# vectifyai/pageindex architecture

> Architecture diagram of the GitHub repository vectifyai/pageindex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vectifyai/pageindex
- Repository: https://github.com/vectifyai/pageindex
- Video tour (about a minute): https://gitdiagram.com/vectifyai/pageindex/video

## Overview

PageIndex is a vectorless RAG SDK: it builds hierarchical document trees, then uses LLM-guided tools to search them and answer questions. The main workflow starts at the SDK client, selects cloud or local operation, indexes PDFs into trees, and exposes retrieval/chat. Flash adds a text-PDF layout-to-outline pipeline; classic indexing and tree optimization remain distinct paths. Groups and arrows reflect README capabilities and source-index references; several implementation details are unsampled, so uncertain internal transitions are omitted.

Main entry points: [`pageindex/client.py`](https://github.com/vectifyai/pageindex/blob/main/pageindex/client.py) (PageIndex client), [`pageindex/flash/main.py`](https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/main.py) (Layout to outline), [`pageindex/local_api.py`](https://github.com/vectifyai/pageindex/blob/main/pageindex/local_api.py) (Local API), [`pageindex/agent_tools.py`](https://github.com/vectifyai/pageindex/blob/main/pageindex/agent_tools.py) (Agent retrieval tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sdk["SDK and APIs"]
  node_client["PageIndex client<br/>[client.py]"]
  node_cloud["Cloud API<br/>[cloud_api.py]"]
  node_local_api["Local API<br/>[local_api.py]"]
  node_store[("Local document store<br/>[local_store.py]")]
end

subgraph group_indexing["Tree indexing"]
  node_classic["Classic indexer"]
  node_optimize["Tree refinement<br/>[tree_optimize.py]"]
end

subgraph group_flash["Flash PDF pipeline"]
  node_flash_api["Flash index API<br/>[api.py]"]
  node_pdf_parse["PDF text parsing<br/>[pipeline.py]"]
  node_layout_outline["Layout to outline<br/>[main.py]"]
  node_flash_model["Layout and text model"]
  node_flash_classify["Text classification"]
  node_flash_labels["Caption labeling<br/>[caption_text.py]"]
  node_flash_heading["Heading detection"]
  node_flash_assembly["Outline assembly<br/>[candidates.py]"]
end

subgraph group_retrieval["Reasoning retrieval"]
  node_chat["Local chat<br/>[local_chat.py]"]
  node_tools["Agent retrieval tools<br/>[agent_tools.py]"]
  node_mcp["MCP bridge<br/>[mcp_bridge.py]"]
  node_integrations["Agent SDK adapters"]
end

node_user(("SDK user"))
node_llm["LLM provider"]
node_document["PDF document"]

node_user -->|"submits and queries"| node_client
node_client -->|"uses cloud mode"| node_cloud
node_client -->|"uses local mode"| node_local_api
node_local_api -->|"reads and writes"| node_store
node_local_api -->|"indexes with"| node_flash_api
node_local_api -->|"indexes with"| node_classic
node_document -.->|"provides PDF"| node_local_api
node_flash_api -->|"runs pipeline"| node_layout_outline
node_flash_api -->|"refines tree"| node_optimize
node_layout_outline -->|"parses pages"| node_pdf_parse
node_layout_outline -->|"uses structures"| node_flash_model
node_layout_outline -->|"classifies text"| node_flash_classify
node_layout_outline -->|"labels captions"| node_flash_labels
node_layout_outline -->|"detects headings"| node_flash_heading
node_layout_outline -->|"assembles outline"| node_flash_assembly
node_classic -->|"refines tree"| node_optimize
node_client -->|"routes local chat"| node_chat
node_client -->|"exposes tools"| node_tools
node_chat -->|"invokes tools"| node_tools
node_tools -->|"uses bridge"| node_mcp
node_client -->|"offers adapters"| node_integrations
node_integrations -->|"wraps tool contract"| node_tools
node_chat -.->|"requests reasoning"| node_llm
node_client -.->|"configures models"| node_llm

click node_client "https://github.com/vectifyai/pageindex/blob/main/pageindex/client.py"
click node_cloud "https://github.com/vectifyai/pageindex/blob/main/pageindex/cloud_api.py"
click node_local_api "https://github.com/vectifyai/pageindex/blob/main/pageindex/local_api.py"
click node_store "https://github.com/vectifyai/pageindex/blob/main/pageindex/local_store.py"
click node_classic "https://github.com/vectifyai/pageindex/blob/main/pageindex/page_index_classic.py"
click node_flash_api "https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/api.py"
click node_pdf_parse "https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/parser_pdfium_charlevel/pipeline.py"
click node_layout_outline "https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/main.py"
click node_flash_model "https://github.com/vectifyai/pageindex/tree/main/pageindex/flash/model"
click node_flash_classify "https://github.com/vectifyai/pageindex/tree/main/pageindex/flash/classification"
click node_flash_labels "https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/labels/caption_text.py"
click node_flash_heading "https://github.com/vectifyai/pageindex/tree/main/pageindex/flash/heading_detection"
click node_flash_assembly "https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/outline_assembly/candidates.py"
click node_optimize "https://github.com/vectifyai/pageindex/blob/main/pageindex/tree_optimize.py"
click node_chat "https://github.com/vectifyai/pageindex/blob/main/pageindex/local_chat.py"
click node_tools "https://github.com/vectifyai/pageindex/blob/main/pageindex/agent_tools.py"
click node_mcp "https://github.com/vectifyai/pageindex/blob/main/pageindex/mcp_bridge.py"
click node_integrations "https://github.com/vectifyai/pageindex/tree/main/pageindex/integrations"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_cloud,node_local_api,node_store,node_user toneBlue
class node_classic,node_optimize toneAmber
class node_flash_api,node_pdf_parse,node_layout_outline,node_flash_model,node_flash_classify,node_flash_labels,node_flash_heading,node_flash_assembly toneMint
class node_chat,node_tools,node_mcp,node_integrations toneRose
class node_llm,node_document toneIndigo
```

## Components

### SDK and APIs

- [PageIndex client](https://github.com/vectifyai/pageindex/blob/main/pageindex/client.py): `pageindex/client.py`
- [Cloud API](https://github.com/vectifyai/pageindex/blob/main/pageindex/cloud_api.py): `pageindex/cloud_api.py`
- [Local API](https://github.com/vectifyai/pageindex/blob/main/pageindex/local_api.py): `pageindex/local_api.py`
- [Local document store](https://github.com/vectifyai/pageindex/blob/main/pageindex/local_store.py): `pageindex/local_store.py`

### Tree indexing

- [Classic indexer](https://github.com/vectifyai/pageindex/blob/main/pageindex/page_index_classic.py): `pageindex/page_index_classic.py`
- [Tree refinement](https://github.com/vectifyai/pageindex/blob/main/pageindex/tree_optimize.py): `pageindex/tree_optimize.py`

### Flash PDF pipeline

- [Flash index API](https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/api.py): `pageindex/flash/api.py`
- [PDF text parsing](https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/parser_pdfium_charlevel/pipeline.py): `pageindex/flash/parser_pdfium_charlevel/pipeline.py`
- [Layout to outline](https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/main.py): `pageindex/flash/main.py`
- [Layout and text model](https://github.com/vectifyai/pageindex/tree/main/pageindex/flash/model): `pageindex/flash/model`
- [Text classification](https://github.com/vectifyai/pageindex/tree/main/pageindex/flash/classification): `pageindex/flash/classification`
- [Caption labeling](https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/labels/caption_text.py): `pageindex/flash/labels/caption_text.py`
- [Heading detection](https://github.com/vectifyai/pageindex/tree/main/pageindex/flash/heading_detection): `pageindex/flash/heading_detection`
- [Outline assembly](https://github.com/vectifyai/pageindex/blob/main/pageindex/flash/outline_assembly/candidates.py): `pageindex/flash/outline_assembly/candidates.py`

### Reasoning retrieval

- [Local chat](https://github.com/vectifyai/pageindex/blob/main/pageindex/local_chat.py): `pageindex/local_chat.py`
- [Agent retrieval tools](https://github.com/vectifyai/pageindex/blob/main/pageindex/agent_tools.py): `pageindex/agent_tools.py`
- [MCP bridge](https://github.com/vectifyai/pageindex/blob/main/pageindex/mcp_bridge.py): `pageindex/mcp_bridge.py`
- [Agent SDK adapters](https://github.com/vectifyai/pageindex/tree/main/pageindex/integrations): `pageindex/integrations`

### Other components

- **SDK user**
- **LLM provider**
- **PDF document**

## Connections

- SDK user → PageIndex client: submits and queries
- PageIndex client → Cloud API: uses cloud mode (evidence: `pageindex/client.py`)
- PageIndex client → Local API: uses local mode (evidence: `pageindex/client.py`)
- Local API → Local document store: reads and writes (evidence: `pageindex/local_api.py`)
- Local API → Flash index API: indexes with (evidence: `pageindex/local_api.py`)
- Local API → Classic indexer: indexes with (evidence: `pageindex/local_api.py`)
- PDF document → Local API: provides PDF
- Flash index API → Layout to outline: runs pipeline (evidence: `pageindex/flash/api.py`)
- Flash index API → Tree refinement: refines tree (evidence: `pageindex/flash/api.py`)
- Layout to outline → PDF text parsing: parses pages (evidence: `pageindex/flash/main.py`)
- Layout to outline → Layout and text model: uses structures (evidence: `pageindex/flash/main.py`)
- Layout to outline → Text classification: classifies text (evidence: `pageindex/flash/main.py`)
- Layout to outline → Caption labeling: labels captions (evidence: `pageindex/flash/main.py`)
- Layout to outline → Heading detection: detects headings (evidence: `pageindex/flash/main.py`)
- Layout to outline → Outline assembly: assembles outline (evidence: `pageindex/flash/main.py`)
- Classic indexer → Tree refinement: refines tree (evidence: `pageindex/page_index_classic.py`)
- PageIndex client → Local chat: routes local chat (evidence: `pageindex/client.py`)
- PageIndex client → Agent retrieval tools: exposes tools (evidence: `pageindex/client.py`)
- Local chat → Agent retrieval tools: invokes tools (evidence: `pageindex/local_chat.py`)
- Agent retrieval tools → MCP bridge: uses bridge (evidence: `pageindex/agent_tools.py`)
- PageIndex client → Agent SDK adapters: offers adapters (evidence: `pageindex/client.py`)
- Agent SDK adapters → Agent retrieval tools: wraps tool contract (evidence: `pageindex/integrations/openai_agents.py`)
- Local chat → LLM provider: requests reasoning
- PageIndex client → LLM provider: configures models
