Use built-in chat() to ask questions about your documents with your preferred LLM.

1. Set up the PageIndex client — choose your index mode and LLM.
2. Send a query — prepare messages and select documents.
3. Customize the response — enable streaming and citations.

Set up the PageIndex client

Both sides need configuring: index decides where documents are processed and stored, chat is the model that searches the tree and writes the answer.

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
)

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
)

client = PageIndexClient(
    index="cloud",
    chat="gpt-5.6-sol",
    instructions="You are ACME's support assistant. Answer in the user's language.",
)

Use an existing document ID from client.list_documents(), or submit a new document. wait=True blocks until it is ready:

doc_id = client.submit_document("./2023-annual-report.pdf", wait=True)["doc_id"]

The examples above use OpenAI. Any provider works — see Use different LLMs.

Send a query

Start with a question string or a list of conversation messages.

messages = "What are the key findings in this document?"

messages = [
    {"role": "user", "content": "What is the main topic of this document?"},
    {"role": "assistant", "content": "..."},
    {"role": "user", "content": "What solutions does it propose?"},
]

Then choose the documents or folder and send messages:

answer = client.chat(messages, doc_id=doc_id)

answer = client.chat(
    messages,
    doc_id=["pi-abc123def456", "pi-abc123ghi789"],
)

answer = client.chat(messages, folder_id="my-folder-id")

Streaming

Streamed answers show the agent’s process by default — thinking and tool calls woven into the text as it runs:

for chunk in client.chat("Summarize this document", doc_id=doc_id, stream=True):
    print(chunk, end="", flush=True)

[thinking] I should read the report's key sections first.

[tool_call] get_document_structure {"doc_name": "report.pdf"}
[tool_result] get_document_structure: {"success": true, ... (+304 chars)

The report finds that ...

Use show_process=False to stream only the answer.

To customize the process output, pass a dict to show_process:

client.chat("...", doc_id=doc_id, stream=True, show_process={"thinking": False})

Citations

Pass citations=True to request source citations. Citations use <cite doc="…" page="…"/> tags, with block="…" where the cloud document has block-level data:

answer = client.chat("Summarize the document.", doc_id=doc_id, citations=True)

Revenue increased during the reporting period. <cite doc="report.pdf" page="12"/>

With your own chat model, choose a citation format using client.citation_prompt(format=...):

Pass the returned prompt as instructions=:

answer = client.chat(
    "Summarize the document.",
    doc_id=doc_id,
    instructions=client.citation_prompt(format="markdown"),
)

API protocols

Use protocol= to return a protocol’s native response format. With stream=True, the response is its native event stream.

response = client.chat(
    "Summarize this document",
    doc_id=doc_id,
    protocol="chat_completions",
)
print(response["choices"])

response = client.chat(
    "Summarize this document",
    doc_id=doc_id,
    protocol="responses",
)
print(response["output"])

response = client.chat(
    "Summarize this document",
    doc_id=doc_id,
    protocol="messages",
    model="claude-opus-5",
)
print(response["content"])

show_process does not apply when protocol is set. Pass provider-specific fields such as thinking and top_k through extra_body.

chat() parameters

The following parameters apply to client.chat().