Enable Advanced Features

[dependencies]
graphrag-core = { path = "../graphrag-core", features = ["lightrag", "leiden", "cross-encoder", "pagerank", "async"] }

# my_config.toml
[enhancements]
enabled = true
[enhancements.lightrag] enabled = true max_keywords = 20           # 6000x token reduction vs traditional GraphRAG highlevelweight = 0.6 lowlevelweight = 0.4
[enhancements.leiden] enabled = true maxclustersize = 10       # Better quality than Louvain resolution = 1.0
[enhancements.cross_encoder] enabled = true model_name = "cross-encoder/ms-marco-MiniLM-L-6-v2" top_k = 10                  # +20% accuracy improvement
Advanced Features (Phases 2-3)
[advancedfeatures.symbolicanchoring]
min_relevance = 0.3         # Minimum relevance for concept anchors
max_anchors = 5             # Maximum anchors per query
[advancedfeatures.dynamicweighting] enablesemanticboost = true    # Boost relationships similar to query enabletemporalboost = true    # Boost recent/relevant relationships enablecausalboost = true      # Boost strong causal relationships
[advancedfeatures.causalanalysis] min_confidence = 0.3            # Minimum confidence for causal chains maxchaindepth = 5             # Maximum chain depth to search requiretemporalconsistency = true  # Enforce chronological ordering
[advancedfeatures.hierarchicalclustering] num_levels = 3                  # Number of hierarchy levels (2-5) generate_summaries = true       # LLM-generated cluster summaries
[advancedfeatures.weightoptimization] learning_rate = 0.05            # Learning rate for optimization max_iterations = 20             # Maximum optimization iterations usellmeval = true             # Use LLM for quality evaluation

Quick Start Example: See graphrag-core/config-examples/quick-start.toml for a minimal configuration.

Basic Usage

1. Simple API (One Line)

use graphrag_rs::simple;
fn main() -> Result<(), Box<dyn std::error::Error>> {     let answer = simple::answer("Your document text", "Your question")?;     println!("Answer: {}", answer);     Ok(()) }

2. Stateful API (Multiple Queries)

use graphrag_rs::easy::SimpleGraphRAG;
fn main() -> Result<(), Box<dyn std::error::Error>> {     let mut graph = SimpleGraphRAG::from_text("Your document text")?;
let answer1 = graph.ask("What is this about?")?;     let answer2 = graph.ask("Who are the main characters?")?;
println!("Answer 1: {}", answer1);     println!("Answer 2: {}", answer2);     Ok(()) }

3. Builder API (Configurable)

use graphrag_rs::{GraphRAG, ConfigPreset};
fn main() -> Result<(), Box<dyn std::error::Error>> {     let mut graphrag = GraphRAG::builder()         .with_preset(ConfigPreset::Balanced)         .autodetectllm()         .build()?;
graphrag.add_document("Your document")?;     let answer = graphrag.ask("Your question")?;
println!("Answer: {}", answer);     Ok(()) }

Understanding GraphRAG

New to GraphRAG? Start here:

• How It Works - Complete 7-stage pipeline explanation with diagrams and examples
• Config Guide - Full JSON5/TOML configuration reference
• Examples - Hands-on code examples from basic to advanced
• Changelog - Feature history and recent updates
• API reference - graphrag-core on docs.rs

Complete 7-Stage Pipeline Schema

INDEXING (build_graph())
├── Phase 1: CHUNKING          → chunksize, chunkoverlap
├── Phase 2: ENTITY EXTRACTION → approach, entitytypes, usegleaning
├── Phase 3: RELATIONSHIP      → extractrelationships, usegleaning
└── Phase 4: GRAPH CONSTRUCTION → enablepagerank, maxconnections
QUERY (ask()) ├── Phase 5: EMBEDDING         → backend, dimension, model ├── Phase 6: RETRIEVAL         → strategy, top_k └── Phase 7: ANSWER GENERATION → chat_model, temperature

Pipeline Configuration Summary

| Phase | Goal | Key Parameters | |-------|------|----------------| | 1. Chunking | Split text | chunksize (300), chunkoverlap (30) | | 2. Extraction | Identify entities | approach (hybrid), entity_types | | 3. Relationships | Connect entities | extract_relationships (true) | | 4. Graph | Build network | maxconnections (50), enablepagerank | | 5. Embedding | Vectorize data | backend (openai), dimension (1536) | | 6. Retrieval | Find context | strategy (hybrid), top_k (10) | | 7. Generation | Answer query | chat_model (gpt-4o), temperature (0.0) |

4. CLI Usage

GraphRAG-rs provides two CLI tools:

Smart CLI (Recommended) - simple_cli

# Build the Smart CLI
cargo build --release --bin simple_cli
Process document and answer question in one command
cargo run --bin simple_cli config.toml "What are the main themes?"
Interactive mode - builds graph if needed, then waits for questions
cargo run --bin simple_cli config.toml
How it works:
1. Loads your TOML configuration
2. Checks if knowledge graph exists
3. Builds graph if needed (shows progress)
4. Answers your question using Ollama
5. Saves results to output directory

Manual CLI - graphrag-rs

# Build the manual CLI
cargo build --release
Step 1: Build knowledge graph
./target/release/graphrag-rs config.toml build
Step 2: Query the graph
./target/release/graphrag-rs config.toml query "Your question"

Configuration

Basic Configuration (config.toml)

The project includes several ready-to-use configuration templates:

Available Templates:

• config.toml - Basic configuration for general use
• config_complete.toml - Full configuration with all options
• configtomsawyer.toml - Pre-configured for book processing
• config_example.toml - Annotated template with explanations

[general]
IMPORTANT: Change these two paths for your project!
inputdocumentpath = "path/to/your/document.txt"  # Your document to process
outputdir = "./output/yourproject"                # Where to save results
[pipeline] chunk_size = 800        # Size of text chunks (adjust based on document type) chunk_overlap = 200     # Overlap to preserve context between chunks
[ollama] enabled = true host = "http://localhost" port = 11434 chat_model = "llama3.1:8b"           # LLM for text generation embedding_model = "nomic-embed-text"  # Model for embeddings

Quick Setup:

• Copy a template: cp configcomplete.toml myproject.toml
• Edit inputdocumentpath to point to your document
• Edit output_dir to set where results are saved
• Run: cargo run --bin simplecli myproject.toml

Embedding Providers Configuration

GraphRAG Core supports 8 embedding providers for maximum flexibility:

[embeddings]
backend = "huggingface"  # Free, offline (default)
backend = "openai"     # Best quality ($0.13/1M tokens)
backend = "voyage"     # Anthropic recommended
backend = "cohere"     # Multilingual (100+ languages)
backend = "jina"       # Cost-optimized ($0.02/1M)
backend = "mistral"    # RAG-optimized
backend = "together"   # Cheapest ($0.008/1M)
backend = "ollama"     # Local GPU
model = "sentence-transformers/all-MiniLM-L6-v2" dimension = 384 batch_size = 32 cache_dir = "~/.cache/huggingface"
For API providers, set api_key or use environment variables
apikey = "your-key"  # Or set OPENAIAPIKEY, VOYAGEAPI_KEY, etc.

Provider Comparison:

| Provider | Cost | Quality | Features | |----------|------|---------|----------| | HuggingFace | Free | ★★★★ | Offline, 100+ models | | OpenAI | $0.13/1M | ★★★★★ | Best quality | | Voyage AI | Medium | ★★★★★ | Domain-specific (code, finance, law) | | Cohere | $0.10/1M | ★★★★ | Multilingual | | Jina AI | $0.02/1M | ★★★★ | Best price/performance | | Mistral | $0.10/1M | ★★★★ | RAG-optimized | | Together AI | $0.008/1M | ★★★★ | Cheapest | | Ollama | Free | ★★★★ | Local GPU |

Environment Variables:

export OPENAIAPIKEY="sk-..." export VOYAGEAPIKEY="pa-..." export COHEREAPIKEY="..." export JINAAPIKEY="jina_..." export MISTRALAPIKEY="..." export TOGETHERAPIKEY="..."

Core Features

Modular Architecture

• Workspace Design: Separate crates for core, WASM, Leptos, and server
• Pluggable Backends: Qdrant, LanceDB, pgvector, or in-memory storage
• Feature Flags: Compile only what you need (WASM, CUDA, Metal, WebGPU)
• Trait-Based: 12+ core abstractions for maximum flexibility

Trait-Based Chunking Architecture

• ChunkingStrategy Trait: Minimal interface for extensible chunking (1 method: fn chunk(&self, text: &str) -> Vec<TextChunk>)
• HierarchicalChunkingStrategy: LangChain-style with boundary preservation (respects paragraphs/sentences)
• Tree-sitter AST Chunking: cAST approach preserving syntactic boundaries for code
• Performance Optimized: Zero-cost abstraction with real implementations
• Example: Symposium analysis with 269 chunks preserving philosophical structure

cAST (Context-Aware Splitting) Implementation

• Syntactic Boundary Preservation: Complete functions, methods, structs
• Rust Support: AST parsing for proper code chunking
• Configurable Granularity: Function-level with minimum size controls
• Feature-Gated: Available with --features code-chunking

Usage Example

use graphrag_core::{
    core::{DocumentId, Document, ChunkingStrategy},
    text::{TextProcessor, HierarchicalChunkingStrategy},
};
// Trait-based chunking with hierarchical strategy let processor = TextProcessor::new(1000, 100)?; let strategy = HierarchicalChunkingStrategy::new(1000, 100, document.id); let chunks = processor.chunkwithstrategy(&document, &strategy)?;
// Tree-sitter code chunking (with code-chunking feature) #[cfg(feature = "code-chunking")] {     let codestrategy = RustCodeChunkingStrategy::new(50, documentid);     let codechunks = codestrategy.chunk(rust_code); }

Run the Complete Example

# Basic example (hierarchical chunking)
cargo run --example symposiumtraitbased_chunking --package graphrag-core
With tree-sitter code chunking
cargo run --example symposiumtraitbased_chunking --package graphrag-core --features code-chunking

See: graphrag-core/examples/symposiumtraitbasedchunking.rs and READMEsymposiumtraitbasedchunking.md for complete documentation.

# Example 1: Process a book using existing template
cp configtomsawyer.toml mybookconfig.toml
Edit mybookconfig.toml:
  inputdocumentpath = "books/my_book.txt"
  outputdir = "./output/mybook"
cargo run --bin simplecli mybook_config.toml "Who are the main characters?"
Example 2: Process a research paper
cp config.toml research_config.toml
Edit research_config.toml:
  inputdocumentpath = "papers/research.txt"
  output_dir = "./output/research"
  chunk_size = 500  # Smaller chunks for technical content
cargo run --bin simplecli researchconfig.toml "What is the main hypothesis?"
Example 3: Process with full configuration
cp configcomplete.toml advancedconfig.toml
Edit all the parameters you need in advanced_config.toml
cargo run --bin simplecli advancedconfig.toml

use graphrag_rs::{GraphRAG, Document};
use std::fs;
fn main() -> Result<(), Box<dyn std::error::Error>> {     // Read document     let content = fs::readtostring("book.txt")?;
// Create and configure GraphRAG     let mut graphrag = GraphRAG::builder()         .withchunksize(1000)         .withchunkoverlap(200)         .build()?;
// Process document     let doc = Document::new("book", content);     graphrag.add_document(doc)?;
// Query     let answer = graphrag.ask("What are the main themes?")?;     println!("Answer: {}", answer);
Ok(()) }

use graphrag_rs::{GraphRAG, OllamaConfig};
fn main() -> Result<(), Box<dyn std::error::Error>> {     // Configure Ollama     let ollama = OllamaConfig::new()         .with_model("llama3.1:8b")         .withembeddingmodel("nomic-embed-text");
// Create GraphRAG with Ollama     let mut graphrag = GraphRAG::builder()         .with_llm(ollama)         .build()?;
// Use as normal     graphrag.add_text("Your document")?;     let answer = graphrag.ask("Your question")?;
Ok(()) }

use graphrag_rs::GraphRAG;
use std::fs;
fn main() -> Result<(), Box<dyn std::error::Error>> {     let mut graphrag = GraphRAG::new_default()?;
// Process multiple documents     for file in ["doc1.txt", "doc2.txt", "doc3.txt"] {         let content = fs::readtostring(file)?;         graphrag.add_text(&content)?;     }
// Query across all documents     let answer = graphrag.ask("What connects these documents?")?;     println!("Answer: {}", answer);
Ok(()) }

use graphrag_core::core::ServiceConfig;

let config = ServiceConfig {     ollamabaseurl: Some("http://localhost:11434".to_string()),     embeddingmodel: Some("nomic-embed-text:latest".tostring()),     languagemodel: Some("llama3.2:latest".tostring()),     vector_dimension: Some(768),     ..Default::default() };
let registry = config.build_registry().build(); // All services configured and ready!

See HOWITWORKS.md for the LLM/Ollama pipeline and config/JSON5CONFIGGUIDE.md for the ollama config block.

graphrag-rs/                     # 5-crate Cargo workspace (~140k lines)
├── graphrag-core/               # ✅ Portable core library (native + WASM)
│   ├── All core functionality   # LightRAG, PageRank, caching, incremental
│   └── Feature-gated deps       # Compile only what you need
├── graphrag-cli/                # ✅ TUI (ratatui) + CLI binary (in-process core)
│   └── index / ask / setup      # Zero-config turnkey commands
├── graphrag-wasm/               # ✅ WASM bindings, browser-native chat shell
│   ├── ONNX Runtime Web         # GPU embeddings (off-main-thread)
│   ├── WebLLM integration       # In-browser LLM synthesis
│   └── IndexedDB + Cache API    # Browser storage / persistence
├── graphrag-server/             # ✅ Production REST API (Actix + Apistos)
│   ├── JSON configuration       # Dynamic config via REST API
│   ├── Qdrant integration       # Vector database
│   ├── Ollama embeddings        # Real semantic search
│   └── Docker Compose           # One-command deployment
└── graphrag/                    # ✅ Meta-crate re-exporting graphrag-core
    └── hello-world API          # use graphrag::GraphRAG;

graphrag-cli    → graphrag-core
graphrag-wasm   → graphrag-core
graphrag-server → graphrag-core
graphrag (meta) → graphrag-core

[features]
Storage backends
memory-storage = []                           # In-memory (development)
persistent-storage = ["lancedb", "arrow"]     # LanceDB embedded vector DB Mutually exclusive with neural-embeddings
redis-storage = ["redis"]                     # Redis for distributed caching
Processing features
parallel-processing = []                      # Rayon parallelization
caching = ["moka"]                           # LLM response caching
incremental = []                             # Zero-downtime updates
pagerank = []                                # Fast-GraphRAG retrieval
lightrag = []                                # Dual-level retrieval
rograg = []                                  # Query decomposition
LLM integrations
ollama = []                                  # Ollama local models with streaming
dashmap = ["dep:dashmap"]                    # Response caching (used with ollama)
neural-embeddings = ["candle-core"]          # Candle ML framework Mutually exclusive with persistent-storage
function-calling = []                        # Function calling support
Platform-specific (GPU acceleration)
cuda = ["neural-embeddings", "candle-core/cuda"]    # NVIDIA GPU
metal = ["neural-embeddings", "candle-core/metal"]  # Apple Silicon GPU
webgpu = ["burn/wgpu"]                              # WebGPU (WASM)
Chunking strategies
code-chunking = ["tree-sitter", "tree-sitter-rust"]  # Tree-sitter AST-based chunking
API & CLI
web-api = []                                 # REST API server

For detailed architecture, see HOWIT_WORKS.md.

API Reference

Core Types

// Main GraphRAG interface
pub struct GraphRAG { / ... / }
// Document representation pub struct Document {     pub id: String,     pub content: String,     pub metadata: HashMap<String, String>, }
// Query results pub struct QueryResult {     pub answer: String,     pub confidence: f32,     pub sources: Vec<String>, }

Main Methods

impl GraphRAG {
    // Create new instance
    pub fn new(config: Config) -> Result<Self>;
// Add content     pub fn add_document(&mut self, doc: Document) -> Result<()>;     pub fn add_text(&mut self, text: &str) -> Result<()>;
// Query     pub fn ask(&self, question: &str) -> Result<String>;     pub fn query(&self, question: &str) -> Result<QueryResult>;
// Management     pub fn clear(&mut self);     pub fn save(&self, path: &str) -> Result<()>;     pub fn load(&mut self, path: &str) -> Result<()>; }

Performance Tuning

Memory Optimization

[performance]
chunk_size = 500  # Smaller chunks use less memory
maxentitiesper_chunk = 10
enable_caching = false

Speed Optimization

[performance]
enable_parallel = true
num_threads = 8  # Adjust based on CPU cores
batch_size = 50

Accuracy Optimization

[pipeline]
chunk_overlap = 400  # Higher overlap preserves more context
min_confidence = 0.7
enable_reranking = true

Troubleshooting

Common Issues

Build fails with "rust version" error

# Update Rust rustup update

Out of memory error

# Reduce chunk size in config.toml chunk_size = 300 enable_parallel = false

Slow processing

# Enable parallel processing enable_parallel = true num_threads = 8

Ollama connection error

# Ensure Ollama is running ollama serve

Check if model is available
ollama list

Debug Mode

# Enable debug logging
RUSTLOG=debug cargo run --bin simplecli config.toml
Enable backtrace for errors
RUST_BACKTRACE=1 cargo run

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/your-username/graphrag-rs.git
cd graphrag-rs
Run tests
cargo test
Run with debug info
RUST_LOG=debug cargo run
Check code quality
cargo clippy
cargo fmt --check

FAQ

Q: What file formats are supported? A: Currently supports plain text (.txt) and markdown (.md). PDF support is planned.

Q: Can I use this without Ollama? A: Yes, the library includes a mock LLM for testing and can work with embeddings only.

Q: How much memory does it need? A: Typically under 100MB for documents up to 500k characters.

Q: Is it production ready? A: Yes, with 214 passing tests, zero warnings, and production-grade structured logging throughout the core library.

Q: Can I use commercial LLMs? A: OpenAI support is planned. Currently works with Ollama's local models.

Roadmap & Implementation Status

✅ Phase 1: Core Implementation (COMPLETE)

Native Backend - Production Ready:

• [x] Modular Architecture: 50,000+ lines across 25+ modules
• [x] Trait System: 15+ core abstractions with dependency injection
• [x] Fast-GraphRAG: PageRank-based retrieval (27x performance boost)
• [x] LightRAG: Dual-level retrieval (6000x token reduction)
• [x] Incremental Updates: Zero-downtime graph processing
• [x] Intelligent Caching: 80%+ hit rates, 6x cost reduction
• [x] ROGRAG: Query decomposition (60%→75% accuracy) + temporal/causal reasoning
• [x] Hybrid Retrieval: Semantic + keyword + BM25 + graph
• [x] Parallel Processing: Multi-threaded document processing
• [x] Configuration System: Complete TOML-driven pipeline
• [x] Professional CLI: Progress bars, auto-detection
• [x] Comprehensive Tests: 214+ test cases, 100% pass rate
• [x] Production Logging: Structured tracing throughout core library

• [x] graphrag-server: REST API with Actix-web 4.9 + Apistos (automatic OpenAPI 3.0.3 docs)
• [x] Dynamic JSON Config: Full pipeline configuration via REST API (no TOML required)
• [x] Qdrant Integration: Production vector database
• [x] Ollama Embeddings: Real semantic search with GPU
• [x] Hash-based Fallback: Zero-dependency mode
• [x] Docker Compose: One-command deployment
• [x] Health Checks: Full system monitoring
• [x] 5.2MB Binary: Optimized release build

Phase 2: WASM & Web UI (IN PROGRESS - 60% Complete)

WASM Infrastructure:

• [x] graphrag-wasm crate: WASM bindings foundation
• [x] ONNX Runtime Web: GPU embeddings (3-8ms, 25-40x speedup)
• [x] WebLLM Integration: GPU LLM (40-62 tok/s)
• [x] IndexedDB: Browser storage layer
• [x] Cache API: Model storage layer
• [x] Voy Bindings: Vector search preparation
• [ ] Burn + wgpu: GPU acceleration (architecture 70% complete)
• [ ] Integration Tests: End-to-end WASM testing

• [x] Browser-native chat shell: 3-column Nordic-Minimal UI (Leptos)
• [x] Citations + subgraph view: per-query references and SVG graph
• [x] Off-main-thread inference: ONNX Runtime Web + WebLLM workers
• [ ] Graph Visualization: richer interactive knowledge-graph display
• [ ] Progress Indicators: Real-time status updates
• [ ] Responsive Design: Mobile-first layout

Phase 3: Advanced Features (PLANNED)

Performance & Scale:

• [ ] Distributed caching with Redis
• [ ] OpenTelemetry monitoring and tracing
• [ ] Query intelligence with ML rewriting
• [ ] Multi-model embeddings support
• [ ] Batch processing optimizations

• [ ] Graph analytics (community detection, centrality)
• [ ] Entity clustering and relationships
• [x] Temporal reasoning: Event timeline extraction and narrative ordering
• [x] Causal reasoning: Cause-effect chain discovery with confidence ranking
• [ ] Quality metrics and confidence scoring

• [ ] Bulk import from CSV, JSON, RDF
• [ ] PDF document processing
• [ ] Multi-format export (GraphML, Cypher)
• [ ] Integration connectors (Notion, Confluence)

Phase 4: Enterprise Features (FUTURE)

Scalability:

• [ ] High availability and failover
• [ ] Horizontal scaling with load balancing
• [ ] Multi-region deployment
• [ ] Enterprise-grade security

• [ ] Multi-language SDKs (Python, TypeScript, Go)
• [ ] GraphQL API
• [ ] Custom plugin system
• [ ] Webhook integrations

License

MIT License - see LICENSE for details.

Acknowledgments

• Microsoft GraphRAG for the original concept
• Ollama for local LLM support
• Rust community for excellent libraries

Built with Rust | Documentation | Report Issues