GraphRAG-rs

A high-performance, modular Rust implementation of GraphRAG (Graph-based Retrieval Augmented Generation) with three deployment architectures: Server-Only, WASM-Only (100% client-side), and Hybrid. Build knowledge graphs from documents and query them with natural language, with GPU acceleration support via WebGPU.

30-Second Quick Start

CLI (no config file needed):

cargo install --path graphrag-cli           # one-time install
graphrag index ./mydoc.txt                  # builds ./graphrag-data
graphrag ask "What is the main topic?"      # answers from the graph

Add --ollama to either command for LLM-quality entity extraction (requires ollama serve running locally).

Library (Rust):

use graphrag::GraphRAG;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut g = GraphRAG::quick_start("Plato's Symposium full text here...").await?;
    println!("{}", g.ask("Who is Diotima?").await?);
    Ok(())
}

Both flows use sensible defaults — hash-fallback embeddings, pattern-based entity extraction, persistent workspace. Opt into Ollama / GLiNER / custom chunking with the builder when you need more.

Prerequisites

System Requirements

• Rust 1.85+ with wasm32-unknown-unknown target
• Node.js 18+ (for WASM builds)
• Git for cloning

Platform-Specific Dependencies

Linux (Ubuntu/Debian)

# Basic build tools
sudo apt update
sudo apt install -y build-essential pkg-config

# For GPU acceleration features (Metal/WebGPU dependencies)
sudo apt install -y gobjc gnustep-devel libgnustep-base-dev

# Optional: For Qdrant vector database
docker-compose   # For containerized vector storage

macOS

# Xcode Command Line Tools (includes Objective-C compiler)
xcode-select --install

# Optional: Homebrew for additional tools
brew install rustup

Windows

# Install Visual Studio Build Tools with C++ support
# Or use Visual Studio Community with C++ development tools

# Install Rust with Windows target support
rustup target add wasm32-unknown-unknown

Optional Dependencies

• Ollama for local LLM embeddings: ollama pull nomic-embed-text
• Docker for Qdrant vector database: docker-compose up -d
• Trunk for WASM builds: cargo install trunk wasm-bindgen-cli

Deployment Options

GraphRAG-rs supports three deployment architectures - choose based on your needs:

Option 1: Server-Only (Traditional) ✅ Production Ready

git clone https://github.com/your-username/graphrag-rs.git
cd graphrag-rs

# Start Qdrant (optional)
cd graphrag-server && docker-compose up -d

# Start Ollama for embeddings (required for real semantic search)
ollama serve &
ollama pull nomic-embed-text

# Start GraphRAG server with real embeddings
export EMBEDDING_BACKEND=ollama
cargo run --release --bin graphrag-server --features "qdrant,ollama"

Best for: Multi-tenant SaaS, mobile apps, GPU workloads, >1M documents

Features: - ✅ Qdrant vector database integration (production-ready) - ✅ Real embeddings via Ollama with GPU acceleration - ✅ Hash-based fallback embeddings (no dependencies) - ✅ REST API with semantic search - ✅ Docker Compose setup - ✅ 5.2MB release binary (optimized)

Option 2: WASM-Only (100% Client-Side) ✅ Production Ready

# Install trunk for WASM builds
cargo install trunk wasm-bindgen-cli

# Build and run WASM app with GPU acceleration
cd graphrag-wasm
trunk serve --open

Best for: Privacy-first apps, offline tools, zero infrastructure cost, edge deployment

Status: Fully Functional! - ✅ Complete GraphRAG pipeline running in browser - ✅ ONNX Runtime Web (GPU-accelerated embeddings) - ✅ WebLLM integration (Phi-3-mini for LLM synthesis) - ✅ Pure Rust vector search (cosine similarity) - ✅ Full Leptos UI with document upload and query interface - ✅ Entity extraction with relationships - ✅ Natural language answer synthesis - ✅ Demo available: Plato's Symposium (2691 entities)

Option 3: Hybrid (Recommended) Planned

Use WASM client for real-time UI with optional server for heavy processing.

Best for: Enterprise apps, multi-device sync, best UX with scalability

Status: Architecture designed, implementation in Phase 3

See graphrag-server/README.md for server documentation.

State-of-the-Art Quality Improvements

GraphRAG-rs implements 5 cutting-edge research papers (2019-2025) for superior retrieval quality:

Research-Based Features

Combined Result: +20% accuracy with 99% cost savings!

New: Advanced Reasoning & Optimization (2025-2026)

Building on state-of-the-art foundations, GraphRAG-rs now implements 7 cutting-edge techniques from recent research:

Key Capabilities

• Symbolic Anchoring: Automatically grounds abstract concepts (like "love" or "justice") to concrete entities for better conceptual query handling
• Dynamic Weighting: Adjusts relationship importance based on query context using semantic, temporal, and causal signals
• Causal Reasoning: Discovers multi-step causal chains with temporal consistency validation
• Hierarchical Clustering: Organizes relationships into multi-level hierarchies using Leiden algorithm with LLM-generated summaries
• Weight Optimization: Learns optimal relationship weights through heuristic optimization for improved retrieval quality

Full Documentation: See HOW_IT_WORKS.md for the pipeline deep-dive, and docs.rs/graphrag-core for the API reference.

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
high_level_weight = 0.6
low_level_weight = 0.4

[enhancements.leiden]
enabled = true
max_cluster_size = 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)
[advanced_features.symbolic_anchoring]
min_relevance = 0.3         # Minimum relevance for concept anchors
max_anchors = 5             # Maximum anchors per query

[advanced_features.dynamic_weighting]
enable_semantic_boost = true    # Boost relationships similar to query
enable_temporal_boost = true    # Boost recent/relevant relationships
enable_causal_boost = true      # Boost strong causal relationships

[advanced_features.causal_analysis]
min_confidence = 0.3            # Minimum confidence for causal chains
max_chain_depth = 5             # Maximum chain depth to search
require_temporal_consistency = true  # Enforce chronological ordering

[advanced_features.hierarchical_clustering]
num_levels = 3                  # Number of hierarchy levels (2-5)
generate_summaries = true       # LLM-generated cluster summaries

[advanced_features.weight_optimization]
learning_rate = 0.05            # Learning rate for optimization
max_iterations = 20             # Maximum optimization iterations
use_llm_eval = true             # Use LLM for quality evaluation

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

Documentation: See HOW_IT_WORKS.md for full details on the pipeline.

Installation

Prerequisites

• Rust 1.85 or later
• (Optional) Ollama for local LLM support - Install Ollama

From Source

git clone https://github.com/your-username/graphrag-rs.git
cd graphrag-rs
cargo build --release

# Optional: Install globally
cargo install --path .

Quick Start (5 Lines!)

The fastest way to get started with GraphRAG:

use graphrag_core::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let mut graphrag = GraphRAG::quick_start("Your document text").await?;
    let answer = graphrag.ask("What is this about?").await?;
    println!("{}", answer);
    Ok(())
}

With Compile-Time Safety (TypedBuilder)

use graphrag_core::prelude::*;

let graphrag = TypedBuilder::new()
    .with_output_dir("./output")  // Required - won't compile without
    .with_ollama()                 // Required - choose your LLM backend
    .with_chunk_size(512)          // Optional
    .build_and_init()?;

Get Explained Answers

let explained = graphrag.ask_explained("Who founded the company?").await?;
println!("Answer: {}", explained.answer);
println!("Confidence: {:.0}%", explained.confidence * 100.0);
for source in &explained.sources {
    println!("Source: {} (relevance: {:.0}%)", source.id, source.relevance_score * 100.0);
}

CLI Setup Wizard

# Interactive configuration wizard
graphrag-cli setup

# With domain template
graphrag-cli setup --template legal

Feature Bundles

Choose the right features for your use case:

[dependencies]
graphrag-core = { version = "0.1", features = ["starter"] }   # Getting started
graphrag-core = { version = "0.1", features = ["full"] }      # Production
graphrag-core = { version = "0.1", features = ["research"] }  # Advanced

Full Guide: See HOW_IT_WORKS.md and graphrag-core/README.md for detailed getting-started documentation.

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)
        .auto_detect_llm()
        .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          → chunk_size, chunk_overlap
├── Phase 2: ENTITY EXTRACTION → approach, entity_types, use_gleaning
├── Phase 3: RELATIONSHIP      → extract_relationships, use_gleaning
└── Phase 4: GRAPH CONSTRUCTION → enable_pagerank, max_connections

QUERY (ask())
├── Phase 5: EMBEDDING         → backend, dimension, model
├── Phase 6: RETRIEVAL         → strategy, top_k
└── Phase 7: ANSWER GENERATION → chat_model, temperature

Pipeline Configuration Summary

See HOW_IT_WORKS.md and **[config/JSON5_CONFIG_GUIDE.md](config/JSON5_CONFIG_GUIDE.md