|
3 | 3 | <img src="https://vectorless.dev/img/with-title.png" alt="Vectorless" width="400"> |
4 | 4 |
|
5 | 5 | <h1>Reasoning-based Document Engine</h1> |
| 6 | +<h5>Reason, don't vector · Structure, not chunks · Agents, not embeddings · Exact, not synthesized</h5> |
6 | 7 |
|
7 | 8 | [](https://pypi.org/project/vectorless/) |
8 | 9 | [](https://pepy.tech/projects/vectorless) |
|
13 | 14 |
|
14 | 15 | </div> |
15 | 16 |
|
16 | | -**Reason, don't vector.** |
| 17 | +**Vectorless** is a reasoning-native document engine written in Rust. It compiles documents into navigable trees, then dispatches **multiple agents** to find exactly what's relevant across your **PDFs, Markdown, reports, contracts**. No embeddings, no chunking, no approximate nearest neighbors. Every retrieval is a **reasoning** act. |
17 | 18 |
|
18 | | -**Vectorless** is a reasoning-based document engine with the core written in Rust. It will reason through any of your structured documents — **PDFs, Markdown, reports, contracts** — and retrieve only what's relevant. Nothing more, nothing less. |
| 19 | +Light up a star and shine with us! ⭐ |
19 | 20 |
|
| 21 | +## Three Rules |
| 22 | +- **Reason, don't vector.** Retrieval is a reasoning act, not a similarity computation. |
| 23 | +- **Model fails, we fail.** No heuristic fallbacks, no silent degradation. |
| 24 | +- **No thought, no answer.** Only reasoned output counts as an answer. |
| 25 | + |
| 26 | +## Why Vectorless |
| 27 | + |
| 28 | +Traditional RAG systems split documents into chunks, embed them into vectors, and retrieve by similarity. Vectorless takes a different approach: it preserves document structure as a navigable tree and lets agents reason through it. |
| 29 | + |
| 30 | +| | Embedding-Based RAG | Vectorless | |
| 31 | +|---|---|---| |
| 32 | +| **Indexing** | Chunk → embed → vector store | Parse → compile → document tree | |
| 33 | +| **Retrieval** | Cosine similarity (approximate) | Multi-agent navigation (exact) | |
| 34 | +| **Structure** | Destroyed by chunking | Preserved as first-class tree | |
| 35 | +| **Query handling** | Keyword/similarity match | Intent classification + decomposition | |
| 36 | +| **Multi-hop reasoning** | Not supported | Orchestrator replans dynamically | |
| 37 | +| **Output** | Retrieved chunks | Original text passages, exact | |
| 38 | +| **Failure mode** | Silent degradation | Explicit — no reasoning, no answer | |
| 39 | + |
| 40 | +## How It Works |
| 41 | + |
| 42 | +### Four-Artifact Index Architecture |
| 43 | + |
| 44 | +When a document is indexed, the compile pipeline builds four artifacts: |
| 45 | + |
| 46 | +``` |
| 47 | +Content Layer Navigation Layer Reasoning Index Document Card |
| 48 | +DocumentTree NavigationIndex ReasoningIndex DocCard |
| 49 | +(TreeNode) (NavEntry, ChildRoute) (topic_paths, hot_nodes) (title, overview, |
| 50 | + │ │ │ question hints) |
| 51 | + │ │ │ │ |
| 52 | + Agent reads Agent reads every Agent's targeted Orchestrator reads |
| 53 | + only on cat decision round search tool (grep) for multi-doc routing |
| 54 | +``` |
| 55 | + |
| 56 | +- **Content Layer** — The raw document tree. The agent only accesses this when reading specific paragraphs (`cat`). |
| 57 | +- **Navigation Layer** — Each non-leaf node stores an overview, question hints, and child routes (title + description). The agent reads this every round to decide where to go next. |
| 58 | +- **Reasoning Index** — Keyword-topic mappings with weights. Provides the agent's `grep` tool with structured keyword data for targeted search within a document. |
| 59 | +- **DocCard** — A compact document-level summary. The Orchestrator reads DocCards to decide which documents to navigate in multi-document queries, without loading full documents. |
| 60 | + |
| 61 | +This separation means the agent makes routing decisions from lightweight metadata, not by scanning full content. |
| 62 | + |
| 63 | +### Agent-Based Retrieval |
| 64 | + |
| 65 | +``` |
| 66 | +Engine.query("What drove the revenue decline?") |
| 67 | + │ |
| 68 | + ├─ Query Understanding ── intent, concepts, strategy (LLM) |
| 69 | + │ |
| 70 | + ├─ Orchestrator ── analyzes query, dispatches Workers |
| 71 | + │ │ |
| 72 | + │ ├─ Worker 1 ── ls → cd "Financials" → ls → cd "Revenue" → cat |
| 73 | + │ └─ Worker 2 ── ls → cd "Risk Factors" → grep "decline" → cat |
| 74 | + │ │ |
| 75 | + │ └─ evaluate ── insufficient? → replan → dispatch new paths → loop |
| 76 | + │ |
| 77 | + └─ Fusion ── dedup, LLM-scored relevance, return with source attribution |
| 78 | +``` |
| 79 | + |
| 80 | +Worker navigation commands: |
| 81 | + |
| 82 | +| Command | Action | Reads | |
| 83 | +|---------|--------|-------| |
| 84 | +| `ls` | List child sections | Navigation Layer (ChildRoute) | |
| 85 | +| `cd` | Enter a child section | Navigation Layer | |
| 86 | +| `cat` | Read content at current node | Content Layer (DocumentTree) | |
| 87 | +| `grep` | Search by keyword | Reasoning Index (topic_paths) | |
| 88 | + |
| 89 | +The Orchestrator evaluates Worker results after each round. If evidence is insufficient, it **replans** — adjusting strategy, dispatching new paths, or deepening exploration. This continues until enough evidence is collected. |
20 | 90 |
|
21 | 91 | ## Quick Start |
22 | 92 |
|
@@ -44,19 +114,30 @@ async def main(): |
44 | 114 | asyncio.run(main()) |
45 | 115 | ``` |
46 | 116 |
|
47 | | -## What It's For |
| 117 | +## Key Features |
| 118 | + |
| 119 | +- **Rust Core** — The entire engine (indexing, retrieval, agent, storage) is implemented in Rust for performance and reliability. Python SDK via PyO3 bindings and a CLI are also provided. |
| 120 | +- **Multi-Agent Retrieval** — Every query is handled by multiple cooperating agents: an Orchestrator plans and evaluates, Workers navigate documents. Each retrieval is a reasoning act — not a similarity score, but a sequence of LLM decisions about where to look, what to read, and when to stop. |
| 121 | +- **Zero Vectors** — No embedding model, no vector store, no similarity search. This eliminates a class of failure modes: wrong chunk boundaries, stale embeddings, and similarity-score false positives. |
| 122 | +- **Tree Navigation** — Documents are compiled into hierarchical trees that preserve the original structure — headings, sections, paragraphs, lists. Workers navigate this tree the way a human would: scan the table of contents, jump to the relevant section, read the passage. |
| 123 | +- **Document-Exact Output** — Returns original text passages from the source document. No synthesis, no rewriting, no hallucinated content. What you get is what was written. |
| 124 | +- **Multi-Document Orchestration** — Query across multiple documents with a single call. The Orchestrator dispatches Workers, evaluates evidence, and fuses results. When one document is insufficient, it replans and expands the search scope. |
| 125 | +- **Query Understanding** — Every query passes through LLM-based intent classification, concept extraction, and strategy selection. Complex queries are decomposed into sub-queries. The system adapts its navigation strategy based on whether the query is factual, analytical, comparative, or navigational. |
| 126 | +- **Checkpointable Pipeline** — The 8-stage compile pipeline writes checkpoints at each stage. If indexing is interrupted (LLM rate limit, network failure), it resumes from the last completed stage — no wasted work. |
| 127 | +- **Incremental Updates** — Content fingerprinting detects changes at the node level. Re-indexing a modified document only recompiles the changed sections and their dependents. |
48 | 128 |
|
49 | | -Vectorless is designed for applications that need **precise** document retrieval: |
| 129 | +## Supported Documents |
50 | 130 |
|
51 | | -- **Financial analysis** — Extract specific figures from reports, compare across filings |
52 | | -- **Legal research** — Find relevant clauses, trace definitions across documents |
53 | | -- **Technical documentation** — Navigate large manuals, locate specific procedures |
54 | | -- **Academic research** — Cross-reference findings across papers |
55 | | -- **Compliance** — Audit trails with source references for every answer |
| 131 | +- **PDF** — Full text extraction with page metadata |
| 132 | +- **Markdown** — Structure-aware parsing (headings, lists, code blocks) |
56 | 133 |
|
57 | | -## Examples |
| 134 | +## Resources |
58 | 135 |
|
59 | | -See [examples/](examples/) for complete usage patterns. |
| 136 | +- [Documentation](https://vectorless.dev) — Guides, architecture, API reference |
| 137 | +- [Rust API Docs](https://docs.rs/vectorless) — Auto-generated crate documentation |
| 138 | +- [PyPI](https://pypi.org/project/vectorless/) — Python package |
| 139 | +- [Crates.io](https://crates.io/crates/vectorless) — Rust crate |
| 140 | +- [Examples](examples/) — Complete usage patterns for Python and Rust |
60 | 141 |
|
61 | 142 | ## Contributing |
62 | 143 |
|
|
0 commit comments