feat: compact row encoding for run_query/preview_table (v0.31.0)

[flyersworder]

Summary

run_query and preview_table rendered every result row as a JSON object repeating all column names. For a wide result that roughly doubles to triples the token cost of a tool result, for identical information — and because tool results persist in the message history and are re-sent on every subsequent model request, that overhead is paid repeatedly rather than once.

rows is now a list of positional arrays aligned to the columns key that run_query already returned.

Measured, realistic short column names:

shape	dict-per-row	arrays-of-arrays
20 cols × 500 rows	198,003 ch (~49.5k tok)	84,503 (43%)
10 cols × 200 rows	36,783	16,583 (45%)
5 cols × 50 rows	3,920	2,120 (54%)

Closes #44.

Design decisions

The knob is operator-facing, not a model-facing tool argument. Unlike Anthropic's concise/detailed pattern, this drops no information, so the agent has no basis on which to choose — and an input_schema field would cost tokens on every request. create_tools(..., row_format="records") restores the previous rendering.

Arrays-of-arrays, not TSV. TSV is ~9 points smaller but needs hand-written escaping and collapses NULL into the empty string. In a library whose purpose is trustworthy reported numbers, a rendering that cannot distinguish "no value" from "empty value" was rejected.

preview_table gains columns in both renderings, so both result tools share one {columns, rows} envelope. This also closes a real gap: a zero-row preview previously returned {"rows": []} and told the agent nothing about the table's shape.

Validation is eager, at create_tools() wiring time rather than render time, because tool callables are async and their failures surface as agent-visible text. create_pydantic_ai_toolset validates in its own body rather than deferring to its per-run factory, so the guarantee holds on every path.

_render_rows's list(row) coercion is load-bearing. DatabaseAdapter is a @runtime_checkable Protocol, so a third-party adapter may return its driver's row type. dict(zip(...)) tolerated that (it needs only iteration) but json.dumps would route it through default=str and emit a string instead of an array.

Compatibility

The default output shape of two tools changed. Anything parsing rows as a list of dicts must either read positionally (row[columns.index("col")]) or pass row_format="records". Values are unaffected — json.dumps(..., default=str) is unchanged.

One nuance found during review and documented: the two renderings are not informationally identical when column labels collide. SELECT t.id, u.id returns ['id', 'id'], and records' dict(zip(...)) is last-value-wins, so a column silently vanishes. compact preserves both — a second argument for the new default.

Non-goals

No row cap or truncation (require_limit and result_check.max_rows already exist as opt-in contract rules; blocking beats silently truncating). No third format. No model-facing tool argument. No wrapper refactor beyond the one parameter.

Testing

Full suite 812 passed; prek run --all-files (ruff check, ruff format, ty) clean under the newly pinned hooks. Built TDD, red-first, across five reviewed tasks. Both pydantic-ai forwards and the SDK forward are regression-checked by deletion — removing the forward makes its test fail.

🤖 Generated with Claude Code

[flyersworder]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}