bae359e3bf
The execute_code description gains the toc.json node shape, the patterns the evals put into the analysis instructions (one list_documents call to map a title to an id, files carry no source, toc before search for a known document, doc_item_refs are items self_refs, chunk ids join files and are not citations) and the sandbox's read-only, no-network, time-limit and output facts, which the analysis instructions now state too. The skill gains pictures as images, image search when offered, and citing chunk metadata locators. docs/mcp.md lists the interpreter's limits under Code. pydantic-monty>=0.0.23 brings collections, itertools, functools, dataclasses, function decorators and str.format into the sandbox; every layer names the same modules, and a test imports them. Monty now caps host callbacks per checkout at 1000 by default; the sandbox raises it out of reach, since the time budgets govern.
59 lines
3.5 KiB
Markdown
59 lines
3.5 KiB
Markdown
# Analysis Capability
|
|
|
|
`AnalysisCapability` adds search, citations, and sandboxed Python computation over the document corpus. Use it for counts, aggregation, comparison, structural traversal, and section-scoped reading.
|
|
|
|
It is deferred by default, keeping its substantial instructions and tool schemas out of context until the model chooses to load it.
|
|
|
|
The default request limit is 30 model requests per question. Override it with `create_capability(request_limit=...)`, or set `request_limit=None` to disable it. As with the RAG capability, `create_capability(vision=...)` overrides the image-attachment gate, defaulting to the configured analysis model's `vision` flag. At the limit, `analysis_search` and `analysis_execute_code` are removed while `analysis_cite` remains for two further requests that call an analysis tool, so the model can register citations before answering from gathered evidence. Requests spent on other capabilities do not count against that window. Other agent and capability tools remain available, and the budget resets for every agent run.
|
|
|
|
When `qa.max_searches` or `analysis.max_executions` runs out, the exhausted tool keeps failing rather than disappearing, and the instructions name it on every following request. Searching from inside `analysis_execute_code` does not count against `qa.max_searches`.
|
|
|
|
## Tools
|
|
|
|
| Tool | Purpose |
|
|
|---|---|
|
|
| `analysis_search(query, limit?)` | Search the corpus for evidence. |
|
|
| `analysis_execute_code(code)` | Run Python against the virtual document filesystem. |
|
|
| `analysis_cite(chunk_ids)` | Register retrieved or filesystem-derived chunk IDs. |
|
|
|
|
The sandbox exposes documents under `/documents/{document_id}/` with `metadata.json`, `content.txt`, `items.jsonl`, `chunks.jsonl` (chunk ids with their metadata) and `toc.json`. In code, `await search()` results carry `chunk_meta` and `await list_documents()` rows carry `metadata`. The interpreter's limits and the per-call budgets are listed under [MCP, Code](../mcp.md#code).
|
|
|
|
## Compose an agent
|
|
|
|
Register it on its own, not alongside `RAGCapability`: it already searches and cites,
|
|
and the two together give the model duplicate tools and separate budgets. See
|
|
[Capabilities](index.md#compose-an-agent).
|
|
|
|
```python
|
|
from pydantic_ai import Agent
|
|
from haiku.rag.capabilities.analysis import create_capability as analysis
|
|
from haiku.rag.capabilities.compaction import create_capability as compaction
|
|
from haiku.rag.capabilities.policy import create_capability as citation_policy
|
|
|
|
agent = Agent(
|
|
"openai:gpt-5",
|
|
capabilities=[
|
|
analysis(db_path="my.lancedb"),
|
|
compaction(),
|
|
citation_policy(),
|
|
],
|
|
)
|
|
```
|
|
|
|
For the high-level convenience API:
|
|
|
|
```python
|
|
from haiku.rag.client import HaikuRAG
|
|
|
|
async with HaikuRAG("my.lancedb") as client:
|
|
result = await client.analyze("Which quarter had the highest revenue?")
|
|
print(result.answer)
|
|
```
|
|
|
|
## State
|
|
|
|
When dependencies expose a state dictionary, `AnalysisState` is stored under `"analysis"`. It contains the document filter, code execution log, searches, citations, and the `evidence` record of what was retrieved and cited per question. Searches and executions are cleared when a new question starts, and a resumed question keeps them; the filter, citation index and evidence record persist.
|
|
|
|
This capability does not alter the message history either. Register the [compaction capability](compaction.md) to compact earlier questions.
|
|
|
|
The capability lazily opens both LanceDB and the sandbox only after it is loaded and a tool requires them. Resources close at the end of the agent run.
|