PageIndex: A Tree Index for Reasoning-Based RAG Without Vector Embeddings

The Problem: Similarity Is Not Relevance

Vector-based RAG retrieves by semantic similarity, which fails on long, complex documents. A paragraph that answers a question may share few words with the query, while a superficially similar passage may be irrelevant. PageIndex argues that relevance requires reasoning, not just embedding distance. The project targets professional documents such as financial reports, legal contracts, regulatory filings, technical manuals, and medical literature. These documents have structure, hierarchy, and context that fixed-size chunking destroys. For engineers building question-answering over such corpora, the failure mode is familiar: the retriever returns the wrong section, and the LLM hallucinates an answer from incomplete context. PageIndex proposes a different retrieval unit: the natural section, organized in a tree.

How PageIndex Works: Tree Index and Agentic Search

The core mechanism is a two-step process. First, the index step generates a hierarchical tree structure for each document. The README states that the tree structure is extracted from the document's own layout information, heuristically, without an LLM. The index model only summarizes and refines that structure. This is a key design choice: it avoids the cost and latency of LLM-driven structure generation. Second, the retrieve step uses an LLM to search the tree agentically. The chat model reasons over the tree, deciding which branches to explore, much like a human reader flipping to a section. This replaces a single vector similarity query with a multi-step reasoning process. The result is traceable: the model can cite explicit references, including document name and page number, as shown in the README's citation example.

Getting Started: SDK Client and Local Mode

Installation is a single pip command: `pip install -U pageindex`. The quickstart shows a minimal client setup. You set an OpenAI API key, then create a `PageIndexClient` with two model parameters: `index` for building the tree and `chat` for searching it. The README notes that the index model can be basic, while the chat model should be the best you can afford. You submit a document with `client.submit_document("report.pdf")`, which returns a `doc_id`. Then you call `client.chat("Your question", doc_id=doc_id)` to get an answer. The SDK also supports a local mode, where indexing, retrieval, and chat run entirely on your machine with your own LLM key. You can also point the same client at PageIndex Cloud with an API key. The `storage_path` parameter controls where indexed documents are stored locally. Model names follow LiteLLM's naming convention, so you can use models from various providers, not just OpenAI.

Traceability and Citations: A Concrete Advantage

One of the strongest differentiators is the citation mechanism. The README demonstrates passing a system message that instructs the model to cite only statements supported by tool outputs, using a specific XML-like tag. The model then outputs something like: `Revenue increased during the reporting period. <cite doc="report.pdf" page="12"/>`. This is not a vague reference to a chunk ID; it is a page number in the original document. For professional use cases like financial audits or legal reviews, this traceability is essential. It lets a user verify the answer against the source. Vector RAG often returns opaque results, as the README's comparison table puts it, 'vibe retrieval'. PageIndex's tree structure and reasoning process make the retrieval path explainable, at least in principle, because the model's reasoning can be inspected, though the README does not provide a detailed log of that reasoning.

Limitations and Failure Modes

The most obvious limitation is cost and latency. The chat model must reason over the tree for every query, which is more expensive than a vector similarity search. The README itself acknowledges this by recommending the best model you can afford for chat, implying a trade-off between accuracy and cost. The README mentions a 'Query cost and accuracy' section, but the README does not include its details, so you should consult the docs for specific numbers. Another limitation is dependence on document layout. The tree structure is extracted heuristically from layout information. If a PDF has poor or unusual layout, or is a scanned image without text layers, the heuristic extraction may fail, producing a bad tree. The README does not describe fallback behavior for such cases. Also, the system is designed for long documents; for short, homogeneous text, the overhead of building a tree is unnecessary. Finally, the local mode still requires an LLM API key, so it is not fully offline; you need a provider like OpenAI, and you must manage that dependency.

Alternative Approaches: Vector RAG and Hybrid Systems

The primary alternative is classic vector RAG, where you embed chunks and retrieve by cosine similarity. That approach is cheaper, faster, and works well for short, self-contained text like FAQs or product descriptions. The difference in approach is fundamental: vector RAG uses a fixed, precomputed representation, while PageIndex uses a dynamic, reasoning-based traversal. A hybrid system might combine both: use vector search to narrow candidates, then use LLM reasoning to select the best sections. Some other projects use graph-based indexes or metadata filtering to improve precision. The README's comparison table highlights that vector RAG lacks context, while PageIndex can incorporate conversation history and domain knowledge. But for a team already invested in a vector database, switching to PageIndex means replacing the entire indexing layer, not just adding a reranker.

Maintenance, License, and Upgrade Cost

The project is MIT-licensed, which is permissive and allows commercial use without copyleft obligations. The repository shows active development, with releases v0.2.11 and v0.2.10 in August 2026, and a default branch that is not archived. The README mentions PageIndex Flash, a feature that generates tree structure from PDFs in seconds using heuristic layout extraction, which suggests ongoing performance improvements. However, the project is relatively young, and the API may change between versions. The README shows two spellings for model parameters (`index=` and `index_model=`), indicating that the API is still settling. Upgrade cost includes testing new releases against your document corpus, as tree extraction heuristics may change. Also, the SDK depends on LiteLLM for model naming, so you inherit that dependency's maintenance burden. There is no mention of a migration tool from vector RAG, so adopting PageIndex requires re-indexing all documents from scratch.

Editorial conclusion

Adopt PageIndex if you work with long professional documents like financial reports or legal filings and need traceable, context-aware retrieval without managing a vector database. Do not adopt it if you need high-throughput retrieval on short, homogeneous text, or if you cannot afford LLM inference costs per query. Before committing, verify the index and chat model costs against your query volume, test the local mode with your own documents, and confirm that the tree structure extraction works well on your PDFs' layout. The project is MIT-licensed and actively released, but you should check the latest documentation for model availability and cost benchmarks.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes