Skip to content

Commit 32157c5

Browse files
zTgxzTgx
committed
docs: enhance documentation with detailed guides and updates
- rewrite main README with comprehensive overview of Vectorless features - add dual pipeline guide explaining index and retrieval architecture - create quick start guide with installation and basic usage examples - update RFCs table with implemented parser statuses - reorganize documentation structure with clear sections - add architecture diagrams and detailed pipeline explanations - include practical examples for different document formats feat: rename JudgeStage to EvaluateStage for clarity - rename JudgeStage to EvaluateStage to better reflect functionality - update all references in orchestrator, pipeline, and stage implementations - change metric field from judge_time_ms to evaluate_time_ms - update stage names in pipeline context and execution flow - maintain preserved names like LlmJudge for specific components - update documentation and examples to use new naming convention docs(rfcs): add RFC-0003 for evaluate stage naming - document rationale for renaming JudgeStage to EvaluateStage - explain motivation behind choosing "Evaluate" over "Judge" - specify changes to file names, struct names, and references - preserve existing LlmJudge terminology where appropriate - update pipeline flow diagrams and implementation steps
1 parent 00a2df3 commit 32157c5

16 files changed

Lines changed: 376 additions & 65 deletions

File tree

‎docs/README.md‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,51 @@
11
# Vectorless Documentation
22

3-
## Brand Assets
3+
Welcome to the Vectorless documentation.
44

5-
Logos and icons for use in README, website, and presentations.
5+
## What is Vectorless?
66

7-
- [assets/brand/](assets/brand/) — Logo variants (light, dark, horizontal, icon)
7+
Vectorless is a **reasoning-native document intelligence engine** that uses LLM-powered tree navigation instead of vector embeddings. It preserves document structure and uses intelligent navigation to find relevant content.
88

9-
## Design Documents
9+
## Key Features
1010

11-
System architecture and core mechanism documentation.
11+
- **Dual Pipeline Architecture** - Separate Index and Retrieval pipelines
12+
- **Pilot System** - LLM-guided navigation with layered fallback
13+
- **Multi-Strategy Retrieval** - Keyword, LLM, and Structure-aware strategies
14+
- **Zero Infrastructure** - No vector database, no embeddings
15+
- **Multi-Format Support** - Markdown, PDF, DOCX, HTML
1216

13-
| Document | Description |
14-
|----------|-------------|
15-
| [architecture.svg](design/architecture.svg) | System architecture diagram |
16-
| [recovery.md](design/recovery.md) | Graceful degradation and error recovery strategy |
17+
## Getting Started
1718

18-
## Development Guides
19+
- [Quick Start Guide](guides/quick-start.md) - Get up and running in 5 minutes
1920

20-
Guides for using and contributing to Vectorless.
21+
## Guides
2122

2223
| Guide | Description |
2324
|-------|-------------|
24-
| [deployment.md](guides/deployment.md) | Production deployment checklist |
25+
| [Quick Start](guides/quick-start.md) | Get up and running quickly |
26+
| [Dual Pipeline](guides/dual-pipeline.md) | Understand Index + Retrieval pipelines |
27+
| [Pilot System](guides/pilot-system.md) | LLM-guided navigation |
28+
| [Multi-Strategy Retrieval](guides/multi-strategy.md) | Keyword, LLM, Structure strategies |
29+
30+
## Design Documents
31+
32+
System architecture and core mechanism documentation.
33+
34+
| Document | Description |
35+
|----------|-------------|
36+
| [pilot.md](design/pilot.md) | Pilot system design |
37+
| [content-aggregation.md](design/content-aggregation.md) | Content aggregation design |
38+
| [client-module.md](design/client-module.md) | Client API design |
39+
| [v3.md](design/v3.md) | Version 3 architecture |
2540

2641
## RFCs (Feature Proposals)
2742

2843
Detailed design documents for new features.
2944

3045
| RFC | Title | Status |
3146
|-----|-------|--------|
32-
| [0001](rfcs/0001-docx-parser.md) | DOCX Parser | Proposed |
47+
| [0001](rfcs/0001-docx-parser.md) | DOCX Parser | Implemented |
48+
| [0002](rfcs/0002-html-parser.md) | HTML Parser | Implemented |
3349

3450
### RFC Process
3551

‎docs/guides/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
1-
# Guide
1+
# Vectorless Guides
2+
3+
Practical guides for using Vectorless effectively.

‎docs/guides/dual-pipeline.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Understanding the Dual Pipeline
2+
3+
Vectorless uses a **dual pipeline architecture** that separates document processing from retrieval. This design enables efficient indexing and intelligent retrieval.
4+
5+
## Architecture Overview
6+
7+
```
8+
┌─────────────────────────────────────────────────────────────────────────────┐
9+
│ Vectorless Architecture │
10+
├─────────────────────────────────────────────────────────────────────────────┤
11+
│ │
12+
│ ┌─────────────────────────────┐ ┌─────────────────────────────┐ │
13+
│ │ INDEX PIPELINE │ │ RETRIEVAL PIPELINE │ │
14+
│ │ │ │ │ │
15+
│ │ Parse → Build → Enrich │ │ Analyze → Plan → Search │ │
16+
│ │ ↓ ↓ ↓ │ │ ↓ ↓ ↓ │ │
17+
│ │ Enhance → Optimize → │ │ Evaluate (Sufficiency) │ │
18+
│ │ Persist │ │ ↑_____________│ │ │
19+
│ │ │ │ │ (NeedMoreData)│ │ │
20+
│ └─────────────────────────────┘ └─────────────────────────────┘ │
21+
│ │ ▲ │
22+
│ └──────────── Workspace ─────────────┘ │
23+
│ │
24+
└─────────────────────────────────────────────────────────────────────────────┘
25+
```
26+
27+
## Index Pipeline
28+
29+
The Index Pipeline processes documents and builds a searchable tree structure.
30+
31+
### Stages
32+
33+
| Stage | Purpose |
34+
|-------|---------|
35+
| **Parse** | Extract content from file (MD, PDF, DOCX, HTML) |
36+
| **Build** | Construct hierarchical document tree |
37+
| **Enrich** | Add metadata, TOC, references |
38+
| **Enhance** | Generate summaries (optional) |
39+
| **Optimize** | Prune, compress, optimize tree |
40+
| **Persist** | Save to workspace storage |
41+
42+
### Example
43+
44+
```rust
45+
// Index pipeline is triggered automatically
46+
let doc_id = engine.index(IndexContext::from_path("./manual.md")).await?;
47+
48+
// With summary generation
49+
let doc_id = engine.index(
50+
IndexContext::from_path("./manual.md")
51+
.with_options(IndexOptions::new().with_summaries())
52+
).await?;
53+
```
54+
55+
## Retrieval Pipeline
56+
57+
The Retrieval Pipeline processes queries and retrieves relevant content.
58+
59+
### Stages
60+
61+
| Stage | Purpose |
62+
|-------|---------|
63+
| **Analyze** | Analyze query complexity, extract keywords |
64+
| **Plan** | Select retrieval strategy and algorithm |
65+
| **Search** | Navigate tree to find candidates |
66+
| **Evaluate** | Check sufficiency, aggregate content |
67+
68+
### The Evaluate Stage
69+
70+
The Evaluate stage is crucial - it determines if retrieved content is sufficient:
71+
72+
```text
73+
┌─────────────┐
74+
│ Search │
75+
└──────┬──────┘
76+
│
77+
▼
78+
┌─────────────┐
79+
│ Evaluate │
80+
└──────┬──────┘
81+
│
82+
┌────────────┼────────────┐
83+
│ │ │
84+
▼ ▼ ▼
85+
Sufficient PartialSufficient Insufficient
86+
│ │ │
87+
▼ ▼ ▼
88+
Return More Search Expand Beam
89+
(1 iteration) (2 iterations)
90+
```
91+
92+
### Retrieval Strategies
93+
94+
```rust
95+
// Three built-in strategies:
96+
97+
// 1. Keyword - Fast, exact matching
98+
// 2. LLM - Semantic understanding via Pilot
99+
// 3. Structure - Hierarchy-aware navigation
100+
```
101+
102+
## The Pilot System
103+
104+
Pilot is the "brain" of the Retrieval Pipeline:
105+
106+
- **Query Analysis**: Understands what the user is asking
107+
- **Context Building**: Creates navigation context from TOC
108+
- **Decision Making**: Decides which branches to explore
109+
- **Fallback**: Algorithm takes over when LLM fails
110+
111+
See [The Pilot System](./pilot-system.md) for details.
112+
113+
## Data Flow
114+
115+
```
116+
Document ──► Index Pipeline ──► Workspace
117+
│
118+
Query ──► Retrieval Pipeline ──────────┘
119+
│
120+
▼
121+
RetrievalResult
122+
├── content
123+
├── node_ids
124+
├── confidence
125+
└── trace
126+
```
127+
128+
## Session-Based Operations
129+
130+
For multi-document operations, use sessions:
131+
132+
```rust
133+
// Create a session
134+
let session = engine.session().await;
135+
136+
// Index multiple documents
137+
session.index(IndexContext::from_path("./doc1.md")).await?;
138+
session.index(IndexContext::from_path("./doc2.md")).await?;
139+
140+
// Query across all documents
141+
let results = session.query_all("What is the architecture?").await?;
142+
143+
for result in results {
144+
println!("From {}: {}", result.doc_id, result.content);
145+
}
146+
```
147+
148+
## See Also
149+
150+
- [Multi-Strategy Retrieval](./multi-strategy.md)
151+
- [Content Aggregation](./content-aggregation.md)
152+
- [Sufficiency Checking](./sufficiency.md)

‎docs/guides/quick-start.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Quick Start Guide
2+
3+
Get up and running with Vectorless in 5 minutes.
4+
5+
## Prerequisites
6+
7+
- Rust 1.70+ installed
8+
- An OpenAI API key (or compatible LLM endpoint)
9+
10+
## Installation
11+
12+
Add to your `Cargo.toml`:
13+
14+
```toml
15+
[dependencies]
16+
vectorless = "0.1"
17+
tokio = { version = "1", features = ["full"] }
18+
```
19+
20+
## Basic Usage
21+
22+
```rust
23+
use vectorless::{Engine, IndexContext};
24+
25+
#[tokio::main]
26+
async fn main() -> Result<(), Box<dyn std::error::Error>> {
27+
// 1. Create an engine with OpenAI
28+
let engine = Engine::builder()
29+
.with_workspace("./workspace")
30+
.with_openai(std::env::var("OPENAI_API_KEY")?)
31+
.build()
32+
.await?;
33+
34+
// 2. Index a document
35+
let doc_id = engine.index(IndexContext::from_path("./manual.md")).await?;
36+
println!("Indexed: {}", doc_id);
37+
38+
// 3. Query the document
39+
let result = engine.query(&doc_id, "How do I configure authentication?").await?;
40+
println!("Answer: {}", result.content);
41+
42+
Ok(())
43+
}
44+
```
45+
46+
## Index from Different Sources
47+
48+
```rust
49+
// From file path
50+
let id1 = engine.index(IndexContext::from_path("./doc.pdf")).await?;
51+
52+
// From string content
53+
let html = "<html><body><h1>Title</h1><p>Content</p></body></html>";
54+
let id2 = engine.index(
55+
IndexContext::from_content(html, vectorless::parser::DocumentFormat::Html)
56+
.with_name("webpage")
57+
).await?;
58+
59+
// From bytes (e.g., from HTTP response)
60+
let pdf_bytes = std::fs::read("./document.pdf")?;
61+
let id3 = engine.index(
62+
IndexContext::from_bytes(pdf_bytes, vectorless::parser::DocumentFormat::Pdf)
63+
).await?;
64+
```
65+
66+
## Index Modes
67+
68+
```rust
69+
use vectorless::IndexMode;
70+
71+
// Default: Skip if already indexed
72+
engine.index(IndexContext::from_path("./doc.md")).await?;
73+
74+
// Force: Always re-index
75+
engine.index(
76+
IndexContext::from_path("./doc.md").with_mode(IndexMode::Force)
77+
).await?;
78+
79+
// Incremental: Only re-index if changed
80+
engine.index(
81+
IndexContext::from_path("./doc.md").with_mode(IndexMode::Incremental)
82+
).await?;
83+
```
84+
85+
## Next Steps
86+
87+
- [Understanding the Dual Pipeline](./dual-pipeline.md) - Learn how Vectorless works
88+
- [Indexing Documents](./indexing.md) - Deep dive into document indexing
89+
- [Querying Documents](./querying.md) - Advanced query techniques

‎docs/rfcs/0003-evaluate-stage.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# RFC-0003: Evaluate Stage Naming
2+
3+
## Summary
4+
5+
Rename the `JudgeStage` to `EvaluateStage` to better reflect its purpose in the retrieval pipeline.
6+
7+
## Motivation
8+
9+
The term "judge" implies a binary verdict, while the stage actually:
10+
1. Aggregates content from candidates
11+
2. Evaluates sufficiency levels (Sufficient, Partial, Insufficient)
12+
3. Can trigger additional search iterations
13+
4. Builds the final response
14+
15+
"Evaluate" better captures the nuanced assessment process.
16+
17+
## Design
18+
19+
### Changes
20+
21+
| Before | After |
22+
|--------|-------|
23+
| `JudgeStage` | `EvaluateStage` |
24+
| `judge.rs` | `evaluate.rs` |
25+
| `judge_time_ms` | `evaluate_time_ms` |
26+
| `"judge"` stage name | `"evaluate"` stage name |
27+
28+
### Preserved Names
29+
30+
The following are intentionally preserved:
31+
- `LlmJudge` - The sufficiency checker that "judges" sufficiency
32+
- `llm_judge` - Field name for the LLM-based sufficiency judge
33+
34+
These remain as they specifically make a judgment call on sufficiency.
35+
36+
## Pipeline Flow Update
37+
38+
```
39+
Before: Analyze → Plan → Search → Judge
40+
After: Analyze → Plan → Search → Evaluate
41+
```
42+
43+
## Implementation
44+
45+
1. Rename `src/retrieval/stages/judge.rs` to `evaluate.rs`
46+
2. Update struct name from `JudgeStage` to `EvaluateStage`
47+
3. Update all references in pipeline and retriever code
48+
4. Update documentation and diagrams
49+
50+
## Status
51+
52+
**Implemented** - 2026-04-05

‎examples/retrieve.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ use vectorless::document::DocumentTree;
2020
use vectorless::retrieval::{
2121
PipelineRetriever, RetrieveOptions, Retriever, StrategyPreference,
2222
pipeline::RetrievalOrchestrator,
23-
stages::{AnalyzeStage, JudgeStage, PlanStage, SearchStage},
23+
stages::{AnalyzeStage, EvaluateStage, PlanStage, SearchStage},
2424
};
2525

2626
#[tokio::main]
@@ -119,7 +119,7 @@ async fn demo_orchestrator(tree: &DocumentTree) -> vectorless::Result<()> {
119119
.stage(AnalyzeStage::new())
120120
.stage(PlanStage::new())
121121
.stage(SearchStage::new())
122-
.stage(JudgeStage::new());
122+
.stage(EvaluateStage::new());
123123

124124
println!("Orchestrator stages:");
125125
if let Ok(names) = orchestrator.stage_names() {

0 commit comments

Comments
 (0)