review: the complete v0.2.10 line — agent tools, local chat, Flash default

[rejojer]

PageIndex SDK 0.2.10 adds two things:

1. Agent tools — plug PageIndex document retrieval into any agent framework with one call.
2. Local chat — ask questions about your documents through three standard chat APIs.

Both work in local mode (runs on your machine, with your model keys) and cloud mode (runs on api.pageindex.ai, with a PageIndex API key).

(Review note: this PR holds the complete 0.2.10 diff for review. The code is already on main via #396, #402, and #404. This PR is not meant to be merged; the tools layer's own review record is #393.)

Install

pip install pageindex==0.2.10.dev1                   # 0.2.10 pre-release; plain `pip install pageindex` still gets 0.2.8
pip install "pageindex[openai]==0.2.10.dev1"         # + OpenAI Agents SDK
pip install "pageindex[anthropic]==0.2.10.dev1"      # + Anthropic SDK (tool runner, messages())
pip install "pageindex[claude]==0.2.10.dev1"         # + Claude Agent SDK

The extras only install the framework you choose. The base SDK adds no new dependencies, and everything else works with no extras installed.

Which API key do you need?

One rule: the key belongs to whatever model does the thinking. The PageIndex tools themselves never call an LLM.

What you're doing	Key you need
Index a PDF locally (submit_document)	OPENAI_API_KEY (the default models are OpenAI's)
Local chat: chat_completions() / responses()	OPENAI_API_KEY (default), or your provider's key if you pick another model
Local chat: messages()	ANTHROPIC_API_KEY
Your own agent framework	that framework's own key — the PageIndex tools need none
Cloud client	just api_key="..." from dash.pageindex.ai — no model keys

Put keys in your environment or a .env file. To use a non-OpenAI model anywhere, pass a LiteLLM-style name like anthropic/claude-sonnet-4-6 and set that provider's usual variable. A missing key fails immediately and tells you which variable to set.

Index your first document

from pageindex import PageIndexLocalClient

client = PageIndexLocalClient()                        # or PageIndexCloudClient(api_key="...")
doc = client.submit_document("report.pdf", wait=True)

Local indexing uses PageIndex Flash by default: the tree structure is built from the PDF's layout in seconds, and the LLM only writes node summaries. Pass mode="standard" for the slower, fully LLM-built tree. The CLI works the same way: python run_pageindex.py --pdf_path doc.pdf, with --mode standard to opt out (--optimize full|merge|off for the tree refinement — see pageindex/flash/README.md).

Plug into your agent framework

Pick your framework. One call returns everything it needs — instructions plus tools. Local and cloud clients work identically here.

# — inside your async app; agent frameworks are async-native —
# client and doc from the setup above

# ── OpenAI Agents SDK ──
# pip install "pageindex[openai]"
from agents import Agent, Runner

agent = Agent(**client.openai_agent_config())   # instructions + tools (+ the local model default)
result = await Runner.run(agent, "What was total revenue this quarter, vs last year?")
print(result.final_output)


# ── Anthropic SDK tool runner ──
# pip install "pageindex[anthropic]"
import anthropic

runner = anthropic.AsyncAnthropic().beta.messages.tool_runner(
    **client.anthropic_runner_config(model="claude-sonnet-4-6", asynchronous=True),
    messages=[{"role": "user", "content": "What was total revenue this quarter?"}],
)
final = await runner.until_done()
print(final.content[-1].text)


# ── Claude Agent SDK ──
# pip install "pageindex[claude]"
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

options = ClaudeAgentOptions(**client.claude_agent_config())
async for message in query(prompt="What was total revenue this quarter?", options=options):
    if isinstance(message, ResultMessage):
        print(message.result)


# ── Any other framework — no extras needed ──
tools = client.agent_tools()   # plain functions returning JSON envelopes

Each *_config() helper is shorthand for two explicit calls: agent_instructions() plus as_openai_tools() / as_anthropic_tools() / as_claude_mcp(). Drop to the explicit form when you want to customize. All of these accept doc_id=... to point the agent at specific documents, and include_management=True to also expose document deletion (off by default).

Chat with your documents

Three methods. Each speaks one standard wire format, so the request and the response look exactly like the API you already know. Pass a plain string, or full messages in that protocol's native format.

# client and doc from the setup above

# ── Universal — any OpenAI-compatible backend (ollama, vllm, gateways, compat endpoints) ──
answer = client.chat_completions("What was Q3 revenue?", doc_id=doc["doc_id"],
                                 model="gpt-5.4")   # model optional — defaults to the client's retrieve_model
print(answer["choices"][0]["message"]["content"])


# ── Agentic — backends that speak the Responses API ──
result = client.responses("Which section covers risk factors?",
                          doc_id=doc["doc_id"], model="gpt-5.4")
print(result["output"][-1]["content"][0]["text"])


# ── Claude-native — Anthropic Messages protocol ──
# pip install "pageindex[anthropic]"
reply = client.messages("What was Q3 revenue?",
                        doc_id=doc["doc_id"], model="claude-sonnet-4-6")
print(reply["content"][-1]["text"])

All three also support:

• Streaming — pass stream=True.
• Multi-turn — append the previous reply to your next call's messages, exactly as the protocol specifies, and keep doc_id the same. Provider prompt caching keeps working across turns.
• Document targeting — doc_id restricts the conversation to those documents. The tools enforce it; it is not just a suggestion to the model.

What works where

Bring your own agent — the tools, on every major surface:

Surface	Local	Cloud
agent_tools() — plain functions, any framework	✅ in-process tools	✅ live cloud tool set over MCP
as_openai_tools() / openai_agent_config() — OpenAI Agents SDK	✅	✅ (hosted=True: execution on OpenAI's side, read-only endpoint by default)
as_anthropic_tools() / anthropic_runner_config() — Anthropic SDK tool runner	✅ sync & async	✅ sync & async
as_claude_mcp() / claude_agent_config() — Claude Agent SDK / Claude Code	✅ in-process MCP server	✅ remote MCP config — read-only endpoint by default
Standard MCP, no SDK involved	⬜ stdio entry point (follow-up)	✅ api.pageindex.ai/mcp (read-only: …/mcp?tools=read) — any MCP host, the Anthropic MCP connector, OpenAI hosted MCP

Managed chat — the SDK runs the loop:

Method	Wire format	Engine	Local	Cloud
chat_completions()	OpenAI chatcmpl	openai-agents	✅	✅ hosted endpoint
responses()	OpenAI Responses	openai-agents	✅	⬜ raises — cloud converges toward this later
messages()	Anthropic Messages	anthropic tool_runner	✅	⬜ raises

Local serves four read-only tools: browse_documents, get_document, get_document_structure, get_page_content (remove_document only with include_management=True). Cloud adds search_documents, folders, and get_document_image — discovered live from the server, never frozen into the SDK.

What a run looks like

An actual run (local mode, OpenAI Agents SDK, over examples/documents/q1-fy25-earnings.pdf):

Q: What was Disney's total revenue in Q1 FY2025, and how did it compare to the prior-year quarter? Cite the page you found it on.

[tool] get_document_structure({"doc_name": "q1-fy25-earnings.pdf", "part": 1})
[tool] get_page_content({"doc_name": "q1-fy25-earnings.pdf", "pages": "1,3"})

A: Disney's total revenue in Q1 FY2025 was $24.7 billion, up 5% from $23.5 billion in the prior-year quarter.
Citations — Page 1: "Revenues increased 5% for Q1 to $24.7 billion from $23.5 billion in Q1 fiscal 2024"; Page 3: table shows $24,690M vs $23,549M, +5%.

This is the intended loop: the agent reads the tree structure first, picks tight page ranges, and answers from tool output with page citations. No vector index, no chunking. The retrieval intelligence is your agent's own model — the navigation tools make no LLM calls.

---

Everything below is design rationale and the test record, written for reviewers. You don't need it to use the SDK.

Design — the tools layer

• The tool surface is the cloud MCP contract: browse_documents / get_document / get_document_structure / get_page_content, doc_name-addressed, same input schemas, descriptions, and JSON response envelopes as the hosted MCP server's tools/list — agent prompts port unchanged between the cloud MCP connection and these in-process tools. Adapters hand the contract/server schema to the framework verbatim (FunctionTool(params_json_schema=…), beta_tool(input_schema=…)) — no regeneration from Python signatures, so items/enum/pattern/bounds survive on every surface. tests/data/cloud_mcp_contract.json freezes the contract; a parity test guards drift.
• Local is an honest subset: tools that don't exist locally (folders, search_documents, get_document_image) are not registered, mirroring the server's gating semantics. Cloud-only parameters (folder_id, sort/query, recursive) are hidden from the local surface entirely — strict-schema frameworks then cannot express the dead-end calls, and the call_tool/MCP path still answers direct calls with a guided "works on PageIndex cloud" envelope as the backstop. Local descriptions and instructions teach only that surface: the exposed schema is the contract minus the documented hidden set (mechanically asserted), and a dead-reference test keeps local guidance from naming cloud-only tools. remove_document is off by default, behind include_management=True.
• The management gate is structural wherever possible. The config-handoff surfaces — as_claude_mcp(), as_openai_tools(hosted=True), the raw connector URL — point at the server's read-only endpoint (/mcp?tools=read) by default, so the URL itself is the gate and works identically in every MCP client. The in-process surfaces (agent_tools(), as_openai_tools(), as_anthropic_tools()) expose only tools the server marks readOnlyHint; local withholds remove_document at registration. include_management=True is the one switch that opens the complete list in either mode, on every surface. All four tool exports stay polymorphic: on a cloud client the live tool set — including new server-side tools — arrives without an SDK release.
• Tools never raise, and failures carry the protocol's own error marking — every failure returns the same {"error", "errorCode", "next_steps"} envelope the cloud emits, flagged through each channel that has one (MCP isError propagated, Anthropic tool runner is_error: true via ToolError), so the model can always tell a failed call from data. Destructive calls validate every argument before acting — a rejection envelope means nothing was deleted.
• agent_instructions(doc_id=None) supplies the retrieval playbook for the agent's system prompt. Cloud: the live instructions the MCP server serves for the key's tool set, captured from the initialize handshake over the same bridge session — server-side guidance updates arrive without an SDK release, and an empty server response raises instead of silently substituting. Local: the built-in playbook for the in-process tools, a trimmed subset with a consistency test that every tool it names exists locally. doc_id (str or list) appends the target documents — in the run above it is what let the agent skip discovery.
• Zero new hard dependencies: openai-agents / claude-agent-sdk / anthropic are imported at call time with actionable errors; the [openai] / [claude] / [anthropic] extras carry floor-only pins. import pageindex and every existing feature work with none installed (covered by tests).
• submit_document(wait=True) polls with growing intervals; returns on completed, raises on failed or after 30 minutes — the manual polling loop cloud callers write today spins forever on a failed document.
• Local indexing defaults to Flash with the full optimize pass (deterministic merge, then LLM expand; summaries and expand share summary_model). page_index_flash() takes optimize="full" (default) / "merge" / False; True is accepted as "full" for backward compatibility, unknown values raise instead of silently degrading. The CLI's --mode {flash,standard} replaces --flash (kept as a hidden compatibility alias); standard-only tuning flags now error in flash mode instead of being silently ignored; the missing-key pre-check (litellm.validate_environment, all providers) runs only when an LLM will actually be called. Both modes emit identical output schemas end to end.

Design — chat on the tools

• Basis is industry standards, not the cloud chat endpoint. The cloud /chat/completions quirks (history flattening, bespoke prompt, stateless re-reading, arbitrary caps) are not mirrored; local targets the standard formats and becomes the reference the cloud can later converge toward. responses()/messages() raise on cloud clients until then.
• Passthrough doctrine. Content is never rewritten — the caller's messages, the model's answers, tool outputs, native finish/stop reasons. The SDK owns exactly four things: gatekeeping (structural validation only — no message caps, sampling params pass through), table-setting (thin chat header + the local AGENT_INSTRUCTIONS; caller system content appended, not rejected; the doc_id targeting block leads the conversation and the tool layer enforces it), tool execution (read-only local set, scoped to doc_id), and billing (usage aggregation, envelope ids). Per-run tracing is disabled; prompt-cache routing keys are per-conversation, never pooled across users.
• Engines are the vendors' own loops, never hand-rolled: openai-agents for the two OpenAI protocols (litellm/-prefixed and provider/model names route through the SDK's LiteLLM model, openai/ strips to the OpenAI SDK), the Anthropic SDK's tool_runner for messages() (floor 0.108.0 — the first release whose runner stops at a refusal carrying a tool_use block instead of executing the tool; verified by probing mock transports against 0.84.0 through 0.108.0). Rule of the layer: engines = each vendor's official thin loop; agent hosts (Claude Code et al.) only ever get tools.
• Envelopes report what actually happened. responses() carries the backend's real terminal status/incomplete_details (recorded at the transport layer — the engine discards them), a partial page read names every omitted page, and framework exceptions surface as PageIndexAPIError, never as raw engine types.
• Prompt-cache continuity is a tested contract. Round-tripped history reaches the backend as an item-for-item extension of the previous call's final model input — asserted on both engines against captured payloads. Anthropic's explicit cache_control breakpoints sit on the managed system blocks only.
• enable_citations raises as cloud-only (citations need block-level OCR data local mode does not store).
• messages() resolves its max_tokens default per model (8192, or 4096 for the claude-3 generation), so the simple call needs only a question on any model.

Verification

• 269 tests green (plus 3 skipped without the claude extra and 3 key-gated live tests): tool behavior against a seeded store with no LLM calls; the real chat engines against scripted backends (a Model fake under openai-agents, a mock HTTP transport under the real anthropic SDK); contract parity vs the frozen snapshot; framework-missing/-installed behavior both ways; streaming on all three surfaces; the round-trip prefix-extension assertions on both engines; doc_id scoping, error-marking, and envelope-honesty regressions.
• Live against the real cloud MCP server: agent_tools() and as_anthropic_tools() discovered this key's gated tool set (7 read-only tools; include_management=True adds remove_document); frozen-contract parity letter-for-letter; envelope field parity on the analogous calls; the server serves non-empty initialize.instructions.
• Live against real model backends: OpenAI — chat_completions answered with the structure-first loop; responses round-trip answered the follow-up with zero new tool calls. Anthropic — messages() history was accepted verbatim by the real API, follow-up answered with zero new tool turns, cache_control hit live (cache_read_input_tokens: 1826), native streaming; both the sync and AsyncAnthropic tool runners drove the live cloud tools end-to-end; the Messages API MCP connector reached api.pageindex.ai/mcp server-side (mcp_tool_use/mcp_tool_result in a single call).
• Review record: multiple independent multi-agent review rounds ran over each layer (adversarial runtime probes, claims-vs-code, refactor-equivalence audits, best-practice review against the frameworks' source); every finding was reproduced before being fixed, and deliberate non-changes are documented alongside. The tools layer's rounds are recorded in feat: agent tools — OpenAI Agents SDK, Claude Agent SDK, and any framework, local & cloud #393; the chat and tools-export rounds in this PR's commit messages. A maximum-effort whole-PR review round then ran over this diff — 26 verified findings, 20 fixed in the first pass (d87fa89, b135711, eb1a230), the remainder triaged with rationale. Nine further review rounds followed (commit messages 31c9150 through eebed64), covering argument coercion, protocol terminal states, envelope honesty, provider error containment, CodeQL findings, and SDK dependency floors — each finding reproduced before the fix landed.
• Post-feat: agent tools and local chat for the PageIndex SDK (v0.2.10) #396 fixes carried here (merged to main via fix: post-merge review fixes for v0.2.10 #402/feat: Flash with full optimization becomes the default local indexing mode #404): conformant responses() envelope — official output (model items only) + items (full transcript for round-trip) + usage aggregated across turns, verified against the real OpenAI API; python floor declared >=3.10; stale anthropic>=0.84.0 hints updated to the real 0.108.0 floor; the bridge's binary-stub behavior disclosed on the two image-advertising tool surfaces; _run_sync moved off the except RuntimeError probe so user exceptions stop carrying a phantom "no running event loop" context.

Release gate — satisfied: the default cloud configs point at the read-only MCP endpoint, so VectifyAI/pageindex-chat#448 had to be deployed before 0.2.10 ships (an older server ignores the tools=read parameter and would silently serve the full set behind a URL that promises read-only). Verified live before publishing 0.2.10.dev1: …/mcp?tools=read serves 7 tools without remove_document, …/mcp serves 8 with it.

Follow-ups (not in this PR): an AsyncPageIndexClient twin per the industry dual-client pattern — every layer around the SDK is already async-native (FastAPI server, agent engines, agent frameworks); the async chat path is the engines' native form (drops the sync bridge, streams pass through as async for), and cloud transport gains an httpx track; a stdio pageindex-mcp entry point for non-Python MCP hosts; a public doc_id scope on the BYO tool exports (the chat surfaces already enforce it); the docs-site agent-integration page; cloud /responses·/messages convergence toward these surfaces.

[rejojer]

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 👎.}