vectorless/lib.rs
1// Copyright (c) 2026 vectorless developers
2// SPDX-License-Identifier: Apache-2.0
3
4//! # Vectorless
5
6// Clippy: allow some pedantic lints that are too noisy for early-stage project
7#![allow(clippy::all)]
8#![allow(dead_code)]
9#![allow(unused_variables)]
10#![allow(unused_imports)]
11#![allow(clippy::iter_over_hash_type)]
12#![allow(clippy::large_enum_variant)]
13#![allow(clippy::manual_unwrap_or_default)]
14
15//! # Vectorless
16//!
17//! **A hierarchical, reasoning-native document intelligence engine.**
18//!
19//! Replace your vector database with LLM-powered tree navigation.
20//! No embeddings. No vector search. Just reasoning.
21//!
22//! ## Overview
23//!
24//! Traditional RAG systems chunk documents into flat vectors, losing structure.
25//! Vectorless preserves your document's hierarchy and uses an LLM to navigate it —
26//! like a human skimming a table of contents, then drilling into relevant sections.
27//!
28//! ## Architecture
29//!
30//! ```text
31//! ┌─────────────────────────────────────────────────┐
32//! │ USER │
33//! │ (Query / Index) │
34//! └────────────────────────┬────────────────────────┘
35//! │
36//! ▼
37//! ┌─────────────────────────────────────────────────────────────────────────────────┐
38//! │ CLIENT LAYER │
39//! │ ┌───────────────────────────────────────────────────────────────────────────┐ │
40//! │ │ Engine / EngineBuilder │ │
41//! │ │ (Unified API for Index + Query) │ │
42//! │ └───────────────────────────────────────────────────────────────────────────┘ │
43//! └─────────────────────────────────────────────────────────────────────────────────┘
44//! │
45//! ┌────────────────────────┴────────────────────────┐
46//! │ │
47//! ▼ ▼
48//! ┌──────────────────────────────────────────────┐ ┌──────────────────────────────────────────────┐
49//! │ INDEX PIPELINE │ │ RETRIEVAL ENGINE │
50//! │ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ │ ┌─────────────────────────────────────┐ │
51//! │ │ Parse │─▶│ Build │─▶│ Enhance │ │ │ │ Pilot (LLM) │ │
52//! │ │ (Doc) │ │ (Tree) │ │ (Summaries) │ │ │ │ ┌───────────────────────┐ │ │
53//! │ └─────────┘ └────┬────┘ └──────┬──────┘ │ │ │ │ Navigation Agent │ │ │
54//! │ │ │ │ │ │ │ │ ┌─────┐ ┌─────────┐ │ │ │
55//! │ ▼ ▼ ▼ │ │ │ │ │Decide│▶│Traverse │ │ │ │
56//! │ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ │ │ │ │Path │ │ Tree │ │ │ │
57//! │ │ Enrich │─▶│ Optimize│─▶│ Persist │ │ │ │ │ └─────┘ └─────────┘ │ │ │
58//! │ │(Meta) │ │ (Tree) │ │ (Storage) │ │ │ │ └───────────────────────┘ │ │
59//! │ └─────────┘ └─────────┘ └─────────────┘ │ │ └─────────────────────────────────────┘ │
60//! │ │ │ │ │ │
61//! │ │ ┌──────────────────────┐ │ │ ▼ │
62//! │ └────────▶│ Change Detector │◀─────┼───┤ ┌─────────────────────────────────────┐ │
63//! │ │ (Fingerprint-based) │ │ │ │ Context Assembler │ │
64//! │ └──────────────────────┘ │ │ │ ┌─────────┐ ┌─────────────────┐ │ │
65//! │ │ │ │ │ Pruning │ │ Token Budget │ │ │
66//! └──────────────────────────────────────────────┘ │ │ │Strategy │ │ Management │ │ │
67//! │ │ │ └─────────┘ └─────────────────┘ │ │
68//! │ │ └─────────────────────────────────────┘ │
69//! │ │ │ │
70//! ▼ │ ▼ │
71//! ┌──────────────────────────────────────────────────────────────────────────────────────────────┐
72//! │ DOMAIN LAYER (Core) │
73//! │ │
74//! │ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │
75//! │ │ DocumentTree │ │ TreeNode │ │ NodeId │ │
76//! │ │ (Arena-based) │────▶│ - title │ │ (indextree) │ │
77//! │ │ │ │ - content │ │ │ │
78//! │ └───────────────────┘ │ - summary │ └───────────────────┘ │
79//! │ │ │ - depth │ │ │
80//! │ ▼ │ - token_count │ │ │
81//! │ ┌───────────────────┐ └───────────────────┘ │ │
82//! │ │ TocView │ │ │ │
83//! │ │ (Table of │ │ │ │
84//! │ │ Contents) │ │ │ │
85//! │ └───────────────────┘ │ │ │
86//! └──────────────────────────────────────────────────────────────────────────────────────────────┘
87//! │ │
88//! ┌─────────────────┴─────────────────────────┴─────────────────┐
89//! │ │
90//! ▼ ▼
91//! ┌─────────────────────────────────────────┐ ┌─────────────────────────────────────────────────┐
92//! │ SUPPORT LAYER │ │ STORAGE LAYER │
93//! │ │ │ │
94//! │ ┌─────────────┐ ┌──────────────────┐ │ │ ┌────────────────┐ ┌─────────────────────┐ │
95//! │ │ LLM │ │ Parser │ │ │ │ Workspace │ │ MemoStore │ │
96//! │ │ (OpenAI) │ │ - Markdown │ │ │ │ (Persistence) │ │ (LLM Cache) │ │
97//! │ │ │ │ - PDF │ │ │ │ │ │ - LRU Eviction │ │
98//! │ │ ┌─────────┐ │ │ - DOCX │ │ │ │ ┌────────────┐ │ │ - TTL Expiration │ │
99//! │ │ │ Pool │ │ │ │ │ │ │ │ LRU │ │ │ - Disk Persist │ │
100//! │ │ │ Retry │ │ └──────────────────┘ │ │ │ │ Cache │ │ │ │ │
101//! │ │ │ Fallback│ │ │ │ │ └────────────┘ │ └─────────────────────┘ │
102//! │ │ └─────────┘ │ ┌──────────────────┐ │ │ │ │ │
103//! │ └─────────────┘ │ Fingerprint │ │ │ │ ┌────────────┐ │ ┌─────────────────────┐ │
104//! │ │ (BLAKE2b) │ │ │ │ │ Atomic │ │ │ ChangeDetector │ │
105//! │ ┌─────────────┐ │ │ │ │ │ │ Writes │ │ │ (Incremental) │ │
106//! │ │ Config │ │ ┌──────────────┐ │ │ │ │ └────────────┘ │ │ │ │
107//! │ │ Loader │ │ │ Content FP │ │ │ │ │ │ │ ┌─────────────────┐ │ │
108//! │ │ │ │ │ Subtree FP │ │ │ │ └────────────────┘ │ │ Processing Ver │ │ │
109//! │ └─────────────┘ │ │ Node FP │ │ │ │ │ └─────────────────┘ │ │
110//! │ │ └──────────────┘ │ │ │ └─────────────────────┘ │
111//! │ ┌─────────────┐ └──────────────────┘ │ │ │
112//! │ │ Throttle │ │ │ ┌────────────────────────────────────────────┐ │
113//! │ │ (Rate Limit)│ ┌──────────────────┐ │ │ │ DocumentMeta │ │
114//! │ └─────────────┘ │ Throttle │ │ │ │ - content_fingerprint │ │
115//! │ │ (Concurrency) │ │ │ │ - processing_version │ │
116//! │ └──────────────────┘ │ │ │ - node_count, total_summary_tokens │ │
117//! │ │ │ └────────────────────────────────────────────┘ │
118//! └─────────────────────────────────────────┘ └─────────────────────────────────────────────────┘
119//! ```
120//!
121//! ## Data Flow
122//!
123//! ### Indexing Flow
124//! ```text
125//! Document ──▶ Parse ──▶ Build Tree ──▶ Generate Summaries ──▶ Detect Changes ──▶ Persist
126//! │ │ │
127//! │ └──▶ MemoStore ◀───────┘
128//! │ (Cache)
129//! └──▶ Fingerprint ──▶ ChangeDetector
130//! ```
131//!
132//! ### Query Flow
133//! ```text
134//! Query ──▶ Pilot Agent ──▶ Navigate Tree ──▶ Assemble Context ──▶ Return Result
135//! │ │ │
136//! └──▶ LLM ◀────────┘ │
137//! (Decide) │
138//! └──▶ MemoStore (Cached Summaries)
139//! ```
140//!
141//! ## Features
142//!
143//! - 🌳 **Tree-Based Indexing** — Documents as hierarchical trees, not flat chunks
144//! - 🧠 **LLM Navigation** — Reasoning-based traversal to find relevant content
145//! - 🚀 **Zero Infrastructure** — No vector database, no embedding models
146//! - 📄 **Multi-Format** — Markdown, PDF, DOCX support
147//! - 💾 **Persistent Workspace** — LRU-cached storage with lazy loading
148//! - 🔄 **Retry & Fallback** — Resilient LLM calls with automatic recovery
149//! - 🔍 **Incremental Updates** — Fingerprint-based change detection
150//! - ⚡ **LLM Memoization** — Cache summaries and decisions to reduce costs
151//!
152//! ## Quick Start
153//!
154//! ```rust,no_run
155//! use vectorless::{EngineBuilder, Engine};
156//! use vectorless::client::IndexContext;
157//!
158//! #[tokio::main]
159//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
160//! // Create client
161//! let client = EngineBuilder::new()
162//! .with_workspace("./workspace")
163//! .build()
164//! .await?;
165//!
166//! // Index a document
167//! let doc_id = client.index(IndexContext::from_path("./document.md")).await?;
168//!
169//! // Query with natural language
170//! let result = client.query(&doc_id, "What is this about?").await?;
171//! println!("{}", result.content);
172//!
173//! Ok(())
174//! }
175//! ```
176//!
177//! ## Modules
178//!
179//! | Module | Description |
180//! |--------|-------------|
181//! | [`client`] | High-level API (`Engine`, `EngineBuilder`) |
182//! | [`document`] | Core domain types (`DocumentTree`, `TreeNode`, `NodeId`) |
183//! | [`index`] | Document indexing pipeline with incremental updates |
184//! | [`retrieval`] | Retrieval strategies and LLM-based navigation |
185//! | [`config`] | Configuration management |
186//! | [`llm`] | LLM client with retry & fallback |
187//! | [`parser`] | Document parsers (Markdown, PDF, DOCX) |
188//! | [`storage`] | Workspace persistence with LRU caching |
189//! | [`throttle`] | Rate limiting and concurrency control |
190//! | [`fingerprint`] | Content and subtree fingerprinting |
191//! | [`memo`] | LLM result memoization and caching |
192
193// =============================================================================
194// Modules
195// =============================================================================
196
197pub mod client;
198pub mod config;
199pub mod document;
200pub mod error;
201pub mod index;
202pub mod llm;
203pub mod memo;
204pub mod metrics;
205pub mod parser;
206pub mod retrieval;
207pub mod storage;
208pub mod throttle;
209pub mod utils;
210
211// =============================================================================
212// Re-exports (Convenience API)
213// =============================================================================
214
215// Client API (most common entry point)
216pub use client::{
217 BuildError, DocumentInfo, Engine, EngineBuilder, IndexContext, IndexMode, IndexOptions,
218 IndexSource, IndexedDocument,
219};
220
221// Error types
222pub use error::{Error, Result};
223
224// Document types
225pub use document::{
226 DocumentStructure, DocumentTree, NodeId, StructureNode, TocConfig, TocEntry, TocNode, TocView,
227 TreeNode,
228};
229
230// Utility functions
231pub use utils::{estimate_tokens, estimate_tokens_fast};
232
233// Configuration
234pub use config::{Config, ConfigLoader, RetrievalConfig, SummaryConfig};
235
236// LLM
237pub use llm::{LlmClient, LlmConfig, LlmConfigs, LlmError, LlmPool, RetryConfig};
238
239// Document parsing
240pub use parser::{
241 DocumentFormat, DocumentParser, DocxParser, MarkdownParser, ParseResult, PdfParser, RawNode,
242};
243
244// Indexing
245pub use index::pipeline::{CustomStageBuilder, PipelineOrchestrator};
246pub use index::{
247 ChangeDetector, ChangeSet, IndexContext as PipelineIndexContext, IndexInput, IndexMetrics,
248 IndexMode as PipelineIndexMode, IndexResult, IndexStage, PartialUpdater, PipelineExecutor,
249 PipelineOptions, SummaryStrategy,
250};
251
252// Retrieval
253pub use retrieval::{
254 ContextBuilder, NavigationDecision, NavigationStep, PipelineRetriever, PruningStrategy,
255 QueryComplexity, RetrievalContext, RetrievalResult, RetrieveOptions, RetrieveResponse,
256 Retriever, RetrieverError, RetrieverResult, SearchPath, StrategyPreference, SufficiencyLevel,
257 TokenEstimation, format_for_llm, format_for_llm_async, format_tree_for_llm,
258 format_tree_for_llm_async,
259};
260
261// Storage
262pub use storage::{DocumentMeta as StorageDocumentMeta, PersistedDocument, Workspace};
263
264// Throttle
265pub use throttle::{ConcurrencyConfig, ConcurrencyController, RateLimiter};
266
267// Memo
268pub use memo::{MemoEntry, MemoKey, MemoOpType, MemoStats, MemoStore, MemoValue};