pageindex 0.3.0.dev0__tar.gz → 0.3.0.dev2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/PKG-INFO +106 -30
  2. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/README.md +99 -28
  3. pageindex-0.3.0.dev2/pageindex/__init__.py +64 -0
  4. pageindex-0.3.0.dev2/pageindex/agent.py +168 -0
  5. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/backend/cloud.py +211 -86
  6. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/backend/local.py +110 -20
  7. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/backend/protocol.py +20 -7
  8. pageindex-0.3.0.dev2/pageindex/client.py +329 -0
  9. pageindex-0.3.0.dev2/pageindex/cloud_api.py +283 -0
  10. pageindex-0.3.0.dev2/pageindex/collection.py +138 -0
  11. pageindex-0.3.0.dev2/pageindex/config.py +165 -0
  12. pageindex-0.3.0.dev2/pageindex/errors.py +44 -0
  13. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/index/page_index.py +53 -53
  14. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/index/page_index_md.py +1 -4
  15. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/index/pipeline.py +41 -32
  16. {pageindex-0.3.0.dev0/pageindex → pageindex-0.3.0.dev2/pageindex/index}/utils.py +467 -272
  17. pageindex-0.3.0.dev2/pageindex/page_index.py +15 -0
  18. pageindex-0.3.0.dev2/pageindex/page_index_md.py +38 -0
  19. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/parser/markdown.py +32 -3
  20. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/parser/pdf.py +8 -10
  21. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/parser/protocol.py +5 -2
  22. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/retrieve.py +8 -5
  23. pageindex-0.3.0.dev2/pageindex/storage/protocol.py +43 -0
  24. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/storage/sqlite.py +58 -30
  25. pageindex-0.3.0.dev2/pageindex/tokens.py +11 -0
  26. pageindex-0.3.0.dev2/pageindex/types.py +32 -0
  27. pageindex-0.3.0.dev2/pageindex/utils.py +14 -0
  28. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pyproject.toml +4 -1
  29. pageindex-0.3.0.dev0/pageindex/__init__.py +0 -40
  30. pageindex-0.3.0.dev0/pageindex/agent.py +0 -93
  31. pageindex-0.3.0.dev0/pageindex/client.py +0 -161
  32. pageindex-0.3.0.dev0/pageindex/collection.py +0 -69
  33. pageindex-0.3.0.dev0/pageindex/config.py +0 -22
  34. pageindex-0.3.0.dev0/pageindex/errors.py +0 -28
  35. pageindex-0.3.0.dev0/pageindex/index/legacy_utils.py +0 -2
  36. pageindex-0.3.0.dev0/pageindex/index/utils.py +0 -431
  37. pageindex-0.3.0.dev0/pageindex/page_index.py +0 -1155
  38. pageindex-0.3.0.dev0/pageindex/page_index_md.py +0 -342
  39. pageindex-0.3.0.dev0/pageindex/storage/protocol.py +0 -18
  40. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/LICENSE +0 -0
  41. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/backend/__init__.py +0 -0
  42. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/events.py +0 -0
  43. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/index/__init__.py +0 -0
  44. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/parser/__init__.py +0 -0
  45. {pageindex-0.3.0.dev0 → pageindex-0.3.0.dev2}/pageindex/storage/__init__.py +0 -0
@@ -1,8 +1,9 @@
1
- Metadata-Version: 2.3
1
+ Metadata-Version: 2.4
2
2
  Name: pageindex
3
- Version: 0.3.0.dev0
3
+ Version: 0.3.0.dev2
4
4
  Summary: Python SDK for PageIndex
5
5
  License: MIT
6
+ License-File: LICENSE
6
7
  Keywords: rag,document,retrieval,llm,pageindex,agents,vector-database
7
8
  Author: Ray
8
9
  Author-email: ray@vectify.ai
@@ -15,15 +16,19 @@ Classifier: Programming Language :: Python :: 3.10
15
16
  Classifier: Programming Language :: Python :: 3.11
16
17
  Classifier: Programming Language :: Python :: 3.12
17
18
  Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
18
20
  Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
21
  Requires-Dist: PyPDF2 (>=3.0.0)
20
22
  Requires-Dist: httpx[socks] (>=0.28.1)
21
23
  Requires-Dist: litellm (>=1.83.0)
24
+ Requires-Dist: openai (>=1.70.0)
22
25
  Requires-Dist: openai-agents (>=0.1.0)
26
+ Requires-Dist: pydantic (>=2.5.0,<3.0.0)
23
27
  Requires-Dist: pymupdf (>=1.26.0)
24
28
  Requires-Dist: python-dotenv (>=1.0.0)
25
29
  Requires-Dist: pyyaml (>=6.0)
26
30
  Requires-Dist: requests (>=2.28.0)
31
+ Requires-Dist: typing-extensions (>=4.9.0)
27
32
  Project-URL: Documentation, https://docs.pageindex.ai
28
33
  Project-URL: Homepage, https://pageindex.ai
29
34
  Project-URL: Issues, https://github.com/VectifyAI/PageIndex/issues
@@ -45,10 +50,10 @@ Description-Content-Type: text/markdown
45
50
 
46
51
  # PageIndex: Vectorless, Reasoning-based RAG
47
52
 
48
- <p align="center"><b>Reasoning-based RAG&nbsp; ◦ &nbsp;No Vector DB&nbsp; ◦ &nbsp;No Chunking&nbsp; ◦ &nbsp;Human-like Retrieval</b></p>
53
+ <p align="center"><b>Reasoning-based RAG&nbsp; ◦ &nbsp;No Vector DB, No Chunking&nbsp; ◦ &nbsp;Context-Aware Retrieval&nbsp; ◦ &nbsp;Reads Like a Human</b></p>
49
54
 
50
55
  <h4 align="center">
51
- <a href="https://vectify.ai">🌐 Homepage</a>&nbsp; • &nbsp;
56
+ <a href="https://vectify.ai">🌐 Website</a>&nbsp; • &nbsp;
52
57
  <a href="https://chat.pageindex.ai">🖥️ Chat Platform</a>&nbsp; • &nbsp;
53
58
  <a href="https://pageindex.ai/developer">🔌 MCP & API</a>&nbsp; • &nbsp;
54
59
  <a href="https://docs.pageindex.ai">📖 Docs</a>&nbsp; • &nbsp;
@@ -62,9 +67,10 @@ Description-Content-Type: text/markdown
62
67
  <details open>
63
68
  <summary><h2>📢 Updates</h2></summary>
64
69
 
65
- - 🔥 [**Agentic Vectorless RAG**](https://github.com/VectifyAI/PageIndex/blob/main/examples/agentic_vectorless_rag_demo.py) — A simple *agentic, vectorless RAG* [example](https://github.com/VectifyAI/PageIndex/blob/main/examples/agentic_vectorless_rag_demo.py) with self-hosted PageIndex, using OpenAI Agents SDK.
70
+ - 🔥 [**Agentic Vectorless RAG**](https://github.com/VectifyAI/PageIndex/blob/main/examples/agentic_vectorless_rag_demo.py) — A simple agentic, vectorless RAG [example](#-agentic-vectorless-rag-an-example) with *self-hosted PageIndex*, using OpenAI Agents SDK.
71
+ - [**Scale PageIndex to Millions of Documents**](https://pageindex.ai/blog/pageindex-filesystem) — *PageIndex File System* is a file-level tree indexing layer that lets PageIndex reason over an entire corpus, not just a single document, enabling massive-scale document search.
66
72
  - [PageIndex Chat](https://chat.pageindex.ai) — Human-like document analysis agent [platform](https://chat.pageindex.ai) for professional long documents. Also available via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
67
- - [PageIndex Framework](https://pageindex.ai/blog/pageindex-intro) — Deep dive into PageIndex: an *agentic, in-context tree index* that enables LLMs to perform *reasoning-based, human-like retrieval* over long documents.
73
+ - [PageIndex Framework](https://pageindex.ai/blog/pageindex-intro) — Deep dive into PageIndex: an *agentic, in-context tree index* that enables LLMs to perform *reasoning-based, context-aware retrieval* over long documents.
68
74
 
69
75
  <!-- **🧪 Cookbooks:**
70
76
  - [Vectorless RAG](https://docs.pageindex.ai/cookbook/vectorless-rag-pageindex): A minimal, hands-on example of reasoning-based RAG using PageIndex. No vectors, no chunking, and human-like retrieval.
@@ -76,13 +82,13 @@ Description-Content-Type: text/markdown
76
82
 
77
83
  # 📑 Introduction to PageIndex
78
84
 
79
- Are you frustrated with vector database retrieval accuracy for long professional documents? Traditional vector-based RAG relies on semantic *similarity* rather than true *relevance*. But **similarity ≠ relevance** — what we truly need in retrieval is **relevance**, and that requires **reasoning**. When working with professional documents that demand domain expertise and multi-step reasoning, similarity search often falls short.
85
+ Are you frustrated with vector database retrieval accuracy for long professional documents? Traditional vector-based RAG relies on semantic *similarity* rather than true *relevance*. But **similarity ≠ relevance** — what we truly need in retrieval is **relevance**, and that requires **reasoning**. When working with professional documents that demand *contextual understanding*, domain expertise, and multi-step reasoning, similarity search often falls short — missing what's relevant but not similar, and returning what's similar yet not relevant.
80
86
 
81
- Inspired by AlphaGo, we propose **[PageIndex](https://vectify.ai/pageindex)** — a **vectorless**, **reasoning-based RAG** system that builds a **hierarchical tree index** from long documents and uses LLMs to **reason** *over that index* for **agentic, context-aware retrieval**.
82
- It simulates how *human experts* navigate and extract knowledge from complex documents through *tree search*, enabling LLMs to *think* and *reason* their way to the most relevant document sections. PageIndex performs retrieval in two steps:
87
+ Inspired by AlphaGo, we propose **[PageIndex](https://vectify.ai/pageindex)** — a **vectorless**, **reasoning-based RAG** system that builds a **hierarchical tree index** from long documents, and uses LLMs to **reason** *over that index* for **agentic, context-aware retrieval**. The retrieval is *traceable* and *explainable*, with no vector DBs or chunking.
88
+ PageIndex simulates how *human experts* navigate and extract knowledge from complex documents through *tree search*, enabling LLMs to *think* and *reason* their way to the most relevant document sections. It performs retrieval in two steps:
83
89
 
84
90
  1. Generate a “Table-of-Contents” **tree structure index** of documents
85
- 2. Perform reasoning-based retrieval through **tree search**
91
+ 2. Perform (agentic) reasoning-based retrieval through **tree search**
86
92
 
87
93
  <div align="center">
88
94
  <a href="https://pageindex.ai/blog/pageindex-intro" target="_blank" title="The PageIndex Framework">
@@ -92,28 +98,31 @@ It simulates how *human experts* navigate and extract knowledge from complex doc
92
98
 
93
99
  ### 🎯 Core Features
94
100
 
101
+ > PageIndex is a vectorless, reasoning-based RAG engine that mirrors how humans read, delivering traceable, explainable, and context-aware retrieval, without vector databases or chunking.
102
+
95
103
  Compared to traditional vector-based RAG, **PageIndex** features:
96
104
  - **No Vector DB**: Uses document structure and LLM reasoning for retrieval, instead of vector similarity search.
97
105
  - **No Chunking**: Documents are organized into natural sections, not artificial chunks.
98
- - **Human-like Retrieval**: Simulates how human experts navigate and extract knowledge from complex documents.
99
- - **Better Explainability and Traceability**: Retrieval is based on reasoning traceable and interpretable, with page and section references. No more opaque, approximate vector search (“vibe retrieval”).
106
+ - **Better Traceability & Explainability**: Retrieval is reasoning-driven and grounded in explicit page and section references, making every result traceable and interpretable — no more “vibe retrieval” with opaque, approximate vector search.
107
+ - **Context-Aware Retrieval**: Retrieval depends on your full context (e.g., conversation history and domain knowledge), and easily incorporates new context.
108
+ - **Human-like Retrieval**: Mirrors how human experts navigate and extract knowledge from complex documents.
100
109
 
101
- PageIndex powers a reasoning-based RAG system that achieved **state-of-the-art** [98.7% accuracy](https://github.com/VectifyAI/Mafin2.5-FinanceBench) on FinanceBench, demonstrating superior performance over vector-based RAG solutions in professional document analysis. See our [blog post](https://vectify.ai/blog/Mafin2.5) for details.
110
+ PageIndex achieved **state-of-the-art** [98.7% accuracy](https://github.com/VectifyAI/Mafin2.5-FinanceBench) on FinanceBench (financial document QA benchmark), vastly outperforming vector RAG solutions on professional document analysis ([blog post](https://vectify.ai/blog/Mafin2.5)).
102
111
 
103
112
  ### 📍 Explore PageIndex
104
113
 
105
- To learn more, please see a detailed introduction to the [PageIndex framework](https://pageindex.ai/blog/pageindex-intro). Check out this GitHub repo for open-source code, and the [cookbooks](https://docs.pageindex.ai/cookbook), [tutorials](https://docs.pageindex.ai/tutorials), and [blog](https://pageindex.ai/blog) for additional usage guides and examples.
114
+ To learn more, please see a detailed introduction to the [PageIndex framework](https://pageindex.ai/blog/pageindex-intro). Check out [our GitHub](https://docs.pageindex.ai/open-source) for open-source code, and the [cookbooks](https://docs.pageindex.ai/cookbook), [tutorials](https://docs.pageindex.ai/tutorials), and [blog](https://pageindex.ai/blog) for more usage guides and examples.
106
115
 
107
- The PageIndex service is available as a ChatGPT-style [chat platform](https://chat.pageindex.ai), or can be integrated via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
116
+ The PageIndex service is available as a ChatGPT-style [chat platform](https://chat.pageindex.ai), or can be integrated via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer), with [enterprise](https://pageindex.ai/enterprise) deployment available.
108
117
 
109
118
  ### 🛠️ Deployment Options
110
- - Self-host — run locally with this open-source repo.
111
- - Cloud Service — try instantly with our [Chat Platform](https://chat.pageindex.ai/), or integrate via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
112
- - _Enterprise_private or on-prem deployment. [Contact us](https://ii2abc2jejf.typeform.com/to/tK3AXl8T) or [book a demo](https://calendly.com/pageindex/meet) for more details.
119
+ - **Self-host** — run locally with this open-source repo (using standard PDF parsing).
120
+ - **Cloud Service**production-grade pipeline with enhanced OCR, tree building, and retrieval for best results. Try instantly on our [Chat Platform](https://chat.pageindex.ai/), or integrate via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
121
+ - **Enterprise**dedicated or private deployment (VPC, on-prem). [Contact us](https://ii2abc2jejf.typeform.com/to/gVv7qkaN) or [book a demo](https://calendly.com/pageindex/meet) to learn more.
113
122
 
114
123
  ### 🧪 Quick Hands-on
115
124
 
116
- - 🔥 [**Agentic Vectorless RAG**](examples/agentic_vectorless_rag_demo.py) (**latest**) — a simple but complete **agentic vectorless RAG** [example](https://github.com/VectifyAI/PageIndex/blob/main/examples/agentic_vectorless_rag_demo.py) with *self-hosted* PageIndex, using OpenAI Agents SDK.
125
+ - 🔥 [**Agentic Vectorless RAG**](examples/agentic_vectorless_rag_demo.py) *(latest)* — a simple but complete **agentic vectorless RAG** [example](#-agentic-vectorless-rag-an-example) with *self-hosted* PageIndex, using OpenAI Agents SDK.
117
126
  - Try the [Vectorless RAG](https://github.com/VectifyAI/PageIndex/blob/main/cookbook/pageindex_RAG_simple.ipynb) notebook — a *minimal*, hands-on example of reasoning-based RAG using PageIndex.
118
127
  - Check out [Vision-based Vectorless RAG](https://github.com/VectifyAI/PageIndex/blob/main/cookbook/vision_RAG_pageindex.ipynb) — no OCR; a minimal, vision-based & reasoning-native RAG pipeline that works directly over page images.
119
128
 
@@ -135,7 +144,7 @@ The PageIndex service is available as a ChatGPT-style [chat platform](https://ch
135
144
 
136
145
  # 🌲 PageIndex Tree Structure
137
146
 
138
- PageIndex can transform lengthy PDF documents into a semantic **tree structure**, similar to a _"table of contents"_ but optimized for use with Large Language Models (LLMs). It's ideal for: financial reports, regulatory filings, academic textbooks, legal or technical manuals, and any document that exceeds LLM context limits.
147
+ PageIndex can transform lengthy PDF documents into a semantic **tree structure**, similar to a _table of contents_ but optimized for use with LLMs and AI agents. It's ideal for: financial reports, legal documents, regulatory filings, technical manuals, medical literature, academic textbooks, and any long, complex professional documents.
139
148
 
140
149
  Below is an example PageIndex tree structure. Also see more example [documents](https://github.com/VectifyAI/PageIndex/tree/main/examples/documents) and generated [tree structures](https://github.com/VectifyAI/PageIndex/tree/main/examples/documents/results).
141
150
 
@@ -167,12 +176,73 @@ Below is an example PageIndex tree structure. Also see more example [documents](
167
176
  ...
168
177
  ```
169
178
 
170
- You can generate the PageIndex tree structure with this open-source repo, or use our [API](https://pageindex.ai/developer).
179
+ You can generate PageIndex tree structures with this open-source repo. Or use our [API](https://pageindex.ai/developer) for higher-quality results powered by our enhanced OCR and tree building pipeline.
180
+
181
+ ---
182
+
183
+ # 🚀 SDK Usage
184
+
185
+ A unified `PageIndexClient` powers both local self-hosted and cloud-managed modes. Mode is auto-detected by whether you pass an `api_key`.
186
+
187
+ ### Install
188
+
189
+ ```bash
190
+ pip install pageindex
191
+ ```
192
+
193
+ ### Quick start
194
+
195
+ ```python
196
+ from pageindex import PageIndexClient
197
+
198
+ # Local mode — uses your LLM key (e.g. OPENAI_API_KEY in env).
199
+ client = PageIndexClient(model="gpt-4o-2024-11-20")
200
+
201
+ col = client.collection()
202
+ doc_id = col.add("path/to/your.pdf")
203
+
204
+ print(col.query("What is the main contribution?", doc_ids=doc_id))
205
+
206
+ # Cloud mode — fully managed, no LLM key needed:
207
+ # client = PageIndexClient(api_key="your-pageindex-api-key")
208
+ ```
209
+
210
+ `col.query(...)` returns the answer string by default. Always pass `doc_ids` for reliable single-document QA — omitting it queries the entire collection, which is experimental (see below).
211
+
212
+ ### Streaming queries
213
+
214
+ ```python
215
+ import asyncio
216
+
217
+ async def main():
218
+ async for ev in col.query("Explain multi-head attention", doc_ids=doc_id, stream=True):
219
+ if ev.type == "answer_delta":
220
+ print(ev.data, end="", flush=True)
221
+ elif ev.type == "tool_call":
222
+ print(f"\n[tool] {ev.data['name']}")
223
+
224
+ asyncio.run(main())
225
+ ```
226
+
227
+ `ev.type` is one of: `tool_call`, `tool_result`, `answer_delta`, `answer_done`.
228
+
229
+ ### Multi-document collections (experimental)
230
+
231
+ Passing `doc_ids` scopes the query to a specific subset of documents — this is the recommended path. `doc_ids` accepts a single id (`str`) or a list:
232
+
233
+ ```python
234
+ col.query("What does this paper say?", doc_ids=doc1) # single
235
+ col.query("Compare these two papers", doc_ids=[doc1, doc2]) # multi
236
+ ```
237
+
238
+ Omitting `doc_ids` queries the **entire collection** and lets the agent pick which docs to read. This is an **experimental** feature with a naive first implementation — we're actively working on better cross-document retrieval. A `UserWarning` is emitted; set `PAGEINDEX_EXPERIMENTAL_MULTIDOC=1` to silence it.
171
239
 
172
240
  ---
173
241
 
174
242
  # ⚙️ Package Usage
175
243
 
244
+ > **Note:** This package uses standard PDF parsing. For use cases with complex PDFs, our [cloud service](https://pageindex.ai/developer) (via MCP and API) offers enhanced OCR, tree building, and retrieval.
245
+
176
246
  You can follow these steps to generate a PageIndex tree from a PDF document.
177
247
 
178
248
  ### 1. Install dependencies
@@ -183,7 +253,7 @@ pip3 install --upgrade -r requirements.txt
183
253
 
184
254
  ### 2. Set your LLM API key
185
255
 
186
- Create a `.env` file in the root directory with your LLM API key, with multi-LLM support via [LiteLLM](https://docs.litellm.ai/docs/providers):
256
+ Create a `.env` file in the root directory with your LLM API key. Multi-LLM is supported via [LiteLLM](https://docs.litellm.ai/docs/providers):
187
257
 
188
258
  ```bash
189
259
  OPENAI_API_KEY=your_openai_key_here
@@ -220,12 +290,12 @@ We also provide markdown support for PageIndex. You can use the `--md_path` flag
220
290
  python3 run_pageindex.py --md_path /path/to/your/document.md
221
291
  ```
222
292
 
223
- > Note: in this mode, we use "#" to determine node headings and their levels. For example, "##" is level 2, "###" is level 3, etc. Make sure your markdown file is formatted correctly. If your Markdown file was converted from a PDF or HTML, we don't recommend using this mode, since most existing conversion tools cannot preserve the original hierarchy. Instead, use our [PageIndex OCR](https://pageindex.ai/blog/ocr), which is designed to preserve the original hierarchy, to convert the PDF to a markdown file and then use this mode.
293
+ > Note: in this mode, we use "#" to determine node headings and their levels. For example, "##" is level 2, "###" is level 3, etc. Make sure your markdown file is formatted correctly. If your Markdown file was converted from a PDF or HTML, we don't recommend using this mode, since most existing conversion tools cannot preserve the original hierarchy. Instead, use our [PageIndex OCR](https://pageindex.ai/blog/ocr), which is designed to preserve it, to convert the PDF to a markdown file and then use this mode.
224
294
  </details>
225
295
 
226
- ## Agentic Vectorless RAG: An Example
296
+ ## 🚀 Agentic Vectorless RAG: An Example
227
297
 
228
- For a simple, end-to-end _**agentic vectorless RAG**_ example using PageIndex with OpenAI Agents SDK, see [`examples/agentic_vectorless_rag_demo.py`](examples/agentic_vectorless_rag_demo.py).
298
+ For a simple, end-to-end **agentic vectorless RAG** example using **self-hosted PageIndex** (with OpenAI Agents SDK), see [`examples/agentic_vectorless_rag_demo.py`](examples/agentic_vectorless_rag_demo.py).
229
299
 
230
300
  ```bash
231
301
  # Install optional dependency
@@ -254,7 +324,7 @@ To address this, we introduced PageIndex OCR — the first long-context OCR mode
254
324
 
255
325
  # 📈 Case Study: PageIndex Leads Finance QA Benchmark
256
326
 
257
- [Mafin 2.5](https://vectify.ai/mafin) is a reasoning-based RAG system for financial document analysis, powered by **PageIndex**. It achieved a state-of-the-art [**98.7% accuracy**](https://vectify.ai/blog/Mafin2.5) on the [FinanceBench](https://arxiv.org/abs/2311.11944) benchmark, significantly outperforming traditional vector-based RAG systems.
327
+ [Mafin 2.5](https://vectify.ai/mafin) is a reasoning-based RAG system for financial document analysis, powered by **PageIndex**. It achieved a state-of-the-art [**98.7% accuracy**](https://vectify.ai/blog/Mafin2.5) on [FinanceBench](https://arxiv.org/abs/2311.11944) (financial document QA benchmark), significantly outperforming traditional vector-based RAG systems.
258
328
 
259
329
  PageIndex's hierarchical indexing and reasoning-driven retrieval enable precise navigation and extraction of relevant context from complex financial reports, such as SEC filings and earnings disclosures.
260
330
 
@@ -308,14 +378,20 @@ PageIndex Blog, Sep 2025.
308
378
  </details>
309
379
 
310
380
 
381
+ ### 🌐 Open-Source Ecosystem
382
+
383
+ [PageIndex](https://github.com/VectifyAI/PageIndex) anchors a growing open-source [ecosystem](https://docs.pageindex.ai/open-source) of **long-context AI infra** — [OpenKB](https://github.com/VectifyAI/OpenKB) is an LLM knowledge base that compiles documents into an interlinked wiki. [ChatIndex](https://github.com/VectifyAI/ChatIndex) provides tree indexing and retrieval for long conversational histories and memory. [ConDB](https://github.com/VectifyAI/ConDB) is a KV-cache native context database for tree-based retrieval at scale. [PageIndex MCP](https://github.com/VectifyAI/pageindex-mcp) is PageIndex's MCP server.
384
+
311
385
  ### Connect with Us
312
386
 
313
387
  <div align="center">
314
388
 
315
- [![Twitter](https://img.shields.io/badge/Twitter-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/PageIndexAI)&ensp;
316
- [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/vectify-ai/)&ensp;
317
- [![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/invite/VuXuf29EUj)&ensp;
318
- [![Contact Us](https://img.shields.io/badge/Contact_Us-3B82F6?style=for-the-badge&logo=envelope&logoColor=white)](https://ii2abc2jejf.typeform.com/to/tK3AXl8T)
389
+ [![Website](https://img.shields.io/badge/Website-2D72CF?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTEyIDEgMSAxMWgyLjV2MTJoNnYtN2g1djdoNlYxMUgyM3oiLz48L3N2Zz4%3D)](https://pageindex.ai)&nbsp;
390
+ [![Twitter](https://img.shields.io/badge/Twitter-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/PageIndexAI)&nbsp;
391
+ [![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTIwLjQ1IDIwLjQ1aC0zLjU1di01LjU3YzAtMS4zMy0uMDMtMy4wNC0xLjg1LTMuMDQtMS44NSAwLTIuMTQgMS40NS0yLjE0IDIuOTR2NS42N0g5LjM1VjloMy40MXYxLjU2aC4wNWMuNDgtLjkgMS42NC0xLjg1IDMuMzctMS44NSAzLjYgMCA0LjI3IDIuMzcgNC4yNyA1LjQ2djYuMjh6TTUuMzQgNy40M2EyLjA2IDIuMDYgMCAxIDEgMC00LjEzIDIuMDYgMi4wNiAwIDAgMSAwIDQuMTN6TTcuMTIgMjAuNDVIMy41NlY5aDMuNTZ2MTEuNDV6TTIyLjIyIDBIMS43N0MuNzkgMCAwIC43NyAwIDEuNzN2MjAuNTRDMCAyMy4yMy43OSAyNCAxLjc3IDI0aDIwLjQ1QzIzLjIgMjQgMjQgMjMuMjMgMjQgMjIuMjdWMS43M0MyNCAuNzcgMjMuMiAwIDIyLjIyIDB6Ii8%2BPC9zdmc%2B)](https://www.linkedin.com/company/vectify-ai/)&nbsp;
392
+ [![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/invite/VuXuf29EUj)&nbsp;
393
+ [![Book a Demo](https://img.shields.io/badge/Book_a_Demo-6E7E96?style=for-the-badge&logo=googlecalendar&logoColor=white)](https://calendly.com/pageindex/meet)&nbsp;
394
+ [![Contact Us](https://img.shields.io/badge/Contact_Us-3B82F6?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjIgNCAyMCAxNiI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTIwIDRINGMtMS4xIDAtMiAuOS0yIDJ2MTJjMCAxLjEuOSAyIDIgMmgxNmMxLjEgMCAyLS45IDItMlY2YzAtMS4xLS45LTItMi0yem0wIDQtOCA1LTgtNVY2bDggNSA4LTV6Ii8%2BPC9zdmc%2B)](https://ii2abc2jejf.typeform.com/to/tK3AXl8T)
319
395
 
320
396
  </div>
321
397
 
@@ -13,10 +13,10 @@
13
13
 
14
14
  # PageIndex: Vectorless, Reasoning-based RAG
15
15
 
16
- <p align="center"><b>Reasoning-based RAG&nbsp; ◦ &nbsp;No Vector DB&nbsp; ◦ &nbsp;No Chunking&nbsp; ◦ &nbsp;Human-like Retrieval</b></p>
16
+ <p align="center"><b>Reasoning-based RAG&nbsp; ◦ &nbsp;No Vector DB, No Chunking&nbsp; ◦ &nbsp;Context-Aware Retrieval&nbsp; ◦ &nbsp;Reads Like a Human</b></p>
17
17
 
18
18
  <h4 align="center">
19
- <a href="https://vectify.ai">🌐 Homepage</a>&nbsp; • &nbsp;
19
+ <a href="https://vectify.ai">🌐 Website</a>&nbsp; • &nbsp;
20
20
  <a href="https://chat.pageindex.ai">🖥️ Chat Platform</a>&nbsp; • &nbsp;
21
21
  <a href="https://pageindex.ai/developer">🔌 MCP & API</a>&nbsp; • &nbsp;
22
22
  <a href="https://docs.pageindex.ai">📖 Docs</a>&nbsp; • &nbsp;
@@ -30,9 +30,10 @@
30
30
  <details open>
31
31
  <summary><h2>📢 Updates</h2></summary>
32
32
 
33
- - 🔥 [**Agentic Vectorless RAG**](https://github.com/VectifyAI/PageIndex/blob/main/examples/agentic_vectorless_rag_demo.py) — A simple *agentic, vectorless RAG* [example](https://github.com/VectifyAI/PageIndex/blob/main/examples/agentic_vectorless_rag_demo.py) with self-hosted PageIndex, using OpenAI Agents SDK.
33
+ - 🔥 [**Agentic Vectorless RAG**](https://github.com/VectifyAI/PageIndex/blob/main/examples/agentic_vectorless_rag_demo.py) — A simple agentic, vectorless RAG [example](#-agentic-vectorless-rag-an-example) with *self-hosted PageIndex*, using OpenAI Agents SDK.
34
+ - [**Scale PageIndex to Millions of Documents**](https://pageindex.ai/blog/pageindex-filesystem) — *PageIndex File System* is a file-level tree indexing layer that lets PageIndex reason over an entire corpus, not just a single document, enabling massive-scale document search.
34
35
  - [PageIndex Chat](https://chat.pageindex.ai) — Human-like document analysis agent [platform](https://chat.pageindex.ai) for professional long documents. Also available via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
35
- - [PageIndex Framework](https://pageindex.ai/blog/pageindex-intro) — Deep dive into PageIndex: an *agentic, in-context tree index* that enables LLMs to perform *reasoning-based, human-like retrieval* over long documents.
36
+ - [PageIndex Framework](https://pageindex.ai/blog/pageindex-intro) — Deep dive into PageIndex: an *agentic, in-context tree index* that enables LLMs to perform *reasoning-based, context-aware retrieval* over long documents.
36
37
 
37
38
  <!-- **🧪 Cookbooks:**
38
39
  - [Vectorless RAG](https://docs.pageindex.ai/cookbook/vectorless-rag-pageindex): A minimal, hands-on example of reasoning-based RAG using PageIndex. No vectors, no chunking, and human-like retrieval.
@@ -44,13 +45,13 @@
44
45
 
45
46
  # 📑 Introduction to PageIndex
46
47
 
47
- Are you frustrated with vector database retrieval accuracy for long professional documents? Traditional vector-based RAG relies on semantic *similarity* rather than true *relevance*. But **similarity ≠ relevance** — what we truly need in retrieval is **relevance**, and that requires **reasoning**. When working with professional documents that demand domain expertise and multi-step reasoning, similarity search often falls short.
48
+ Are you frustrated with vector database retrieval accuracy for long professional documents? Traditional vector-based RAG relies on semantic *similarity* rather than true *relevance*. But **similarity ≠ relevance** — what we truly need in retrieval is **relevance**, and that requires **reasoning**. When working with professional documents that demand *contextual understanding*, domain expertise, and multi-step reasoning, similarity search often falls short — missing what's relevant but not similar, and returning what's similar yet not relevant.
48
49
 
49
- Inspired by AlphaGo, we propose **[PageIndex](https://vectify.ai/pageindex)** — a **vectorless**, **reasoning-based RAG** system that builds a **hierarchical tree index** from long documents and uses LLMs to **reason** *over that index* for **agentic, context-aware retrieval**.
50
- It simulates how *human experts* navigate and extract knowledge from complex documents through *tree search*, enabling LLMs to *think* and *reason* their way to the most relevant document sections. PageIndex performs retrieval in two steps:
50
+ Inspired by AlphaGo, we propose **[PageIndex](https://vectify.ai/pageindex)** — a **vectorless**, **reasoning-based RAG** system that builds a **hierarchical tree index** from long documents, and uses LLMs to **reason** *over that index* for **agentic, context-aware retrieval**. The retrieval is *traceable* and *explainable*, with no vector DBs or chunking.
51
+ PageIndex simulates how *human experts* navigate and extract knowledge from complex documents through *tree search*, enabling LLMs to *think* and *reason* their way to the most relevant document sections. It performs retrieval in two steps:
51
52
 
52
53
  1. Generate a “Table-of-Contents” **tree structure index** of documents
53
- 2. Perform reasoning-based retrieval through **tree search**
54
+ 2. Perform (agentic) reasoning-based retrieval through **tree search**
54
55
 
55
56
  <div align="center">
56
57
  <a href="https://pageindex.ai/blog/pageindex-intro" target="_blank" title="The PageIndex Framework">
@@ -60,28 +61,31 @@ It simulates how *human experts* navigate and extract knowledge from complex doc
60
61
 
61
62
  ### 🎯 Core Features
62
63
 
64
+ > PageIndex is a vectorless, reasoning-based RAG engine that mirrors how humans read, delivering traceable, explainable, and context-aware retrieval, without vector databases or chunking.
65
+
63
66
  Compared to traditional vector-based RAG, **PageIndex** features:
64
67
  - **No Vector DB**: Uses document structure and LLM reasoning for retrieval, instead of vector similarity search.
65
68
  - **No Chunking**: Documents are organized into natural sections, not artificial chunks.
66
- - **Human-like Retrieval**: Simulates how human experts navigate and extract knowledge from complex documents.
67
- - **Better Explainability and Traceability**: Retrieval is based on reasoning traceable and interpretable, with page and section references. No more opaque, approximate vector search (“vibe retrieval”).
69
+ - **Better Traceability & Explainability**: Retrieval is reasoning-driven and grounded in explicit page and section references, making every result traceable and interpretable — no more “vibe retrieval” with opaque, approximate vector search.
70
+ - **Context-Aware Retrieval**: Retrieval depends on your full context (e.g., conversation history and domain knowledge), and easily incorporates new context.
71
+ - **Human-like Retrieval**: Mirrors how human experts navigate and extract knowledge from complex documents.
68
72
 
69
- PageIndex powers a reasoning-based RAG system that achieved **state-of-the-art** [98.7% accuracy](https://github.com/VectifyAI/Mafin2.5-FinanceBench) on FinanceBench, demonstrating superior performance over vector-based RAG solutions in professional document analysis. See our [blog post](https://vectify.ai/blog/Mafin2.5) for details.
73
+ PageIndex achieved **state-of-the-art** [98.7% accuracy](https://github.com/VectifyAI/Mafin2.5-FinanceBench) on FinanceBench (financial document QA benchmark), vastly outperforming vector RAG solutions on professional document analysis ([blog post](https://vectify.ai/blog/Mafin2.5)).
70
74
 
71
75
  ### 📍 Explore PageIndex
72
76
 
73
- To learn more, please see a detailed introduction to the [PageIndex framework](https://pageindex.ai/blog/pageindex-intro). Check out this GitHub repo for open-source code, and the [cookbooks](https://docs.pageindex.ai/cookbook), [tutorials](https://docs.pageindex.ai/tutorials), and [blog](https://pageindex.ai/blog) for additional usage guides and examples.
77
+ To learn more, please see a detailed introduction to the [PageIndex framework](https://pageindex.ai/blog/pageindex-intro). Check out [our GitHub](https://docs.pageindex.ai/open-source) for open-source code, and the [cookbooks](https://docs.pageindex.ai/cookbook), [tutorials](https://docs.pageindex.ai/tutorials), and [blog](https://pageindex.ai/blog) for more usage guides and examples.
74
78
 
75
- The PageIndex service is available as a ChatGPT-style [chat platform](https://chat.pageindex.ai), or can be integrated via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
79
+ The PageIndex service is available as a ChatGPT-style [chat platform](https://chat.pageindex.ai), or can be integrated via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer), with [enterprise](https://pageindex.ai/enterprise) deployment available.
76
80
 
77
81
  ### 🛠️ Deployment Options
78
- - Self-host — run locally with this open-source repo.
79
- - Cloud Service — try instantly with our [Chat Platform](https://chat.pageindex.ai/), or integrate via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
80
- - _Enterprise_private or on-prem deployment. [Contact us](https://ii2abc2jejf.typeform.com/to/tK3AXl8T) or [book a demo](https://calendly.com/pageindex/meet) for more details.
82
+ - **Self-host** — run locally with this open-source repo (using standard PDF parsing).
83
+ - **Cloud Service**production-grade pipeline with enhanced OCR, tree building, and retrieval for best results. Try instantly on our [Chat Platform](https://chat.pageindex.ai/), or integrate via [MCP](https://pageindex.ai/developer) or [API](https://pageindex.ai/developer).
84
+ - **Enterprise**dedicated or private deployment (VPC, on-prem). [Contact us](https://ii2abc2jejf.typeform.com/to/gVv7qkaN) or [book a demo](https://calendly.com/pageindex/meet) to learn more.
81
85
 
82
86
  ### 🧪 Quick Hands-on
83
87
 
84
- - 🔥 [**Agentic Vectorless RAG**](examples/agentic_vectorless_rag_demo.py) (**latest**) — a simple but complete **agentic vectorless RAG** [example](https://github.com/VectifyAI/PageIndex/blob/main/examples/agentic_vectorless_rag_demo.py) with *self-hosted* PageIndex, using OpenAI Agents SDK.
88
+ - 🔥 [**Agentic Vectorless RAG**](examples/agentic_vectorless_rag_demo.py) *(latest)* — a simple but complete **agentic vectorless RAG** [example](#-agentic-vectorless-rag-an-example) with *self-hosted* PageIndex, using OpenAI Agents SDK.
85
89
  - Try the [Vectorless RAG](https://github.com/VectifyAI/PageIndex/blob/main/cookbook/pageindex_RAG_simple.ipynb) notebook — a *minimal*, hands-on example of reasoning-based RAG using PageIndex.
86
90
  - Check out [Vision-based Vectorless RAG](https://github.com/VectifyAI/PageIndex/blob/main/cookbook/vision_RAG_pageindex.ipynb) — no OCR; a minimal, vision-based & reasoning-native RAG pipeline that works directly over page images.
87
91
 
@@ -103,7 +107,7 @@ The PageIndex service is available as a ChatGPT-style [chat platform](https://ch
103
107
 
104
108
  # 🌲 PageIndex Tree Structure
105
109
 
106
- PageIndex can transform lengthy PDF documents into a semantic **tree structure**, similar to a _"table of contents"_ but optimized for use with Large Language Models (LLMs). It's ideal for: financial reports, regulatory filings, academic textbooks, legal or technical manuals, and any document that exceeds LLM context limits.
110
+ PageIndex can transform lengthy PDF documents into a semantic **tree structure**, similar to a _table of contents_ but optimized for use with LLMs and AI agents. It's ideal for: financial reports, legal documents, regulatory filings, technical manuals, medical literature, academic textbooks, and any long, complex professional documents.
107
111
 
108
112
  Below is an example PageIndex tree structure. Also see more example [documents](https://github.com/VectifyAI/PageIndex/tree/main/examples/documents) and generated [tree structures](https://github.com/VectifyAI/PageIndex/tree/main/examples/documents/results).
109
113
 
@@ -135,12 +139,73 @@ Below is an example PageIndex tree structure. Also see more example [documents](
135
139
  ...
136
140
  ```
137
141
 
138
- You can generate the PageIndex tree structure with this open-source repo, or use our [API](https://pageindex.ai/developer).
142
+ You can generate PageIndex tree structures with this open-source repo. Or use our [API](https://pageindex.ai/developer) for higher-quality results powered by our enhanced OCR and tree building pipeline.
143
+
144
+ ---
145
+
146
+ # 🚀 SDK Usage
147
+
148
+ A unified `PageIndexClient` powers both local self-hosted and cloud-managed modes. Mode is auto-detected by whether you pass an `api_key`.
149
+
150
+ ### Install
151
+
152
+ ```bash
153
+ pip install pageindex
154
+ ```
155
+
156
+ ### Quick start
157
+
158
+ ```python
159
+ from pageindex import PageIndexClient
160
+
161
+ # Local mode — uses your LLM key (e.g. OPENAI_API_KEY in env).
162
+ client = PageIndexClient(model="gpt-4o-2024-11-20")
163
+
164
+ col = client.collection()
165
+ doc_id = col.add("path/to/your.pdf")
166
+
167
+ print(col.query("What is the main contribution?", doc_ids=doc_id))
168
+
169
+ # Cloud mode — fully managed, no LLM key needed:
170
+ # client = PageIndexClient(api_key="your-pageindex-api-key")
171
+ ```
172
+
173
+ `col.query(...)` returns the answer string by default. Always pass `doc_ids` for reliable single-document QA — omitting it queries the entire collection, which is experimental (see below).
174
+
175
+ ### Streaming queries
176
+
177
+ ```python
178
+ import asyncio
179
+
180
+ async def main():
181
+ async for ev in col.query("Explain multi-head attention", doc_ids=doc_id, stream=True):
182
+ if ev.type == "answer_delta":
183
+ print(ev.data, end="", flush=True)
184
+ elif ev.type == "tool_call":
185
+ print(f"\n[tool] {ev.data['name']}")
186
+
187
+ asyncio.run(main())
188
+ ```
189
+
190
+ `ev.type` is one of: `tool_call`, `tool_result`, `answer_delta`, `answer_done`.
191
+
192
+ ### Multi-document collections (experimental)
193
+
194
+ Passing `doc_ids` scopes the query to a specific subset of documents — this is the recommended path. `doc_ids` accepts a single id (`str`) or a list:
195
+
196
+ ```python
197
+ col.query("What does this paper say?", doc_ids=doc1) # single
198
+ col.query("Compare these two papers", doc_ids=[doc1, doc2]) # multi
199
+ ```
200
+
201
+ Omitting `doc_ids` queries the **entire collection** and lets the agent pick which docs to read. This is an **experimental** feature with a naive first implementation — we're actively working on better cross-document retrieval. A `UserWarning` is emitted; set `PAGEINDEX_EXPERIMENTAL_MULTIDOC=1` to silence it.
139
202
 
140
203
  ---
141
204
 
142
205
  # ⚙️ Package Usage
143
206
 
207
+ > **Note:** This package uses standard PDF parsing. For use cases with complex PDFs, our [cloud service](https://pageindex.ai/developer) (via MCP and API) offers enhanced OCR, tree building, and retrieval.
208
+
144
209
  You can follow these steps to generate a PageIndex tree from a PDF document.
145
210
 
146
211
  ### 1. Install dependencies
@@ -151,7 +216,7 @@ pip3 install --upgrade -r requirements.txt
151
216
 
152
217
  ### 2. Set your LLM API key
153
218
 
154
- Create a `.env` file in the root directory with your LLM API key, with multi-LLM support via [LiteLLM](https://docs.litellm.ai/docs/providers):
219
+ Create a `.env` file in the root directory with your LLM API key. Multi-LLM is supported via [LiteLLM](https://docs.litellm.ai/docs/providers):
155
220
 
156
221
  ```bash
157
222
  OPENAI_API_KEY=your_openai_key_here
@@ -188,12 +253,12 @@ We also provide markdown support for PageIndex. You can use the `--md_path` flag
188
253
  python3 run_pageindex.py --md_path /path/to/your/document.md
189
254
  ```
190
255
 
191
- > Note: in this mode, we use "#" to determine node headings and their levels. For example, "##" is level 2, "###" is level 3, etc. Make sure your markdown file is formatted correctly. If your Markdown file was converted from a PDF or HTML, we don't recommend using this mode, since most existing conversion tools cannot preserve the original hierarchy. Instead, use our [PageIndex OCR](https://pageindex.ai/blog/ocr), which is designed to preserve the original hierarchy, to convert the PDF to a markdown file and then use this mode.
256
+ > Note: in this mode, we use "#" to determine node headings and their levels. For example, "##" is level 2, "###" is level 3, etc. Make sure your markdown file is formatted correctly. If your Markdown file was converted from a PDF or HTML, we don't recommend using this mode, since most existing conversion tools cannot preserve the original hierarchy. Instead, use our [PageIndex OCR](https://pageindex.ai/blog/ocr), which is designed to preserve it, to convert the PDF to a markdown file and then use this mode.
192
257
  </details>
193
258
 
194
- ## Agentic Vectorless RAG: An Example
259
+ ## 🚀 Agentic Vectorless RAG: An Example
195
260
 
196
- For a simple, end-to-end _**agentic vectorless RAG**_ example using PageIndex with OpenAI Agents SDK, see [`examples/agentic_vectorless_rag_demo.py`](examples/agentic_vectorless_rag_demo.py).
261
+ For a simple, end-to-end **agentic vectorless RAG** example using **self-hosted PageIndex** (with OpenAI Agents SDK), see [`examples/agentic_vectorless_rag_demo.py`](examples/agentic_vectorless_rag_demo.py).
197
262
 
198
263
  ```bash
199
264
  # Install optional dependency
@@ -222,7 +287,7 @@ To address this, we introduced PageIndex OCR — the first long-context OCR mode
222
287
 
223
288
  # 📈 Case Study: PageIndex Leads Finance QA Benchmark
224
289
 
225
- [Mafin 2.5](https://vectify.ai/mafin) is a reasoning-based RAG system for financial document analysis, powered by **PageIndex**. It achieved a state-of-the-art [**98.7% accuracy**](https://vectify.ai/blog/Mafin2.5) on the [FinanceBench](https://arxiv.org/abs/2311.11944) benchmark, significantly outperforming traditional vector-based RAG systems.
290
+ [Mafin 2.5](https://vectify.ai/mafin) is a reasoning-based RAG system for financial document analysis, powered by **PageIndex**. It achieved a state-of-the-art [**98.7% accuracy**](https://vectify.ai/blog/Mafin2.5) on [FinanceBench](https://arxiv.org/abs/2311.11944) (financial document QA benchmark), significantly outperforming traditional vector-based RAG systems.
226
291
 
227
292
  PageIndex's hierarchical indexing and reasoning-driven retrieval enable precise navigation and extraction of relevant context from complex financial reports, such as SEC filings and earnings disclosures.
228
293
 
@@ -276,14 +341,20 @@ PageIndex Blog, Sep 2025.
276
341
  </details>
277
342
 
278
343
 
344
+ ### 🌐 Open-Source Ecosystem
345
+
346
+ [PageIndex](https://github.com/VectifyAI/PageIndex) anchors a growing open-source [ecosystem](https://docs.pageindex.ai/open-source) of **long-context AI infra** — [OpenKB](https://github.com/VectifyAI/OpenKB) is an LLM knowledge base that compiles documents into an interlinked wiki. [ChatIndex](https://github.com/VectifyAI/ChatIndex) provides tree indexing and retrieval for long conversational histories and memory. [ConDB](https://github.com/VectifyAI/ConDB) is a KV-cache native context database for tree-based retrieval at scale. [PageIndex MCP](https://github.com/VectifyAI/pageindex-mcp) is PageIndex's MCP server.
347
+
279
348
  ### Connect with Us
280
349
 
281
350
  <div align="center">
282
351
 
283
- [![Twitter](https://img.shields.io/badge/Twitter-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/PageIndexAI)&ensp;
284
- [![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/vectify-ai/)&ensp;
285
- [![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/invite/VuXuf29EUj)&ensp;
286
- [![Contact Us](https://img.shields.io/badge/Contact_Us-3B82F6?style=for-the-badge&logo=envelope&logoColor=white)](https://ii2abc2jejf.typeform.com/to/tK3AXl8T)
352
+ [![Website](https://img.shields.io/badge/Website-2D72CF?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTEyIDEgMSAxMWgyLjV2MTJoNnYtN2g1djdoNlYxMUgyM3oiLz48L3N2Zz4%3D)](https://pageindex.ai)&nbsp;
353
+ [![Twitter](https://img.shields.io/badge/Twitter-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/PageIndexAI)&nbsp;
354
+ [![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTIwLjQ1IDIwLjQ1aC0zLjU1di01LjU3YzAtMS4zMy0uMDMtMy4wNC0xLjg1LTMuMDQtMS44NSAwLTIuMTQgMS40NS0yLjE0IDIuOTR2NS42N0g5LjM1VjloMy40MXYxLjU2aC4wNWMuNDgtLjkgMS42NC0xLjg1IDMuMzctMS44NSAzLjYgMCA0LjI3IDIuMzcgNC4yNyA1LjQ2djYuMjh6TTUuMzQgNy40M2EyLjA2IDIuMDYgMCAxIDEgMC00LjEzIDIuMDYgMi4wNiAwIDAgMSAwIDQuMTN6TTcuMTIgMjAuNDVIMy41NlY5aDMuNTZ2MTEuNDV6TTIyLjIyIDBIMS43N0MuNzkgMCAwIC43NyAwIDEuNzN2MjAuNTRDMCAyMy4yMy43OSAyNCAxLjc3IDI0aDIwLjQ1QzIzLjIgMjQgMjQgMjMuMjMgMjQgMjIuMjdWMS43M0MyNCAuNzcgMjMuMiAwIDIyLjIyIDB6Ii8%2BPC9zdmc%2B)](https://www.linkedin.com/company/vectify-ai/)&nbsp;
355
+ [![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.com/invite/VuXuf29EUj)&nbsp;
356
+ [![Book a Demo](https://img.shields.io/badge/Book_a_Demo-6E7E96?style=for-the-badge&logo=googlecalendar&logoColor=white)](https://calendly.com/pageindex/meet)&nbsp;
357
+ [![Contact Us](https://img.shields.io/badge/Contact_Us-3B82F6?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjIgNCAyMCAxNiI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTIwIDRINGMtMS4xIDAtMiAuOS0yIDJ2MTJjMCAxLjEuOSAyIDIgMmgxNmMxLjEgMCAyLS45IDItMlY2YzAtMS4xLS45LTItMi0yem0wIDQtOCA1LTgtNVY2bDggNSA4LTV6Ii8%2BPC9zdmc%2B)](https://ii2abc2jejf.typeform.com/to/tK3AXl8T)
287
358
 
288
359
  </div>
289
360
 
@@ -0,0 +1,64 @@
1
+ # pageindex/__init__.py
2
+ # Load .env explicitly, before anything else, so environment-based credentials
3
+ # (OPENAI_API_KEY for local mode, PAGEINDEX_API_KEY that callers read via
4
+ # os.environ for cloud mode) are populated by PageIndex itself — not left to
5
+ # litellm's incidental dotenv loading, which would vanish if litellm changes or
6
+ # its import is ever made lazy.
7
+ from dotenv import load_dotenv as _load_dotenv
8
+ _load_dotenv()
9
+
10
+ # Backward compatibility: honor CHATGPT_API_KEY as an alias for OPENAI_API_KEY
11
+ # (kept from the pre-SDK pageindex.utils). Runs after load_dotenv so a value in
12
+ # .env is picked up too; only fills OPENAI_API_KEY when it isn't already set.
13
+ import os as _os
14
+ if not _os.getenv("OPENAI_API_KEY") and _os.getenv("CHATGPT_API_KEY"):
15
+ _os.environ["OPENAI_API_KEY"] = _os.getenv("CHATGPT_API_KEY")
16
+
17
+ # Upstream exports (backward compatibility). Import from the canonical
18
+ # pageindex.index.* modules directly so `import pageindex` does NOT trip the
19
+ # top-level deprecation shims (pageindex.page_index / .page_index_md / .utils).
20
+ from .index.page_index import * # noqa: E402
21
+ from .index.page_index_md import md_to_tree
22
+ from .retrieve import get_document, get_document_structure, get_page_content
23
+
24
+ # SDK exports
25
+ from .client import PageIndexClient, LocalClient, CloudClient
26
+ from .config import IndexConfig, set_llm_params
27
+ from .collection import Collection
28
+ from .types import DocumentInfo, DocumentDetail, PageContent
29
+ from .parser.protocol import ContentNode, ParsedDocument, DocumentParser
30
+ from .storage.protocol import StorageEngine
31
+ from .events import QueryEvent
32
+ from .errors import (
33
+ PageIndexError,
34
+ PageIndexAPIError,
35
+ CollectionNotFoundError,
36
+ DocumentNotFoundError,
37
+ IndexingError,
38
+ CloudAPIError,
39
+ FileTypeError,
40
+ )
41
+
42
+ __all__ = [
43
+ "PageIndexClient",
44
+ "LocalClient",
45
+ "CloudClient",
46
+ "IndexConfig",
47
+ "set_llm_params",
48
+ "Collection",
49
+ "DocumentInfo",
50
+ "DocumentDetail",
51
+ "PageContent",
52
+ "ContentNode",
53
+ "ParsedDocument",
54
+ "DocumentParser",
55
+ "StorageEngine",
56
+ "QueryEvent",
57
+ "PageIndexError",
58
+ "PageIndexAPIError",
59
+ "CollectionNotFoundError",
60
+ "DocumentNotFoundError",
61
+ "IndexingError",
62
+ "CloudAPIError",
63
+ "FileTypeError",
64
+ ]