perf: ship inspection data in the agent task to cut steps and tokens

[SkyeAv]

The inner agent spent 2+ LLM steps per article calling pmc_article_context/read_table on files the
supervisor had already downloaded (fleet logs: ~4,600 such calls; 68% of articles exhausted the 20-step
budget at a median 17 steps / 549k tokens). This ships all deterministic inspection output inside the task,
tightens the prescribed workflow, and stops paying for repeated identical builds.

Pre-rendered task context

• Adds render_task_context (src/tablassert/agent.py): the supervisor renders the article summary plus an
  8-row head preview of EVERY candidate table and EVERY Excel worksheet directly into the task text.
• pmc_article_context / read_table stay registered as fallbacks for rows beyond a preview or a preview
  that failed; unreadable tables render a fail-visible note instead of raising, and the block is capped at
  60k chars so a pathological article cannot flood the context.

Leaner prompt + loop

• Rewrites the INSTRUCTIONS workflow to target 4 steps or fewer (derive_config → build_and_audit →
  at most two edit rounds → final_answer); the supervisor's deterministic improve loop continues after the
  agent finishes, so quality ownership does not change.
• Disables periodic re-planning: build_agent now defaults planning_interval=None — each smolagents
  planning turn was a full extra LLM round trip carrying the entire prompt.
• Memoizes identical build_and_audit tool calls per instance via functools.lru_cache(maxsize=16);
  models re-ran unchanged configs despite instructions and each repeat paid a full validate+build+coverage
  pass on a fresh tempdir.

Design

• No CLI surface changes: everything is hardcoded (matching the preference for a minimal tablassert agent
  command), and the schema-gated final answer + supervisor improve loop are untouched, so MAPPED/SKIPPED
  semantics are unchanged.
• Accepted caveat: cached reports point at the first build's tempdir paths, which persist for the process
  lifetime (tempdirs are never cleaned mid-run), so downstream readers stay correct.

Docs

• Updates docs/agent.md: the two-pass wiring of article/table context, the derive-first supervisor flow,
  and the planning-off rationale (em-dash-free, matching docs: remove em-dashes and AI-text tells from READMEs and docs #108).

Testing

• uv run pytest tests/test_agent_speed.py -q → 7 passed (previews incl. multi-sheet Excel, fail-visible
  unreadable table, truncation cap, prompt contract, planner default, cache dedupes identical builds).
• uv run pytest tests/ -q --no-cov → 984 passed, 14 skipped; the one failure + one error
  (test_lib.py::test_compile_subgraph_threads_fine_phases_into_resolve_and_qc, test_qc.py import) reproduce
  on the base commit (missing qc extra in this worktree venv) and are unrelated.
• uv run ruff check . && uv run ruff format --check . → clean; uv run pyright src/tablassert/agent.py tests/test_agent_speed.py → 0 errors.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 60941134-2329-48e0-af28-b19fc8b12f5a

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}