Skip to Content
Python SDK

⚙️ 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.

Install

pip install -U pageindex

Quickstart (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 indexed

See Document Processing for the full response shapes.

Local vs. Cloud

CapabilityLocalCloud (get an API key)
Best fortext-heavy PDFs and local workflowsscanned, image-heavy, and large document collections
Indexingruns on your machineruns in PageIndex Cloud, with production OCR and image understanding
Storagelocal (storage_path)managed in PageIndex Cloud
Chat modelyour modelyour model, or the managed chat included with your key
Citationspage-levelline-level
Image understanding
Multi-document scalemanualPageIndex File System
Folders
MCP server

SDK Full Reference

💬 Community & Support

Last updated on