agents: contract 0.2.0 — descriptors.json as the single source, capabilities(), acall()

[ShawnChen-Sirius]

What

chdb.agents and its TypeScript twin (chdb-io/chdb-node integrations/agents) had started to drift: the model-visible tool descriptions existed in three hand-written copies (this package's tool_specs(), chdb-node's framework descriptor list, and the tool docstrings in the pending mcp-clickhouse chDB integration), the two bindings counted max_bytes differently, and the only version signal a downstream integration could pin against was __beta__ = True. This PR turns those into contract machinery:

• chdb/agents/descriptors.json is now the single source of the model-visible surface (tool names, description text, argument schemas). tool_specs(dialect="anthropic" | "openai" | "mcp") and capabilities() are generated from it (module-level; ChDBTool.tool_specs() delegates). The file is vendored byte-identical in chdb-node, whose zod schemas are generated from it too (companion PR linked below).
• CONTRACT_VERSION + capabilities() return {contract_version, tools, features}, giving downstream integrations a probeable version/feature surface instead of guessing from the package version. Feature keys: dataframe_query (Python-only), attachments, file_allowlist, max_execution_time, async, streaming (reserved, currently false).
• acall() — async tool dispatch via a worker thread (aquery's twin), so async-first frameworks (AutoGen, Pydantic AI) bind to it instead of each re-implementing a thread-pool wrapper around call().

Cross-binding drift fixes (behavior changes)

• max_bytes now counts UTF-8 bytes of each row's compact JSON. The previous ASCII-escaped character count put the truncation point up to ~2.6× earlier than chdb-node's UTF-16 count on non-ASCII rows — a model-visible split between bindings. CONTRACT.md P3 now names the normative measure.
• A non-numeric cap (max_rows / limit, per-call or constructor) raises a typed ChDBError with type="INVALID_ARGUMENT" instead of a bare ValueError.
• On the model-facing call() envelope path, a JSON null optional argument now means "omitted" (models routinely send null for optional args); the direct method path stays strict.

Conformance fixture

conformance/cases.jsonl gains:

• a header record carrying the fixture's contract_version — each binding's runner asserts it equals its own CONTRACT_VERSION, so a stale vendored fixture fails loudly;
• capability gating via "requires": "<feature>" — dataframe_query gets its first fixture coverage (runs on Python, auto-skipped by the TypeScript runner);
• new cases for every behavior above.

Tests

python -m pytest tests/test_agents_chdbtool.py tests/test_agents_conformance.py — 31 passed (21 conformance cases + unit tests for the dialects, version/descriptor parity, acall(), and argument validation).

Companion chdb-node PR: chdb-io/chdb-node#70

🤖 Generated with Claude Code

Note

Add contract 0.2.0 to chdb agents with descriptors.json, capabilities(), and acall()

• Makes descriptors.json the single source of truth for tool surface (run_select_query, list_databases, list_tables, etc.) and introduces CONTRACT_VERSION = "0.2.0" in descriptors.py, exported via chdb.agents.
• Adds capabilities() returning {contract_version, tools, features} and tool_specs(dialect) supporting anthropic, openai, and mcp dialects with typed INVALID_ARGUMENT errors for unknown dialects.
• Hardens ChDBTool.__init__ to probe (not mutate) caller-provided sessions, raising CONFIG_MISMATCH when readonly state mismatches, and snapshots engine table functions for precise file-allowlist gating.
• Rewrites allowlist enforcement in _enforce_allowlist using masked SQL scanning via find_source_calls; non-literal source arguments and out-of-allowlist paths now raise ACCESS_DENIED; dataframe_query is exempted via _permit_fns={'python'}.
• Adds acall() as an async wrapper around call(), and call() now returns typed error envelopes for malformed/non-dict argument payloads instead of raising.
• Risk: session construction now fails with CONFIG_MISMATCH if a caller-provided session is not in the expected readonly mode, which is a breaking change for callers that relied on silent mode coercion.

^{Macroscope summarized 61684f8.}

[ShawnChen-Sirius]

@chibugai, review it

[Copilot]

Pull request overview

Aligns chdb.agents with a versioned “agent tool contract” by making descriptors.json the single source of truth for the model-visible tool surface, adding a probeable capabilities/version API, and introducing async tool dispatch (acall) to reduce cross-binding drift and simplify downstream integrations.

Changes:

• Add contract machinery: descriptors.json → generated tool_specs(dialect=...), plus CONTRACT_VERSION and capabilities().
• Add async tool dispatch via ChDBTool.acall() and tighten numeric cap validation to raise typed INVALID_ARGUMENT.
• Extend conformance fixture/runner to include a header with contract_version, capability-gated cases, and new behavior cases (UTF-8 max_bytes, null optional args on envelope path).

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_agents_conformance.py	Updates conformance runner to support fixture headers and capability-gated cases; adds dataframe_query invocation.
tests/test_agents_chdbtool.py	Adds unit tests for dialect generation, contract version/capabilities, descriptor/dispatch parity, and acall().
pyproject.toml	Ships agents/descriptors.json in package data.
chdb/agents/tool.py	Adds _int_arg typed validation, UTF-8 max_bytes counting, generated tool specs delegation, and acall().
chdb/agents/descriptors.py	New module to load descriptors.json, generate dialect tool specs, and expose contract capabilities/version.
chdb/agents/descriptors.json	New single-source contract file defining tool names/descriptions/param schemas and contract_version.
chdb/agents/CONTRACT.md	Documents contract v0.2.0, descriptors.json as the single source, capabilities probing, async semantics, and normative max_bytes rules.
chdb/agents/conformance/README.md	Documents fixture header record, capability gating, and dataframe_query case format.
chdb/agents/conformance/cases.jsonl	Adds header record, new conformance cases for UTF-8 max_bytes, typed invalid caps, null optional args, and dataframe_query gating.
chdb/agents/init.py	Re-exports CONTRACT_VERSION, capabilities, tool_specs, and load_descriptors as part of the public surface.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chibugai]

@ShawnChen-Sirius Reviewed at 0dbd6dc — OCR deep pass (opus-4-8, deterministic ruleset + LLM agent, --max-tools 40) over the diff: no findings. Manual read agrees. What I specifically verified:

• max_bytes UTF-8 accounting — checked the arithmetic on p3_maxbytes_utf8: {"s":"汉字汉字汉字"} is 26 UTF-8 bytes/row compact, so cap 60 keeps exactly 2 of 5 rows. Under the old ensure_ascii counting the same row is 44 chars → 1 row, so the fixture genuinely locks the new behavior (fails on old code).
• _int_arg typed-error flow — direct method path raises INVALID_ARGUMENT; envelope path surfaces the same type via except ChDBError → e.to_dict(). Both covered by the new conformance cases.
• p2_empty_database_rejected — _qualify treats only None as "unqualified"; "" flows into quote_ident() and is rejected, reaching the envelope as TOOL_ERROR. Matches the fixture.
• Envelope-only null-means-omitted — confined to call(); direct method path stays strict, as documented.
• acall() / asyncio.to_thread — needs Python ≥ 3.9; fine with requires-python = ">=3.9" and the existing aquery precedent.
• Packaging — agents/descriptors.json added to [tool.setuptools.package-data], so wheel installs ship the single-source file the module reads at import-adjacent time.

Local verification: ran tests/test_agents_chdbtool.py + tests/test_agents_conformance.py on Linux x86_64 (Python 3.12, chdb-core 26.5.0 engine): 31/31 pass, including the capability-gated optional_dataframe_query.

Copilot's two nits (lenient header detection in _load_fixture, load_descriptors() returning the cached object un-copied) are valid but minor — your call whether to address them here. No blocking findings from me; no inline comments to add.

Scope note: this review covers this PR only, not the companion chdb-io/chdb-node#70.