vectorless/client/
mod.rs

1// Copyright (c) 2026 vectorless developers
2// SPDX-License-Identifier: Apache-2.0
3
4//! High-level client API for document indexing and retrieval.
5//!
6//! This module provides the main entry point for using vectorless:
7//! - [`Engine`] — The main client for indexing and querying documents
8//! - [`EngineBuilder`] — Builder pattern for client configuration
9//! - [`IndexContext`] — Unified input for document indexing
10//! - [`Session`] — Multi-document session management
11//!
12//! # Architecture
13//!
14//! The client module is organized into specialized sub-modules:
15//!
16//! ```text
17//! client/
18//! ├── mod.rs           → Re-exports and documentation
19//! ├── engine.rs        → Main orchestrator
20//! ├── builder.rs       → Builder pattern
21//! ├── index_context.rs → Index input types
22//! ├── types.rs         → Public API types
23//! ├── context.rs       → Request context and configuration
24//! ├── session.rs       → Session management
25//! ├── indexer.rs       → Document indexing operations
26//! ├── retriever.rs     → Query and retrieval operations
27//! ├── workspace.rs     → Workspace CRUD operations
28//! └── events.rs        → Event system and callbacks
29//! ```
30//!
31//! # Quick Start
32//!
33//! ```rust,no_run
34//! use vectorless::client::{Engine, EngineBuilder, IndexContext};
35//!
36//! # #[tokio::main]
37//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
38//! // Create a client with default settings
39//! let client = EngineBuilder::new()
40//!     .with_workspace("./my_workspace")
41//!     .build()
42//!     .await?;
43//!
44//! // Index a document from file
45//! let doc_id = client.index(IndexContext::from_path("./document.md")).await?;
46//!
47//! // Index HTML content directly
48//! let html = "<html><body><h1>Title</h1><p>Content</p></body></html>";
49//! let doc_id2 = client.index(
50//!     IndexContext::from_content(html, vectorless::parser::DocumentFormat::Html)
51//!         .with_name("webpage")
52//! ).await?;
53//!
54//! // Query the document
55//! let result = client.query(&doc_id, "What is this?").await?;
56//! println!("{}", result.content);
57//!
58//! // List all documents
59//! for doc in client.list_documents().await? {
60//!     println!("{}: {}", doc.id, doc.name);
61//! }
62//! # Ok(())
63//! # }
64//! ```
65//!
66//! # Session-Based Operations
67//!
68//! For multi-document operations, use sessions:
69//!
70//! ```rust,no_run
71//! # use vectorless::client::{Engine, EngineBuilder, IndexContext};
72//! # #[tokio::main]
73//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
74//! let client = EngineBuilder::new()
75//!     .with_workspace("./workspace")
76//!     .build()
77//!     .await?;
78//!
79//! let session = client.session().await;
80//!
81//! // Index multiple documents
82//! let doc1 = session.index(IndexContext::from_path("./doc1.md")).await?;
83//! let doc2 = session.index(IndexContext::from_path("./doc2.md")).await?;
84//!
85//! // Query across all documents
86//! let results = session.query_all("What is the architecture?").await?;
87//! # Ok(())
88//! # }
89//! ```
90//!
91//! # Events and Progress
92//!
93//! Monitor operation progress with events:
94//!
95//! ```rust,no_run
96//! # use vectorless::client::{Engine, EngineBuilder, EventEmitter, IndexEvent};
97//! # #[tokio::main]
98//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
99//! let events = EventEmitter::new()
100//!     .on_index(|e| match e {
101//!         IndexEvent::Complete { doc_id } => println!("Indexed: {}", doc_id),
102//!         _ => {}
103//!     });
104//!
105//! let client = EngineBuilder::new()
106//!     .with_events(events)
107//!     .build()
108//!     .await?;
109//! # Ok(())
110//! # }
111//! ```
112//!
113//! # Features
114//!
115//! - **Document Indexing** — Parse and index Markdown, PDF, and text files
116//! - **Tree-Based Structure** — Documents organized as hierarchical trees
117//! - **Workspace Persistence** — Save and load indexed documents
118//! - **Session Management** — Multi-document operations with caching
119//! - **Event System** — Progress callbacks and monitoring
120
121mod builder;
122mod context;
123mod engine;
124pub mod events;
125mod index_context;
126mod indexer;
127mod retriever;
128mod session;
129mod types;
130mod workspace;
131
132// ============================================================
133// Main Types
134// ============================================================
135
136pub use builder::{BuildError, EngineBuilder};
137pub use engine::Engine;
138
139// ============================================================
140// Index Context
141// ============================================================
142
143pub use index_context::{IndexContext, IndexSource};
144
145// ============================================================
146// Sub-Clients
147// ============================================================
148
149pub use indexer::IndexerClient;
150pub use retriever::RetrieverClient;
151pub use session::Session;
152pub use workspace::WorkspaceClient;
153
154// ============================================================
155// Context and Events
156// ============================================================
157
158pub use context::{ClientContext, FeatureFlags, RequestContextConfig};
159pub use events::{
160    AsyncEventHandler, Event, EventEmitter, EventHandler, IndexEvent, QueryEvent, WorkspaceEvent,
161};
162
163// ============================================================
164// Types
165// ============================================================
166
167pub use types::{
168    // Error types
169    ClientError,
170    // Document info
171    DocumentInfo,
172    // Index types
173    IndexMode,
174    IndexOptions,
175    // Document types
176    IndexedDocument,
177    PageContent,
178    // Query types
179    QueryResult,
180};
181
182// ============================================================
183// Sub-Client Types
184// ============================================================
185
186pub use indexer::{IndexerConfig, ValidationResult};
187pub use retriever::{NodeContext, RetrieverClientConfig};
188pub use session::{EvictionPolicy, PreloadStrategy, SessionConfig, SessionStats};
189pub use workspace::{WorkspaceClientConfig, WorkspaceStats};
vectorless/client/mod.rs

vectorless/client/
mod.rs
