Expand description
Trait-driven RAG framework with runtime hot-swapping.
Zero native dependencies in the default build. cargo build --release
produces a pure-Rust binary that talks to a local Ollama server for models.
No C++ compiler, no cmake, no protoc required.
§Architecture
Every pipeline stage is a trait object — swap any agent at runtime without losing your document index or conversation context:
| Stage | Trait | Built-in backends |
|---|---|---|
| Chat | agents::Generator | Ollama, DeepSeek |
| Memory / Rewrite | agents::Generator | Ollama, DeepSeek |
| Ranking | store::Ranker | RRF fusion, weighted linear, MMR diversity, LLM re-rank |
| Embeddings | embed::Embedder | Ollama, Fastembed (CPU-only), No-op |
| Storage | store::VectorStore | Brute-force (MessagePack), LanceDB |
| Parsing | parsers::DocumentParser | PDF × 5 (incl. vision-VLM), EPUB, DOCX, HTML, Markdown |
§Quick Start
use ragrig::{
ChunkConfig,
embed::EmbedderSpec,
agents::ChatAgentSpec,
parsers::{DocumentParsers, build_parsers},
store::open_store,
vector::{collect_documents, search_similar},
};
use std::path::Path;
// Build agents from spec enums — swap backends by changing the variant.
let embedder = EmbedderSpec::Ollama { model: "nomic-embed-text:latest".into(), request_timeout_secs: None }.build()?;
let chat = ChatAgentSpec::Ollama { model: "gemma2:latest".into(), params: Default::default(), request_timeout_secs: None }.build()?;
// Open or create the vector store.
let folder = Path::new("./my_docs");
let store = open_store(folder).await?;
// Parse PDFs/EPUBs/DOCXs and index them.
let parsers = DocumentParsers::new(build_parsers());
let cfg = ChunkConfig::default(); // 1024 tokens, 128 overlap
collect_documents(&*embedder, &parsers, folder, &cfg, &*store).await?;
// Search and generate.
let results = search_similar(&*embedder, 5, 0.0, &*store, "quantum entanglement").await?;
chat.generate("Summarise the following:\n\n...").await?;See the repository README for the full guide, including the REPL, session persistence, and hot-swap commands.
§Feature Flags
| Flag | Default | Adds |
|---|---|---|
ollama-embed | on | Embeddings via local Ollama server |
internal | on | Pure-Rust brute-force vector store |
internal-embed | off | Fastembed CPU-only embeddings (requires C compiler) |
lancedb | off | LanceDB hybrid vector store (requires protoc, cmake) |
test-fixtures | off | Embedded test fixtures for downstream crates |
Re-exports§
pub use types::AttachedDocument;pub use types::ChatConfig;pub use types::ChunkConfig;pub use types::ChunkMeta;pub use types::ContextSizeMode;pub use types::DocumentType;pub use types::EmbedConfig;pub use types::EpubParserBackend;pub use types::GenerationParams;pub use types::IndexManifest;pub use types::MemoryConfig;pub use types::PaperResult;pub use types::ParseConfig;pub use types::PdfParserBackend;pub use types::RagrigConfig;pub use attach::AppendAttach;pub use attach::AttachStrategy;pub use attach::NoopAttach;pub use attach::PrependAttach;pub use attach::ReplaceAttach;pub use agents::ChatAgentSpec;pub use agents::Generator;pub use agents::MutexGenerator;pub use agents::SimpleGenerator;pub use embed::Embedder;pub use embed::EmbedderSpec;pub use embed::EmbeddingMetadata;pub use embed::NoopEmbedder;pub use embed::OllamaEmbedder;pub use parsers::DocumentParser;pub use parsers::DocumentParsers;pub use parsers::VisionPdfParser;pub use parsers::build_parsers;pub use parsers::chunk_text;pub use parsers::extract_text;pub use fs_session_store::FsSessionStore;pub use longterm_memory::HistoryStrategy;pub use longterm_memory::LogHistory;pub use longterm_memory::MemoryStrategyKind;pub use longterm_memory::SessionConfig;pub use longterm_memory::SessionData;pub use longterm_memory::SessionId;pub use longterm_memory::SessionStore;pub use longterm_memory::SummaryHistory;pub use longterm_memory::Turn;pub use longterm_memory::TurnPairs;pub use longterm_memory::TurnPerf;pub use longterm_memory::TurnRole;pub use memory::MemoryStrategy;pub use memory::RewriteMemory;pub use memory::TranscriptMemory;pub use prompts::SystemPrompts;pub use agent::RagAgent;pub use agent::RagResponse;pub use store::HybridRrfRanker;pub use store::LlmReranker;pub use store::MmrDiversityRanker;pub use store::Ranker;pub use store::ScoredChunk;pub use store::VectorStore;pub use store::WeightedFusionRanker;pub use error::RagrigError;pub use documents::FileIndexResult;pub use vector::collect_documents;pub use vector::collect_documents_with_stats;pub use vector::embed_documents;pub use vector::index_folder;pub use vector::scan_document_files;pub use vector::search_by_document;
Modules§
- agent
- Composable RAG pipeline — the atomic building block for all orchestrators.
- agents
- Agent traits and concrete backends for the RAG pipeline stages.
- attach
- Document attachment strategies for the RAG pipeline.
- documents
- Document parsing, chunking, and file-hash-based incremental updates.
- embed
- Embedding backend abstraction.
- error
- Typed errors for the ragrig library.
- fs_
session_ store - Filesystem-backed
SessionStore— one JSON file per session. - longterm_
memory - Session persistence and cross-session history diffusion.
- memory
- Query rewriting for multi‑turn RAG.
- parsers
- Document parsing: convert PDF / EPUB / DOCX / HTML files into structured Markdown.
- prompts
- Configurable system prompts for the three agent roles.
- store
- Vector store abstraction for chunk persistence and hybrid search.
- types
- Domain types shared across the crate: document representations, CLI arguments, search results, and provider enums.
- vector
- Embedding generation and document ingestion.
Constants§
- DEFAULT_
MAX_ DOWNLOAD_ BYTES - Default maximum download size: 50 MiB.
Functions§
- download_
and_ ingest_ url - Downloads a PDF or EPUB from a URL, saves it to the document folder, and ingests it into the store.