• [2026/08] 🔥 PageIndex SDK — pip install -U pageindex now ships local mode: index, retrieve, and chat entirely on your machine with your own LLM key, or point the same client at PageIndex Cloud with an API key.
• [2026/08] ⚡ PageIndex Flash — tree structure generation from PDFs in seconds, with structure extracted heuristically instead of by an LLM.
• PageIndex Chat — a human-like document analysis agent for long professional documents. Also available via MCP or API.

⚙️ Step 1: Initialize the client

Create a local client and choose the models used for indexing and retrieval:

from pageindex import PageIndexClient
import os

client = PageIndexClient(
    index_model="gpt-5.6-luna",
    chat_model="gpt-5.6-sol",
    storage_path=".pageindex",
)

• index_model builds the tree index. A basic model is sufficient.

• chat_model searches the tree and answers questions. Use the best model you can afford.

• storage_path specifies where indexed documents are stored locally.

Model naming conventions

Model names follow LiteLLM's naming convention. Choose the format that matches your provider:

OpenAI — use the model name directly and set OPENAI_API_KEY:

os.environ["OPENAI_API_KEY"] = "your-openai-api-key"
chat_model = "gpt-5.6-sol"

Anthropic — prefix the model name with anthropic/ and set ANTHROPIC_API_KEY:

os.environ["ANTHROPIC_API_KEY"] = "your-anthropic-api-key"
chat_model = "anthropic/claude-sonnet-4-6"

OpenRouter — prefix the provider and model name with openrouter/ and set OPENROUTER_API_KEY:

os.environ["OPENROUTER_API_KEY"] = "your-openrouter-api-key"
chat_model = "openrouter/anthropic/claude-sonnet-4-6"

For model names and API key settings for other providers, see the LiteLLM provider documentation.

🌲 Step 2: Build the tree index

submit_document defaults to Flash indexing: the structure is extracted from the PDF's own layout (no LLM), and a model is called only for node summaries and the tree-optimization expansion pass. It takes seconds.

doc_id = client.submit_document("report.pdf")["doc_id"]

Inspect what you got:

tree = client.get_document_structure(doc_id)    # titles, page ranges, summaries — no text
client.list_documents()                         # everything you have indexed

A PageIndex tree looks like this — a table of contents optimized for LLMs and agents:

{
  "title": "Financial Stability",
  "node_id": "0006",
  "start_index": 21,
  "end_index": 22,
  "summary": "The Federal Reserve ...",
  "nodes": [
    {
      "title": "Monitoring Financial Vulnerabilities",
      "node_id": "0007",
      "start_index": 22,
      "end_index": 28,
      "summary": "The Federal Reserve's monitoring ..."
    },
    {
      "title": "Domestic and International Cooperation and Coordination",
      "node_id": "0008",
      "start_index": 28,
      "end_index": 31,
      "summary": "In 2023, the Federal Reserve collaborated ..."
    }
  ]
}

See more example documents and generated tree structures.

💬 Step 3: Ask questions

chat() is the one-line surface. Underneath it is a document-QA agent, and you can talk to it over whichever protocol your stack already speaks:

Get a simple answer with chat():

client.chat("What changed in the risk factors?", doc_id=doc_id)

Pass a string or role/content history and get the answer back.

Stream the answer:

client.chat(question, doc_id=doc_id, stream=True)

Returns the answer as text chunks.

Use the OpenAI Chat Completions format:

client.chat_completions(messages, doc_id=doc_id)

Returns the full envelope, including token usage, streaming metadata, and finish_reason.

Use the OpenAI Responses format:

client.responses("...", doc_id=doc_id, reasoning={"effort": "high"})

Returns the agent's process transcript in items. Append those items to the next call's input to preserve memory and benefit from provider prompt caching. This requires a Responses-compatible backend in local mode.

Use the Anthropic Messages format:

client.messages("...", model="claude-sonnet-4-6", doc_id=doc_id)

Uses Anthropic's native Messages API and tool runner. Install it with pip install 'pageindex[anthropic]'.

Pass a list of ids to doc_id to search several documents at once, and keep it identical across a conversation's calls.

🤖 Integrate PageIndex with your own agent

Instead of calling PageIndex's agent, hand PageIndex's tools to yours. One call fills every slot:

OpenAI Agents SDK:

from agents import Agent, Runner

agent = Agent(**client.openai_agent_config(doc_id=doc_id))
result = Runner.run_sync(agent, "Summarize the auditor's concerns.")

openai_agent_config() provides the instructions and tools required by an OpenAI agent.

Anthropic SDK tool runner:

runner = anthropic_client.beta.messages.tool_runner(
    **client.anthropic_runner_config(model="claude-sonnet-4-6", doc_id=doc_id),
    messages=[{"role": "user", "content": "Summarize the auditor's concerns."}],
)

anthropic_runner_config() configures Anthropic's native tool runner. Install the integration with pip install 'pageindex[anthropic]'.

Claude Agent SDK:

options = ClaudeAgentOptions(**client.claude_agent_config(doc_id=doc_id))

claude_agent_config() creates the options for the Claude Agent SDK. Install the integration with pip install 'pageindex[claude]'.

Other agent frameworks:

tools = client.agent_tools()

agent_tools() returns plain Python functions that work with LangChain, PydanticAI, and other agent frameworks.

Each *_config helper is sugar over the explicit pieces — client.agent_instructions() for the system prompt and client.as_openai_tools() / as_anthropic_tools() / as_claude_mcp() for the tools — so you can swap in your own prompt whenever you need to. Locally, doc_id is enforced at the tool layer, not just prompted: out-of-scope lookups return NOT_FOUND.

@article{zhang2025pageindex,
  author = {Mingtian Zhang and Yu Tang and PageIndex Team},
  title = {PageIndex: Next-Generation Vectorless, Reasoning-based RAG},
  journal = {PageIndex Blog},
  year = {2025},
  month = {September},
  note = {https://pageindex.ai/blog/pageindex-intro},
}