Today, we are announcing a major update to the PageIndex SDK: the complete reasoning-based RAG workflow can now run locally.
PageIndex SDK users can now build tree indexes, store documents, run reasoning-based retrieval, and chat with long documents on their own machines. The local workflow uses your preferred LLM and API key, produces page-level citations, and works with the same agent frameworks and model APIs already supported by the SDK.
This is not a separate local product or a new client. It is a major expansion of the existing PageIndex SDK: choose local or cloud indexing when you initialize PageIndexClient
, while keeping the rest of your application workflow consistent.
Install it with one command:
pip install -U pageindex
Local mode is designed for text-heavy PDFs and private development workflows. It uses your own model API key, stores indexes on your machine, and requires no vector database.
Why PageIndex?
Most RAG systems split a document into fixed-size chunks and retrieve them by vector similarity. This approach is useful, but similarity is not the same as relevance.
In long professional documents, the passage that answers a question may use completely different language from the query. A semantically similar passage may also be nearby in meaning while being irrelevant to the actual task. Financial reports, regulations, technical manuals, and textbooks often require context, domain knowledge, and multi-step reasoning to identify the right evidence.
PageIndex takes a different approach. It organizes each document as a hierarchical tree index, then lets an LLM reason through that tree in the same way a human reader uses a table of contents and section structure to find the right pages.
Retrieval happens in two stages:
Index: Build a tree that preserves the document's natural structure.Retrieve: Use LLM-based tree search to identify and read the relevant sections.
<cite doc="report.pdf" page="43"/>
| Vector RAG | PageIndex | |
|---|---|---|
| Index | Vector index | Hierarchical tree index |
| Retrieval unit | Fixed-size chunk | Natural document section |
| Retrieval method | Semantic similarity | Reasoning-based tree search |
| Context | Query embedding | Conversation history and domain knowledge |
| Result | Chunk-level matches | Explicit, traceable references |
PageIndex does not replace one vector database with another. It removes the vector database from the retrieval path entirely.
The Same Client, Now Running Locally
If you have used the PageIndex SDK before, the interface will look familiar. The full local workflow takes only a few lines of Python:
import os
from pageindex import PageIndexClient
os.environ["OPENAI_API_KEY"] = "your-openai-key"
client = PageIndexClient(
index="gpt-5.6-luna",
chat="gpt-5.6-sol",
)
doc_id = client.submit_document("report.pdf")["doc_id"]
answer = client.chat(
"What was the 2023 operating margin, and where is it stated?",
doc_id=doc_id,
)
print(answer)
submit_document()
builds and stores the index. The returned doc_id
can be reused for every later question, so indexing remains a one-time operation.
chat()
is the simplest query interface. It accepts either a string or a role/content message history, making it suitable for direct questions, multi-turn conversations, and custom system instructions.
Page-Level Citations in the Answer
For professional document workflows, an answer is only useful when its evidence can be verified. Local mode can produce machine-readable, page-level citations by passing a system message to client.chat()
:
messages = [
{
"role": "system",
"content": (
'Cite only statements supported by tool outputs using '
'<cite doc="{docName}" page="{pageNumber}"/>'
),
},
{"role": "user", "content": "Summarize the document."},
]
answer = client.chat(messages, doc_id=doc_id)
The model fills the placeholders with the document name and page returned by the retrieval tools:
Revenue increased during the reporting period. <cite doc="report.pdf" page="12"/>
The instruction does two things: it defines a citation format that applications can parse, and it tells the model to cite only statements supported by retrieved evidence. Local mode provides page-level citations, while PageIndex Cloud supports more granular line-level citations.
Fast Local Indexing with PageIndex Flash
The SDK uses PageIndex Flash by default. Flash extracts structure from the PDF's own layout instead of asking an LLM to infer the full outline from scratch. A model is only used to generate node summaries and perform the tree-optimization expansion pass.
This makes local index construction both fast and predictable. In our benchmark setup, indexing costs approximately $0.001 per page with the recommended basic indexing model. A 1,000-page textbook costs a little over one dollar to index once, after which the same tree can serve every question.
Across benchmark documents ranging from 9 to 1,098 pages, indexing completed in approximately 13 seconds to 4.5 minutes.
The tree contains titles, page ranges, summaries, and nested sections. It acts as a table of contents optimized for LLM search while remaining understandable to developers.
Separate Models for Indexing and Retrieval
Index construction and document search have different requirements, so the SDK lets you configure them independently.
- The index model creates node summaries and helps optimize the tree. A basic, cost-efficient model is generally sufficient. - The chat model searches the tree, evaluates relevance, reads evidence, and produces the final answer. Use the strongest model that fits your accuracy and cost requirements.
This separation keeps the one-time indexing cost low without limiting the quality of later retrieval. It also lets you change the chat model without rebuilding the document index.
Model names follow LiteLLM conventions, so the same local client can use OpenAI, Anthropic, OpenRouter, and other supported providers.
Query Cost and Accuracy
The PageIndex OSS Benchmark evaluates the same local setup shown above: PageIndexClient()
with Flash indexing and no OCR.
The benchmark contains 62 lookup questions over 34 PDFs and 1,945 pages drawn from MMLongBench-Doc-V2. Every answer is a fact stated in running text, so an incorrect result represents a retrieval or reading failure rather than an open-ended reasoning disagreement.
Within each model, increasing reasoning effort creates a clear accuracy ladder at a relatively similar cost level. Moving to a larger model can improve the frontier further, but often increases the cost per question by an order of magnitude. This gives teams a practical way to tune deployment: choose a model family for the target budget, then adjust reasoning effort for the required accuracy.
Full results, source documents, and the benchmark runner are available in the benchmark repository.
One SDK for Local and Cloud Workflows
The updated SDK supports both local and PageIndex Cloud workflows through the same client pattern, while each mode remains optimized for different workloads.
| Capability | Local | Cloud |
|---|---|---|
| Best for | Text-heavy PDFs and local workflows | Scanned, image-heavy, and large document collections |
| Indexing | Runs locally | Managed by PageIndex Cloud |
| Storage | Local | Managed cloud storage |
| Chat model | Your model | Your model |
| Citations | Page-level | Line-level |
| Image understanding | — | Included |
| Multi-document scale | Manual | PageIndex File System |
| MCP server | — | Included |
Moving indexing and storage to the cloud only requires a PageIndex API key and one configuration change:
import os
from pageindex import PageIndexClient
os.environ["PAGEINDEX_API_KEY"] = "your-pageindex-key"
os.environ["OPENAI_API_KEY"] = "your-openai-key"
client = PageIndexClient(
index="cloud",
chat="gpt-5.6-sol",
)
doc_id = client.submit_document("report.pdf", wait=True)["doc_id"]
answer = client.chat("What was the 2023 operating margin?", doc_id=doc_id)
The rest of the application can keep the same submit_document()
and chat()
workflow.
Upgrade and Run PageIndex Locally
This major PageIndex SDK update brings the complete reasoning-based RAG workflow to your machine:
- Local tree indexing with PageIndex Flash
- Vectorless, reasoning-based retrieval
- Document chat with your preferred LLM
- Page-level, machine-readable citations
- Provider-native API formats
- Tools and configuration for existing agents
- A compatible path from local development to PageIndex Cloud
Upgrade to the latest version:
pip install -U pageindex
Then submit a PDF and ask your first question. No chunking pipeline, embedding model, or vector database is required.
Fully Open Source
Local mode ships entirely in the open. Flash indexing, reasoning-based tree search, document chat, and page-level citations all live in the PageIndex repository on GitHub, so you can read the retrieval logic line by line, run the whole pipeline offline, and adapt it to your own agent.
Full API details are in the documentation. To try reasoning-based retrieval without installing anything, open PageIndex Chat. To move indexing and storage to the managed path, get a PageIndex Cloud API key.