⚙️ PageIndex Python SDK
One client, two independent sides. Index decides where your documents live and get processed — on your machine, or in PageIndex Cloud. Chat decides who answers — your own model, or PageIndex’s managed chat.
Local and cloud modes, model naming, storage, backends
Index documents and read their tree structure
Document QA over Chat Completions, Responses, and Messages
Hand PageIndex’s tools to your own agent
Install
pip install -U pageindexQuickstart (local mode)
Index, retrieve, and chat entirely on your machine with your own LLM key. No PageIndex API key required.
import os
from pageindex import PageIndexClient
os.environ["OPENAI_API_KEY"] = "your-openai-key"
client = PageIndexClient(
index="gpt-5.6-luna", # model that builds the tree index
chat="gpt-5.6-sol", # model that searches the tree
)
doc_id = client.submit_document("./2023-annual-report.pdf")["doc_id"]
answer = client.chat(
"What was the 2023 operating margin, and where is it stated?",
doc_id=doc_id,
)
print(answer)Local indexing is synchronous — submit_document returns once the document is ready.
Model recommendations. index= builds the tree index; a basic model is sufficient. chat= searches the tree and answers; use the best model you can afford.
Quickstart (PageIndex Cloud)
With a PageIndex API key , parsing, OCR, image understanding, tree construction, and storage all run in the cloud. The chat side stays yours.
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", # index and store in PageIndex Cloud
chat="gpt-5.6-sol", # your own model answers
)
# Cloud indexing is asynchronous — wait=True blocks until the document is ready
doc_id = client.submit_document("./2023-annual-report.pdf", wait=True)["doc_id"]
print(client.chat("What was the 2023 operating margin?", doc_id=doc_id))See Client Configuration for every combination, model naming, and storage options.
Ask questions
chat() is the one-line surface. Pass a question string or a role/content history, and scope it with one doc_id or a list of them.
client.chat("What changed in the risk factors?", doc_id=doc_id)
# Several documents at once
client.chat("Compare the results across these reports", doc_id=[doc_id_a, doc_id_b])
# Stream the answer as text chunks
for chunk in client.chat("Summarize this document", doc_id=doc_id, stream=True):
print(chunk, end="", flush=True)Underneath is a document-QA agent you can also drive over the protocol your stack already speaks — chat_completions() (OpenAI Chat Completions), responses() (OpenAI Responses), or messages() (Anthropic Messages). See the Chat API reference.
Answers with citations
Ask for inline page-level citations by passing a system message alongside the question:
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 in the document name and page number:
Revenue increased during the reporting period. <cite doc="report.pdf" page="12"/>On PageIndex Cloud’s managed chat, chat_completions(..., enable_citations=True) returns structured line-level citations instead. See Chat API.
List indexed documents
client.list_documents() # everything you have indexedSee Document Processing for the full response shapes.
Local vs. Cloud
| Capability | Local | Cloud (get an API key ) |
|---|---|---|
| Best for | text-heavy PDFs and local workflows | scanned, image-heavy, and large document collections |
| Indexing | runs on your machine | runs in PageIndex Cloud, with production OCR and image understanding |
| Storage | local (storage_path) | managed in PageIndex Cloud |
| Chat model | your model | your model, or the managed chat included with your key |
| Citations | page-level | line-level |
| Image understanding | — | ✅ |
| Multi-document scale | manual | PageIndex File System |
| Folders | — | ✅ |
| MCP server | — | ✅ |
SDK Full Reference
- Client Configuration: modes, models, storage, and backend overrides.
- Document Processing: index documents and read their tree structure.
- Chat API:
chat,chat_completions,responses, andmessages. - Agent Integration: tools and configs for your own agent framework.
- Legacy: OCR and the deprecated retrieval API.