项目文件夹

0
Ray fc2dc41c16 Client instructions: a standing persona for every answer surface (#497)
* Client instructions: a standing persona for every answer surface

PageIndexClient(instructions=...) sets standing guidance for the answering
agent — persona, language, format — appended after the managed system
prompt wherever an answer is produced: chat() and chat_completions() on
both engines, the Responses and Messages protocol lanes, agent_instructions()
and the three *_agent_config() bundles. It is a client-level argument like
mode=, not a chat-side spelling: it combines with any chat= and never
selects own-model chat on its own. Blank configures nothing, as
chat(instructions="") does. chat(instructions=) adds to it per call; the
prompt order is managed base, client, call, history system rows.

One insertion point serves every own-model surface (_base_instructions).
The managed cloud chat takes exactly one system message, first: the
client's instructions, the call's, and the history's system rows now fold
into it, in that order — so chat(instructions=) works on a managed client
(refused since #460, although the endpoint has accepted custom
instructions since Sep 1), and a system row anywhere in the history no
longer 400s. The answer lane's messages contract is the same on both
engines: text history only — the endpoint refuses tool rows and
structured content itself; the SDK says so first, with the protocol-lane
pointer.

Live-verified against the production managed chat and the live MCP
instructions.

Claude-Session: https://claude.ai/code/session_01J8fbpdM5pz2JLjiNY11usy

* Managed fold: always send the canonical history

The managed payload is now the same shape every time — one leading
system row when there is any system text, then the role/content history —
instead of forwarding the caller's list untouched when nothing folded. That
branch let a blank system row sit mid-history and reach the endpoint's
"only one system message, first" refusal; blank text now configures
nothing, like a blank instructions= does.

Claude-Session: https://claude.ai/code/session_01J8fbpdM5pz2JLjiNY11usy

* Managed fold: lift system rows only, forward the rest verbatim

The managed chat_completions lane ran the whole payload through the
own-model validator: tool rows, structured content and tuples were
refused before the wire, and every field beyond role/content was
stripped (tool_calls, name, the endpoint's own citations). The SDK is
a thin skin over the cloud. It folds the client's instructions and the
history's system/developer rows into the one leading system row the
endpoint takes, and sends everything else as given; the endpoint
decides what it accepts.

Also:
- _managed_instructions drops blank system texts, as the managed fold
  and _anthropic_system already do, so both engines build the same
  prompt for the same input (and share one prompt-cache key).
- An end-to-end test drives chat() on the own-model lane and asserts
  the persona and the call's system text reach the model; the
  white-box builder tests alone stayed green with the persona removed
  from the answer lane.
- as_claude_mcp(): the MCP-instructions channel carries the tool
  guidance only; the client's instructions ride system_prompt.
- Comments that restated code or an assertion removed; the chat=
  combination test asserts chat_model too. Blank instructions
  configure nothing at the constructor, as chat(instructions="") does.

Claude-Session: https://claude.ai/code/session_01TgdXZx63aMwrpaKFTQFFKx

* Chat history: normalize the container, validate only what the SDK reads

Both lanes now take any iterable of message dicts. chat()'s instructions
prepend expanded only lists, so a tuple or generator on the managed lane
silently dropped the call's instructions once _require_own_chat no longer
refused it; own-model rejected the same shapes outright. list() once at
each reader instead. None and other non-iterables fail with Python's own
TypeError, as in the OpenAI SDK.

_system_text refuses a system row carrying non-text parts instead of
keeping the text parts and dropping the rest: the SDK folds that row into
its own system text, so it is the reader and must say what it could not
read. The endpoint stays the authority on every row the fold leaves in
place.

Restore the messages docstring sentence 108875b rewrote: tool-role turns
are rejected on both engines (the endpoint 400s them), so the managed
lane does not take them "verbatim"; rename the test that carried that
claim. Cover the blank-text filter, which no test guarded, and drop a
truncated comment.

Claude-Session: https://claude.ai/code/session_01UBpLu7TJUvrvLvFacs8WYT

* fix: ctor type error names the answer, not a lane managed clients cannot use

A plain managed client is the caller most likely to pass Messages-style
blocks as instructions=, and the old message sent it to
chat(protocol="messages"), which that same client refuses. Say "pass
text", and make the block pointer the exact working call: model= is
required on that lane, and it needs a chat_model= client.

Claude-Session: https://claude.ai/code/session_018od4o3YBqrny2vzGhrX4q5

* Rebase onto the merged lanes: two pins the lift and the targeting move void

The chat_completions protocol lane's guard test still pinned the managed
refusal of instructions=, which this branch lifts on purpose; its own
managed-fold tests cover what the lane now does. And _anthropic_system
lost its doc_id argument when targeting moved to the first user message,
so the prompt-order assertion calls it with what it takes.
2026-09-10 20:05:27 +08:00
2026-03-27 03:30:13 +08:00
2026-08-31 02:41:09 +01:00
2025-04-01 18:54:08 +08:00
2026-09-10 11:30:22 +01:00

pi_github_banner_low

VectifyAI%2FPageIndex | Trendshift

PageIndex: Vectorless, Reasoning-based RAG

Reasoning-based RAG  ◦  No Vector DB, No Chunking  ◦  Context-Aware Retrieval  ◦  Reads Like a Human

🌐 Website  •   ☁️ Cloud  •   📖 Docs  •   📝 Blog  •   ✉️ Contact 

Updates

  • [Aug '26] 🔥 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.
  • [Aug '26] PageIndex Flash: fast tree index generation for text-based PDFs, now the default indexing method in PageIndex SDK local mode.
  • Scale PageIndex to Millions of Documents: PageIndex File System is a file-level tree indexing layer that lets PageIndex reason over an entire corpus, not just a single document.
  • PageIndex App: a human-like document analysis agent for long professional documents.

What is PageIndex?

Are you frustrated with vector database retrieval accuracy for long and complex documents? Vector-based RAG retrieves by semantic similarity. But similarity ≠ relevance — what retrieval actually needs is relevance, and relevance requires reasoning. On professional documents that demand contextual understanding, domain expertise, and multi-step reasoning, similarity search misses what is relevant but not similar, and returns what is similar but not relevant.

Inspired by AlphaGo, PageIndex replaces the vector index with a hierarchical tree index and lets an LLM reason its way through it, the way a human expert turns to and reads the right section of a long report. Retrieval happens in two steps:

  1. Index: generate a tree-structure index for each document
  2. Retrieve: agentically search that tree with LLM reasoning

TL;DR

PageIndex is a vectorless, reasoning-based RAG engine that mirrors how humans read, delivering traceable, explainable, and context-aware retrieval, with no vector DBs or chunking.

Compare with Vector RAG

Vector RAG PageIndex
Index vector index tree index
Retrieval semantic similarity search LLM reasoning over the tree
Result opaque, “vibe retrieval” traceable to explicit references
Context query embedding only full context: conversation history, domain knowledge, etc.

It is ideal for financial reports, legal documents, regulatory filings, technical manuals, medical literature, academic textbooks, and any other long, complex professional document.

Quickstart

pip install -U pageindex
import os
from pageindex import PageIndexClient

os.environ["OPENAI_API_KEY"] = "your-openai-key"

client = PageIndexClient(
    index="gpt-5.6-luna",               # model to build the tree index
    chat="gpt-5.6-sol",                 # model to search the tree
)
doc_id = client.submit_document("report.pdf")["doc_id"]

answer = client.chat("What was the 2023 operating margin?", doc_id=doc_id)
print(answer)

Model Recommendations

  • index=: a basic model is sufficient. The tree structure itself is extracted from the document layout without an LLM; the index model only summarizes and refines it, which a basic model does well.
  • chat=: use the best model you can afford. The chat model searches the tree to retrieve information. See Query cost and accuracy.

Use PageIndex through the SDK client →

Configure other models, streaming, multi-document search, citations, and more.

Integrate PageIndex with your own agent →

Drop PageIndex tools into the OpenAI Agents SDK, the Claude Agent SDK, or any other framework.

Benchmarks

Local indexing cost and time

Building a tree locally runs about $0.001 per page with gpt-5.6-luna as the index model, so a 1,000-page textbook costs a little over a dollar and a few minutes, once, and every later question reuses it. PageIndex is designed not to rely heavily on the model used at index time, so in our experiments a basic model does not hurt quality.

Indexing cost against document length, log-log, for nine PDFs from 9 to 1,098 pages. Points track a $0.0011-per-page reference line; the spread around it is text density, not length.

Indexing time also scales predictably with document length. In the same local setup, the benchmark documents (9 to 1,098 pages) finished in roughly 13 seconds to 4.5 minutes.

Indexing time against document length, log-log, for nine PDFs from 9 to 1,098 pages. The measured indexing times range from about 13 seconds to 4.5 minutes and increase predictably with document length.

Query cost and accuracy

PageIndex-OSS-Benchmark measures exactly the setup in the quickstart above (PageIndexClient() in local mode, flash indexing, no OCR) on 62 lookup questions over 34 PDFs (1,945 pages) drawn from MMLongBench-Doc-V2. Every question's answer is a fact stated in running text, so a wrong answer is a retrieval or reading failure, not a reasoning one.

Accuracy against average cost per question. Each model forms a near-vertical reasoning-effort ladder; moving between models costs an order of magnitude a step.

Full results, data, and the runner are in the benchmark repo.

Cost per query vs. native PDF input

The alternative to retrieval is handing the model the whole PDF on every question. That cost grows with the document; PageIndex's does not, because it reads only the nodes its reasoning reaches. On documents where both routes return the same answer, native PDF input costs 2.1× more at 52 pages and 16.6× more at 420 (gpt-5.6-sol, prompt caching excluded) — and at 805 pages the document no longer fits in the context window at all.

Cost per query relative to PageIndex retrieval, for five PDFs from 52 to 805 pages. Passing the PDF natively costs 2.1x, 3.4x, 7.8x, and 16.6x more at 52, 85, 198, and 420 pages; at 805 pages it exceeds the model's context window.

Leading accuracy on FinanceBench

PageIndex reached a state-of-the-art 98.7% accuracy on FinanceBench (financial document QA benchmark), vastly outperforming vector-based RAG.

Explore the full FinanceBench evaluation results and the blog post.

PageIndex Cloud

The open-source version is ideal for text-heavy PDFs and local workflows. With PageIndex Cloud, document indexing and storage run in the cloud: PageIndex handles parsing, OCR, image understanding, tree-index construction, and managed storage for you. The chat and retrieval layer remains compatible with your model, so you can search the cloud-hosted index using the model provider your application already uses.

Moving indexing and storage from Local to Cloud only requires a PageIndex API key:

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",                       # build and store the index in PageIndex Cloud
    chat="gpt-5.6-sol",                  # use your preferred compatible model for chat
)
doc_id = client.submit_document("report.pdf", wait=True)["doc_id"]
print(client.chat("What was the 2023 operating margin?", doc_id=doc_id))
Capability Local (this repo) Cloud (get an API key)
Best for text-heavy PDFs and local workflows scanned, image-heavy, and large document collections
Indexing runs locally runs in PageIndex Cloud, with production OCR and image understanding
Storage local 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
MCP server

More About PageIndex Cloud

Ready to Try It?

For dedicated deployment (VPC or on-premises), contact us or book a demo.


Support Us

Leave us a star 🌟 if you like our project. Thank you!

Please cite this work as:

Mingtian Zhang, Yu Tang and PageIndex Team,
"PageIndex: Next-Generation Vectorless, Reasoning-based RAG",
PageIndex Blog, Sep 2025.
Or use the BibTeX citation.
@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},
}

© 2026 PageIndex AI

pageindex-wordmark-animated-288-warm