How GraphRAG Works: A Complete Guide

Understanding the 7-Stage Pipeline from Document to Answer

What is GraphRAG?

GraphRAG (Graph-based Retrieval-Augmented Generation) is an intelligent system that transforms unstructured text into a knowledge graph and uses it to answer questions with unprecedented accuracy and context awareness.

Think of it like this:

Imagine a brilliant librarian who:

1. Reads every book in the library
2. Creates an interconnected index of people, places, concepts, and their relationships
3. When you ask a question, uses this knowledge map to find relevant information
4. Combines multiple sources to give you a comprehensive, contextual answer

That’s exactly what GraphRAG does, but at machine scale with scientific precision.

Why GraphRAG vs Traditional RAG?

Configuration-Driven Dynamic Pipeline

GraphRAG-rs adapts its behavior based on your TOML configuration - the same codebase can run as:

• Fast, lightweight system (pattern-based, no LLM, <10ms processing)
• High-accuracy AI system (LLM-based, gleaning, contextual extraction)
• Hybrid approach (selective LLM use for critical stages)

All controlled by simple TOML settings - no code changes required.

How Configuration Changes the Pipeline

# Example 1: Fast, No-LLM Pipeline
[entity_extraction]
use_gleaning = false          # ← Pattern-based extraction

[ollama]
enabled = false               # ← No LLM required

# Result: <10ms entity extraction, good quality

# Example 2: High-Accuracy LLM Pipeline
[entity_extraction]
use_gleaning = true           # ← LLM-based extraction
max_gleaning_rounds = 4       # ← 4 refinement passes

[ollama]
enabled = true
chat_model = "llama3.1:8b"    # ← AI-powered extraction

# Result: 200-500ms entity extraction, excellent quality

Dynamic Stage Selection

The system automatically selects implementations based on config:

Logged during startup:

[INFO] Configuration loaded from: symposium_config.toml
[INFO] Using LLM-based entity extraction with gleaning (max_rounds: 4)
[INFO] Using Ollama embeddings: nomic-embed-text (768 dimensions)
[INFO] Using hybrid retrieval: vector (40%) + bm25 (30%) + pagerank (30%)
[INFO] Using Ollama generation: llama3.1:8b

Three Pipeline Approaches: Choose Your Strategy

GraphRAG-rs offers three distinct pipeline approaches, each optimized for different use cases and resource constraints. This approach-based architecture lets you explicitly choose your quality vs. speed trade-off.

The Three Approaches

┌─────────────────┬──────────────────┬─────────────────┐
│    SEMANTIC     │   ALGORITHMIC    │     HYBRID      │
│                 │                  │                 │
│  Neural/LLM     │  Pattern-based   │  Best of Both   │
│  High Quality   │  High Speed      │  Balanced       │
│  GPU Preferred  │  CPU Only        │  Moderate GPU   │
└─────────────────┴──────────────────┴─────────────────┘

1. Semantic Pipeline (Neural/LLM-based)

Philosophy: Use deep learning and LLMs for maximum understanding and quality.

Technology Stack:

• Embeddings: Neural models (HuggingFace, OpenAI, Ollama)
• Entity Extraction: LLM-based with gleaning (iterative refinement)
• Retrieval: Vector similarity search (cosine similarity, HNSW)
• Graph Construction: Semantic relationships with PageRank

Configuration:

[mode]
approach = "semantic"

[semantic.embeddings]
backend = "huggingface"
model_name = "sentence-transformers/all-MiniLM-L6-v2"

[semantic.entity_extraction]
use_gleaning = true
max_gleaning_rounds = 3
llm_model = "llama3.1:8b"

[semantic.retrieval]
strategy = "vector_similarity"
use_hnsw_index = true

Performance:

• Quality: ★★★★★ (90-95% accuracy)
• Speed: ★★☆☆☆ (100-500 docs/sec)
• Resource: ★★★★★ (High: 4-8GB, GPU recommended)

Best For: Research papers, legal documents, philosophical texts, narrative fiction, nuanced content analysis.

2. Algorithmic Pipeline (Pattern-based)

Philosophy: Use traditional NLP and pattern matching for speed and deterministic behavior.

Technology Stack:

• Embeddings: Hash-based with TF-IDF weighting
• Entity Extraction: Pattern matching (regex, capitalization rules)
• Retrieval: BM25 keyword-based retrieval
• Graph Construction: Co-occurrence based relationships

Configuration:

[mode]
approach = "algorithmic"

[algorithmic.embeddings]
backend = "hash"
hash_size = 1024
use_tfidf_weighting = true

[algorithmic.entity_extraction]
use_gleaning = false
use_patterns = true
extract_capitalized = true

[algorithmic.retrieval]
strategy = "bm25"
bm25_k1 = 1.5
bm25_b = 0.75

Performance:

• Quality: ★★★☆☆ (70-85% accuracy)
• Speed: ★★★★★ (1000-5000 docs/sec)
• Resource: ★☆☆☆☆ (Low: 1-2GB, CPU only)

Best For: Large-scale processing, resource-constrained environments, real-time applications, structured data, privacy-sensitive systems (no external APIs).

3. Hybrid Pipeline (Combined)

Philosophy: Combine semantic and algorithmic approaches for balanced quality and performance.

Technology Stack:

• Embeddings: Dual (neural + hash-based)
• Entity Extraction: LLM + pattern fusion
• Retrieval: RRF (Reciprocal Rank Fusion) combining vector + BM25
• Graph Construction: Cross-validated relationships

Configuration:

[mode]
approach = "hybrid"

[hybrid.weights]
semantic_weight = 0.6
algorithmic_weight = 0.4

[hybrid.embeddings]
primary_backend = "huggingface"
secondary_backend = "hash"
fusion_strategy = "weighted"

[hybrid.entity_extraction]
use_gleaning = true
use_patterns = true
max_gleaning_rounds = 2

[hybrid.retrieval]
fusion_strategy = "rrf"
rrf_k = 60

Performance:

• Quality: ★★★★☆ (85-95% accuracy)
• Speed: ★★★☆☆ (200-1000 docs/sec)
• Resource: ★★★☆☆ (Medium: 3-4GB, moderate GPU)

Best For: Production systems, diverse query workloads, mixed document types, applications requiring both quality and efficiency.

How Approach Selection Works

The [mode] section in your TOML config controls the entire pipeline:

# Option 1: Semantic (high quality)
[mode]
approach = "semantic"

# Option 2: Algorithmic (high speed)
[mode]
approach = "algorithmic"

# Option 3: Hybrid (balanced)
[mode]
approach = "hybrid"

This single setting automatically configures:

• Which embedding implementation to use
• Whether to use LLM-based or pattern-based entity extraction
• Which retrieval strategy to employ
• How to construct graph relationships

Dynamic Pipeline Selection at Runtime:

#![allow(unused)]
fn main() {
// In src/lib.rs:346 - build_graph() method
// The system checks config.approach and selects implementations:

match config.approach.as_str() {
    "semantic" => {
        // Use LLM-based gleaning extraction
        if config.entities.use_gleaning && config.ollama.enabled {
            extract_entities_with_gleaning()
        }
    }
    "algorithmic" => {
        // Use pattern-based extraction
        extract_entities_with_patterns()
    }
    "hybrid" => {
        // Use both and fuse results
        let llm_entities = extract_entities_with_gleaning();
        let pattern_entities = extract_entities_with_patterns();
        fuse_entity_results(llm_entities, pattern_entities)
    }
}
}

Approach Comparison Matrix

Quick Start by Approach

Semantic Pipeline:

cp config/templates/semantic_pipeline.toml my_config.toml
# Edit paths in my_config.toml
cargo run --example your_example -- my_config.toml

Algorithmic Pipeline:

cp config/templates/algorithmic_pipeline.toml my_config.toml
# Edit paths in my_config.toml
cargo run --example your_example -- my_config.toml
# No Ollama required!

Hybrid Pipeline:

cp config/templates/hybrid_pipeline.toml my_config.toml
# Edit paths in my_config.toml
cargo run --example your_example -- my_config.toml

For detailed configuration guide, see CONFIGURATION_GUIDE.md.

LazyGraphRAG & E2GraphRAG: Ultra-Efficient Approaches

New in 2025: Revolutionary approaches achieving 0.1% of traditional indexing cost while maintaining 90%+ quality.

Overview: Cost-Optimized GraphRAG

These cutting-edge implementations eliminate expensive LLM-based entity extraction during indexing:

┌──────────────────┬─────────────────┬────────────────┐
│  Traditional     │  LazyGraphRAG   │  E2GraphRAG    │
│  GraphRAG        │                 │                │
│                  │                 │                │
│  LLM-based       │  Concept-based  │  Pattern-based │
│  High Cost       │  0.1% Cost      │  0.05% Cost    │
│  95% Quality     │  92% Quality    │  88% Quality   │
└──────────────────┴─────────────────┴────────────────┘

LazyGraphRAG (Microsoft Research, 2025)

Philosophy: Zero LLM for indexing, concept graph from co-occurrence, iterative deepening for queries.

Key Features:

• No LLM Calls During Indexing: Uses noun phrase extraction
• 1000x Cheaper Indexing: $0.10 vs $100 per 1M tokens
• 100x Faster Indexing: 1000 docs/sec vs 10 docs/sec
• 700x Cheaper Queries: $0.0014 vs $1.00 per query
• 92% Quality: Acceptable trade-off for massive cost savings

Technology Stack:

• Concept Extraction: Regex-based noun phrases (no LLM)
• Graph Construction: Co-occurrence with Jaccard similarity
• Indexing: Bidirectional entity-chunk index (O(1) lookups)
• Query Processing: Iterative deepening search
• Refinement: Query expansion via concept graph traversal

Configuration:

[experimental]
lazy_graphrag = true

[experimental.lazy_graphrag_config]
use_concept_extraction = true
min_concept_length = 3
max_concept_words = 5
co_occurrence_threshold = 1
use_query_refinement = true
max_refinement_iterations = 3
use_bidirectional_index = true

Performance:

• Quality: ★★★★☆ (92% accuracy) | Speed: ★★★★★ (1000 docs/sec)
• Cost: ★★★★★ (0.1% of traditional) | Resource: ★☆☆☆☆ (200MB RAM)

Example:

#![allow(unused)]
fn main() {
use graphrag_core::lightrag::LazyGraphRAGPipeline;

let mut pipeline = LazyGraphRAGPipeline::default();
pipeline.index_document("doc1", "Machine Learning transforms AI...");
pipeline.build_graph(); // Fast, no LLM!

let results = pipeline.query("machine learning applications");
println!("Found {} chunks", results.chunk_count());
}

E2GraphRAG (2025)

Philosophy: Pattern-based entity extraction, no LLM required, deterministic output.

Key Features:

• 100x Faster Entity Extraction: 5ms vs 500ms per chunk
• 2000x Cheaper: $0.05 per 1M tokens
• ✅ Deterministic: Fully reproducible results

Configuration:

[experimental]
e2_graphrag = true

[experimental.e2_graphrag_config]
use_lightweight_ner = true
entity_types = ["PERSON", "ORGANIZATION", "LOCATION", "CONCEPT"]
use_capitalization_detection = true
use_noun_phrase_extraction = true

Cost Comparison

ROI Example (1M docs, 10k queries/month):

• Traditional: $220k/year
• LazyGraphRAG: $268/year (820x cheaper!)
• E2GraphRAG: $170/year (1300x cheaper!)

For complete documentation, see docs/LAZYGRAPHRAG_E2GRAPHRAG.md.

The 7-Stage Pipeline

GraphRAG-rs processes documents through 7 interconnected stages, transforming raw text into intelligent, queryable knowledge. Let’s explore each stage with a real example using The Adventures of Tom Sawyer.

flowchart TB
    Input[Raw Document<br/>434,401 characters] --> Stage1

    subgraph Pipeline ["GraphRAG 7-Stage Pipeline"]
        Stage1[Stage 1: Text Chunking<br/>Break into 492 chunks]
        Stage2[Stage 2: Embeddings<br/>Generate 384-dim vectors]
        Stage3[Stage 3: Entity Extraction<br/>Find 429 entities]
        Stage4[Stage 4: Graph Construction<br/>Build knowledge graph]
        Stage5[Stage 5: Dual-Level Retrieval<br/>Smart search]
        Stage6[Stage 6: Query Processing<br/>Understand question]
        Stage7[Stage 7: Answer Generation<br/>Compose response]

        Stage1 --> Stage2
        Stage2 --> Stage3
        Stage3 --> Stage4
        Stage4 --> Stage5

        Query[User Query] --> Stage6
        Stage6 --> Stage5
        Stage5 --> Stage7
    end

    Stage7 --> Output[✅ Final Answer<br/>with sources]

    style Stage1 fill:#e1f5ff
    style Stage2 fill:#fff4e6
    style Stage3 fill:#f3e5f5
    style Stage4 fill:#e8f5e9
    style Stage5 fill:#fff9c4
    style Stage6 fill:#fce4ec
    style Stage7 fill:#e0f2f1

Stage 1: Text Chunking

What it does: Divides long documents into overlapping, semantically meaningful segments.

Why: LLMs have token limits (typically 4K-32K tokens). Chunking allows processing of arbitrarily large documents while preserving local context through overlap.

Process Details

Input:

"Tom!" No answer. "TOM!" No answer. "What's gone with that boy, I wonder?
You TOM!" No answer. The old lady pulled her spectacles down and looked
over them about the room; then she put them up and looked out under them...

Configuration (from config/templates/narrative_fiction.toml):

chunk_size = 800        # ~200 words
chunk_overlap = 200     # 50 words overlap

Output: 492 overlapping chunks

Chunk 1: "Tom! No answer. TOM! No answer. What's gone..."  [800 chars]
Chunk 2: "...What's gone with that boy, I wonder? You TOM!..." [800 chars, 200 overlap]
Chunk 3: "...You TOM! No answer. The old lady pulled her..." [800 chars, 200 overlap]
...
Chunk 492: "...the end of Tom Sawyer's adventures." [final chunk]

Why Overlap Matters

Without Overlap (❌ Context Loss):

Chunk A: "...Tom found the treasure under the"
Chunk B: "cross marked on the old tree..."
❌ Entity "treasure under the cross" split across chunks

With 200-char Overlap (✅ Preserved):

Chunk A: "...Tom found the treasure under the cross marked on..."
Chunk B: "...treasure under the cross marked on the old tree..."
✅ Complete entity captured in both chunks

Module: src/text/chunking.rs Performance: ~0.01s for 434KB document

Stage 2: Embeddings Generation

What it does: Converts text chunks into high-dimensional numerical vectors that capture semantic meaning.

Why: Computers can’t understand text directly. Embeddings transform words into numbers while preserving meaning relationships (e.g., “king - man + woman ≈ queen”).

The Vector Space

Each chunk becomes a 384-dimensional vector where similar meanings cluster together:

"Tom and Huck found treasure" → [0.23, -0.45, 0.67, ..., 0.12] (384 numbers)
"The boys discovered gold"    → [0.21, -0.42, 0.69, ..., 0.14] (close!)
"The weather was sunny"       → [-0.67, 0.23, -0.12, ..., 0.45] (far away)

Embedding Backends

GraphRAG-rs supports multiple embedding strategies:

Real Example Output

#![allow(unused)]
fn main() {
// From examples/real_ollama_pipeline.rs
let embedding = embedder.generate_embedding_async(
    "Tom found the treasure in the cave"
).await?;

// Result: Vec<f32> with 384 dimensions
// [0.234, -0.456, 0.678, 0.123, ..., -0.234]
// L2 norm: ~1.0 (normalized)
}

Module: src/embeddings/neural/mod.rs Performance:

• Ollama: ~100ms per chunk (5-10 chunks/sec)
• ONNX GPU: ~3-8ms per chunk (125-333 chunks/sec, 25-40x faster)

Stage 3: Entity Extraction

What it does: Identifies and extracts named entities (people, places, concepts, events) and their relationships from each chunk.

Why: Entities are the nodes of our knowledge graph. Without them, we’d just have disconnected chunks of text.

Dynamic Pipeline Configuration

GraphRAG-rs now adapts Stage 3 based on your TOML configuration. The system automatically chooses the optimal extraction method:

# Configuration controls the pipeline behavior
[entity_extraction]
use_gleaning = true           # ← If TRUE: LLM-based extraction
                              #    If FALSE: Pattern-based extraction
max_gleaning_rounds = 4       # ← Number of refinement passes

[ollama]
enabled = true                # ← Must be TRUE for LLM extraction
chat_model = "llama3.1:8b"    # ← LLM model for extraction

The pipeline dynamically selects:

Logged Output:

[INFO] Using LLM-based entity extraction with gleaning (max_rounds: 4)
  ✓ Ollama client initialized
  ✓ Model: llama3.1:8b
  ✓ Entity types: PERSON, CONCEPT, ARGUMENT, LOCATION, ...

or

[INFO] Using pattern-based entity extraction
  ✓ Fast regex-based extraction
  ✓ No LLM required

Entity Types

GraphRAG recognizes these entity categories (fully customizable via config):

PERSON    → "Tom Sawyer", "Huckleberry Finn", "Aunt Polly"
LOCATION  → "Mississippi River", "St. Petersburg", "McDougal's Cave"
CONCEPT   → "treasure hunting", "freedom", "childhood innocence"
EVENT     → "witnessing the murder", "finding the treasure", "trial scene"

Customize via TOML:

[pipeline.entity_extraction]
entity_types = [
    "PERSON",                 # Your custom types!
    "CONCEPT",
    "ARGUMENT",
    "MYTHOLOGICAL_REFERENCE"  # ← Philosophical texts
]

Extraction Methods (Config-Driven)

A. Pattern-Based (Fast, Deterministic)

#![allow(unused)]
fn main() {
// Enabled when: use_gleaning = false
// src/entity/mod.rs - Regex + capitalization
Keywords: ["Tom Sawyer", "Huck", "treasure", "cave"]
Performance: <10ms per chunk
Found: 189 entities in Symposium, 429 in Tom Sawyer
}

B. LLM-Based Gleaning (Accurate, Contextual)

#![allow(unused)]
fn main() {
// Enabled when: use_gleaning = true && ollama.enabled = true
// src/entity/gleaning_extractor.rs - Uses Ollama llama3.1:8b
Prompt: "Extract entities of types: PERSON, CONCEPT, ARGUMENT...
         from this text. Return JSON..."

Input: "Tom and Huck found the treasure under the cross..."

LLM Output (Round 1):
[
  {"name": "Tom Sawyer", "type": "PERSON", "confidence": 0.95},
  {"name": "Huckleberry Finn", "type": "PERSON", "confidence": 0.93},
  {"name": "treasure", "type": "CONCEPT", "confidence": 0.88},
  {"name": "cross marker", "type": "LOCATION", "confidence": 0.85}
]

Performance: 200-500ms per chunk
}

Gleaning (Multi-Pass LLM Refinement)

Gleaning is an iterative process controlled by max_gleaning_rounds:

Configuration: max_gleaning_rounds = 4

Round 1: Extract obvious entities     → Found 100 entities
Round 2: "Did you miss any entities?" → Found 15 more entities
Round 3: "Any relationships?"          → Found 8 relationships
Round 4: "Final check for concepts"   → Found 2 subtle concepts
Total: 125 entities, 8 relationships

[INFO] ✅ Extraction complete after 4 rounds
[INFO] Final gleaning results: 125 entities, 8 relationships

Module: src/entity/gleaning_extractor.rs Performance:

• Pattern-based: <10ms per chunk
• LLM-based gleaning: 200-500ms per chunk × max_gleaning_rounds
  • 1 round: ~300ms
  • 4 rounds: ~1200ms

Configuration Examples

Example 1: Fast Pattern-Based (No LLM)

[entity_extraction]
enabled = true
min_confidence = 0.7
use_gleaning = false          # ← Pattern-based extraction

[ollama]
enabled = false               # ← No LLM needed

Result: <10ms per chunk, good quality, no API/GPU required

Example 2: High-Quality LLM-Based

[entity_extraction]
enabled = true
min_confidence = 0.6          # ← Lower for philosophical nuance
use_gleaning = true           # ← LLM-based extraction
max_gleaning_rounds = 4       # ← 4 refinement passes

[ollama]
enabled = true
chat_model = "llama3.1:8b"    # ← LLM for extraction

Result: 200-500ms per chunk, excellent quality, custom entity types

Real Output Example

{
  "entity_id": "ent_tom_sawyer_001",
  "name": "Tom Sawyer",
  "type": "PERSON",
  "chunk_ids": ["chunk_001", "chunk_015", "chunk_234"],
  "confidence": 0.95,
  "description": "Main protagonist, adventurous boy",
  "extraction_method": "gleaning_llm",  // ← Indicates LLM extraction
  "gleaning_round": 1                   // ← Found in first pass
}

Stage 4: Knowledge Graph Construction

What it does: Connects extracted entities into a unified, queryable graph structure with typed relationships.

Why: A graph reveals how entities relate, not just that they co-occur. This enables multi-hop reasoning and contextual understanding.

Graph Structure

graph LR
    TomSawyer[Tom Sawyer<br/>PERSON]
    Huck[Huckleberry Finn<br/>PERSON]
    Treasure[Treasure<br/>CONCEPT]
    Cave[McDougal's Cave<br/>LOCATION]
    InjunJoe[Injun Joe<br/>PERSON]

    TomSawyer -->|FRIEND_OF| Huck
    TomSawyer -->|FOUND| Treasure
    Treasure -->|LOCATED_IN| Cave
    InjunJoe -->|GUARDS| Treasure
    TomSawyer -->|WITNESSED_MURDER_BY| InjunJoe
    Huck -->|HELPED_FIND| Treasure

    style TomSawyer fill:#e3f2fd
    style Huck fill:#e3f2fd
    style Treasure fill:#fff9c4
    style Cave fill:#e8f5e9
    style InjunJoe fill:#fce4ec

Graph Components

Nodes (Entities):

#![allow(unused)]
fn main() {
pub struct Entity {
    pub id: EntityId,
    pub name: String,
    pub entity_type: String,
    pub description: String,
    pub chunk_references: Vec<ChunkId>,
}
}

Edges (Relationships):

#![allow(unused)]
fn main() {
pub struct Relationship {
    pub source: EntityId,
    pub target: EntityId,
    pub relation_type: String,  // "FRIEND_OF", "FOUND", etc.
    pub confidence: f32,
}
}

Advanced Features

A. Incremental Updates (Zero-Downtime)

#![allow(unused)]
fn main() {
// src/graph/incremental.rs
graph.add_document("Tom Sawyer");   // 429 entities added
graph.add_document("Symposium");    // 189 entities added
// Automatically merges 58 duplicate entities!
}

B. PageRank Scoring (Fast-GraphRAG)

#![allow(unused)]
fn main() {
// src/graph/pagerank.rs
let scores = pagerank.compute_personalized(
    seed_entities: ["Tom Sawyer", "Huck Finn"],
    max_iterations: 20
);
// Ranks entities by importance: 27x faster retrieval!
}

C. Community Detection (Hierarchical Clustering)

Community 1: Tom Sawyer storyline (347 entities)
  ├─ Subgraph: Treasure hunting (45 entities)
  ├─ Subgraph: School adventures (89 entities)
  └─ Subgraph: Courtroom drama (23 entities)

Community 2: Philosophical concepts (189 entities)
  └─ From Symposium document

Module: src/graph/mod.rs, src/graph/incremental.rs Performance:

• Graph construction: ~50ms for 500 entities
• PageRank: ~20ms (cached, 27x speedup vs traditional)

Stage 5: Dual-Level Retrieval (LightRAG)

What it does: Searches the knowledge graph at two levels simultaneously - specific entities (low-level) and broad concepts (high-level).

Why: Traditional RAG searches only chunks. LightRAG searches entities AND their community context, achieving 6000x token reduction.

The Dual-Level Approach

Query: "What did Tom and Huck find in the cave?"

LOW-LEVEL RETRIEVAL (Specific):
  → Search entities: "Tom Sawyer", "Huck Finn", "cave"
  → Results: 12 entity matches

HIGH-LEVEL RETRIEVAL (Contextual):
  → Search communities: "treasure hunting" storyline
  → Results: 45 related entities in same narrative arc

FUSION:
  → Combine both levels with Reciprocal Rank Fusion (RRF)
  → Final results: Top 10 most relevant entities

Retrieval Strategies

GraphRAG-rs implements 4 complementary strategies:

Reciprocal Rank Fusion (RRF)

Formula:

RRF_score(entity) = Σ (1 / (k + rank_in_strategy))
                    for each strategy

Example:

Entity: "Tom Sawyer"
  Vector search rank: 2  → score = 1/(60+2) = 0.0161
  BM25 rank: 1          → score = 1/(60+1) = 0.0164
  PageRank rank: 3      → score = 1/(60+3) = 0.0159

  Total RRF = 0.0484 (ranked #1 overall!)

Module: src/lightrag/dual_retrieval.rs Performance:

• Low-level retrieval: ~20ms
• High-level retrieval: ~30ms
• Fusion: ~10ms
• Total: ~60ms (vs 2-5 seconds traditional GraphRAG)

Stage 6: Query Processing

What it does: Analyzes the user’s question to determine intent, entities, and optimal search strategy.

Why: “What is love?” requires different processing than “When did Tom find the treasure?” - query understanding guides retrieval.

Query Analysis Components

A. Intent Classification

#![allow(unused)]
fn main() {
// src/query/advanced_pipeline.rs
pub enum QueryIntent {
    Factual,     // "What is X?"
    Relational,  // "How is X related to Y?"
    Temporal,    // "When did X happen?"
    Causal,      // "Why did X happen?"
    Comparative, // "Compare X and Y"
    Exploratory, // "Tell me about X"
}
}

B. Entity Extraction from Query

Query: "How did Tom and Huck find the treasure in McDougal's Cave?"

Extracted Entities:
  - "Tom" (PERSON)
  - "Huck" (PERSON)
  - "treasure" (CONCEPT)
  - "McDougal's Cave" (LOCATION)

Intent: Relational + Temporal
Strategy: Graph traversal + vector search hybrid

C. Query Decomposition (ROGRAG)

For complex queries, break into sub-queries:

Complex: "Compare Tom's and Huck's roles in finding the treasure"

Decomposed:
  1. "What role did Tom play in finding the treasure?"
  2. "What role did Huck play in finding the treasure?"
  3. [Synthesis] "Compare the two roles"

Accuracy boost: 60% → 75% (15% improvement!)

Advanced Query Pipeline

#![allow(unused)]
fn main() {
// src/query/advanced_pipeline.rs:165-200
pub async fn execute_query() -> Result<QueryResult> {
    // Step 1: Analyze query
    let analysis = self.analyze_query(query).await?;

    // Step 2: Vector similarity search
    let vector_scores = self.vector_search(query, graph).await?;

    // Step 3: PageRank propagation
    let pagerank_scores = self.pagerank_propagation(&analysis).await?;

    // Step 4: Relationship scoring
    let rel_scores = self.score_relationships(graph).await?;

    // Step 5: Multi-modal fusion
    let combined = self.fuse_scores(vector_scores, pagerank_scores, rel_scores);

    // Step 6: Rank and filter
    let results = self.apply_ranking_policies(combined);

    return results;
}
}

Module: src/query/advanced_pipeline.rs, src/rograg/ Performance:

• Query analysis: ~50ms
• Decomposition (if needed): ~100ms

Stage 7: Answer Generation

What it does: Synthesizes retrieved entities, relationships, and chunks into a coherent, natural language answer.

Why: Raw search results are just data. Generation transforms them into human-readable, contextual answers with citations.

Generation Pipeline

Retrieved Context:
  Entity 1: Tom Sawyer (confidence: 0.95)
    - Relevant chunk: "Tom and Huck ventured into the cave..."
  Entity 2: Treasure (confidence: 0.92)
    - Relevant chunk: "They found twelve thousand dollars in gold..."
  Relationship: Tom FOUND Treasure (confidence: 0.88)

↓ LLM Prompt Construction ↓

System Prompt:
  "You are a knowledgeable assistant. Answer based ONLY on provided context."

Context Assembly:
  [Include top 5 chunks with source attribution]
  [Include entity descriptions]
  [Include relationship graph snippet]

User Question:
  "How did Tom and Huck find the treasure?"

↓ LLM Generation (Ollama llama3.1:8b) ↓

Generated Answer:
  "Tom Sawyer and Huckleberry Finn discovered the treasure in McDougal's Cave
   after witnessing Injun Joe hide it there. They found approximately $12,000
   in gold coins under a cross marked on a rock. This discovery came after Tom
   got lost in the cave with Becky Thatcher and noticed the hiding spot while
   trying to find an exit.

   Sources: Chapter 33 (cave discovery), Chapter 35 (counting the treasure)"

LLM Backend Options

Caching (6x Cost Reduction)

#![allow(unused)]
fn main() {
// src/caching/cached_client.rs
let cache_key = generate_semantic_key(prompt);

if let Some(cached) = cache.get(&cache_key) {
    return cached;  // 80%+ hit rate in production!
}

let response = llm.generate(prompt).await?;
cache.put(cache_key, response.clone());
return response;
}

Cache Performance:

• Hit rate: 80%+ (typical workload)
• Cost reduction: 6x
• Latency reduction: 50-100ms → 5ms (16-20x faster)

Module: src/generation/mod.rs, src/caching/ Performance:

• Generation: 1-3 seconds (depending on answer length)
• Cached: ~5ms

Complete Pipeline Performance

Real Benchmark: Tom Sawyer (434KB)

Source: examples/multi_document_pipeline.rs - production benchmarks

Scalability

With PageRank + LightRAG optimizations:

• 27x faster retrieval
• 6000x fewer tokens processed
• 6x cost reduction (caching)

Alternative Techniques for Each Stage

GraphRAG-rs is highly modular with pluggable implementations for each pipeline stage. Choose the best technique based on your requirements using the core::traits abstraction layer.

Architecture: Trait-Based Plugin System

#![allow(unused)]
fn main() {
// src/core/traits.rs - Core abstraction layer
pub trait Embedder { ... }            // Stage 2: Embeddings
pub trait EntityExtractor { ... }     // Stage 3: Entity Extraction
pub trait VectorStore { ... }         // Stage 5: Vector Search
pub trait Retriever { ... }           // Stage 5: Retrieval
pub trait LanguageModel { ... }       // Stage 7: Generation
pub trait GraphStore { ... }          // Stage 4: Graph Storage
}

Stage 1: Text Chunking - 3 Strategies

Hierarchical Separator Precedence:

#![allow(unused)]
fn main() {
[
    "\n\n",   // Paragraph breaks (priority 1)
    "\n",     // Line breaks
    ". ",     // Sentence endings
    "! ",     // Exclamations
    "? ",     // Questions
    "; ",     // Semicolons
    " ",      // Word boundaries
    "",       // Character fallback
]
}

Configuration:

[pipeline]
chunk_size = 800        # Characters per chunk
chunk_overlap = 200     # Overlap for context preservation
min_chunk_size = 50     # Skip tiny chunks

Stage 2: Embeddings - 11 Providers

GraphRAG Core now supports 11 embedding backends via unified configuration:

Free/Local Providers

API Providers (Production)

Planned

Models Available:

HuggingFace Hub (100+ models):

sentence-transformers/all-MiniLM-L6-v2    → 384 dim (default, recommended)
sentence-transformers/all-mpnet-base-v2   → 768 dim (balanced)
BAAI/bge-large-en-v1.5                    → 1024 dim (best quality)
intfloat/e5-small-v2                      → 384 dim (E5 family)
paraphrase-multilingual-MiniLM-L12-v2     → 384 dim (50+ languages)

API Providers:

OpenAI:     text-embedding-3-small (1536), text-embedding-3-large (3072)
Voyage:     voyage-3-large (1024), voyage-code-3 (1024), voyage-finance-2, voyage-law-2
Cohere:     embed-english-v3.0 (1024), embed-multilingual-v3.0 (1024)
Jina:       jina-embeddings-v3 (1024), jina-embeddings-v4 (multimodal)
Mistral:    mistral-embed (1024), codestral-embed (code)
Together:   BAAI/bge-large-en-v1.5 (1024), BAAI/bge-base-en-v1.5 (768)
Ollama:     nomic-embed-text (768)

Trait Implementation:

#![allow(unused)]
fn main() {
#[async_trait::async_trait]
pub trait EmbeddingProvider: Send + Sync {
    /// Initialize the embedding provider (e.g., download models)
    async fn initialize(&mut self) -> Result<()>;

    /// Generate embedding for single text
    async fn embed(&self, text: &str) -> Result<Vec<f32>>;

    /// Generate embeddings for multiple texts (batch processing)
    async fn embed_batch(&self, texts: &[&str]) -> Result<Vec<Vec<f32>>>;

    /// Get the embedding dimension
    fn dimensions(&self) -> usize;

    /// Check if the provider is available and ready
    fn is_available(&self) -> bool;

    /// Get the provider name
    fn provider_name(&self) -> &str;
}
}

Configuration:

[embeddings]
backend = "huggingface"           # Free, offline (default)
# backend = "openai"              # Best quality ($0.13/1M)
# backend = "voyage"              # Anthropic recommended
# backend = "cohere"              # Multilingual
# 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 HuggingFace
# api_key = "..."  # For API providers (or set env vars)

# Environment variables (recommended for API keys):
# OPENAI_API_KEY, VOYAGE_API_KEY, COHERE_API_KEY, JINA_API_KEY, MISTRAL_API_KEY, TOGETHER_API_KEY

See: config/JSON5_CONFIG_GUIDE.md for the complete configuration reference.

Stage 3: Entity Extraction - Config-Driven Selection

The system automatically chooses the extraction method based on your configuration:

Entity Types (Fully Customizable):

# Configure your own entity types!
[pipeline.entity_extraction]
entity_types = [
    "PERSON",                 # "Tom Sawyer", "Socrates"
    "LOCATION",               # "Mississippi River", "Athens"
    "CONCEPT",                # "treasure hunting", "Eros"
    "EVENT",                  # "murder witness", "symposium"
    "ARGUMENT",               # Philosophical arguments
    "MYTHOLOGICAL_REFERENCE"  # Gods, myths
]

Gleaning Process (LLM-Based, Config-Controlled):

[entity_extraction]
use_gleaning = true           # ← Enable LLM extraction
max_gleaning_rounds = 4       # ← Number of refinement passes

[ollama]
enabled = true
chat_model = "llama3.1:8b"    # ← LLM for extraction

Runtime Behavior:

Round 1: Extract obvious entities      → 100 entities
Round 2: "Did you miss any entities?"  → +15 entities
Round 3: "Find relationships"          → 8 relationships
Round 4: "Final check for concepts"    → 2 subtle concepts
Total: 125 entities, 8 relationships

[INFO] ✅ Extraction complete after 4 rounds

Trait Implementation:

#![allow(unused)]
fn main() {
pub trait EntityExtractor {
    fn extract(&self, text: &str) -> Result<Vec<Entity>>;
    fn extract_with_confidence(&self, text: &str) -> Result<Vec<(Entity, f32)>>;
    fn set_confidence_threshold(&mut self, threshold: f32);
}

#[async_trait]
pub trait AsyncEntityExtractor {
    async fn extract(&self, text: &str) -> Result<Vec<Entity>>;
    async fn extract_batch(&self, texts: &[&str]) -> Result<Vec<Vec<Entity>>>;
    async fn extract_batch_concurrent(&self, texts: &[&str], max_concurrent: usize);
}
}

Configuration (Controls Behavior):

[entity_extraction]
enabled = true
min_confidence = 0.6          # ← Minimum confidence threshold
use_gleaning = true           # ← Pattern-based (false) vs LLM-based (true)
max_gleaning_rounds = 4       # ← Number of LLM refinement passes
semantic_merging = true       # ← Deduplicate similar entities
automatic_linking = true      # ← Auto-link related entities

[pipeline.entity_extraction]
entity_types = ["PERSON", "CONCEPT", ...]  # ← Custom types
confidence_threshold = 0.7

[ollama]
enabled = true                # ← Required for LLM-based extraction
chat_model = "llama3.1:8b"    # ← LLM model

The pipeline reads this config at startup and selects the appropriate implementation automatically.

Stage 4: Graph Construction - 3 Storage Backends

Graph Features:

Trait Implementation:

#![allow(unused)]
fn main() {
pub trait GraphStore {
    fn add_node(&mut self, node: Node) -> Result<String>;
    fn add_edge(&mut self, from: &str, to: &str, edge: Edge) -> Result<String>;
    fn find_nodes(&self, criteria: &str) -> Result<Vec<Node>>;
    fn get_neighbors(&self, node_id: &str) -> Result<Vec<Node>>;
    fn traverse(&self, start_id: &str, max_depth: usize) -> Result<Vec<Node>>;
}
}

Configuration:

[graph]
backend = "in-memory"                  # or "qdrant", "neo4j"
enable_incremental = true
enable_pagerank = true
enable_community_detection = true
deduplication_threshold = 0.85

Stage 5: Retrieval - 5 Strategies

LightRAG Dual-Level (6000x token reduction):

Query: "What did Tom find in the cave?"

LOW-LEVEL:  Search specific entities (Tom, cave, treasure)
            → 12 entity matches

HIGH-LEVEL: Search community context (treasure hunting storyline)
            → 45 related entities in narrative arc

FUSION:     RRF combines both levels
            → Top 10 most relevant results

Reciprocal Rank Fusion Formula:

#![allow(unused)]
fn main() {
RRF_score(entity) = Σ (1 / (k + rank_i))
where k = 60 (constant), rank_i = rank in strategy i
}

Trait Implementation:

#![allow(unused)]
fn main() {
pub trait Retriever {
    fn search(&self, query: Query, k: usize) -> Result<Vec<SearchResult>>;
    fn search_with_context(&self, query: Query, context: &str, k: usize);
}

#[async_trait]
pub trait AsyncRetriever {
    async fn search(&self, query: Query, k: usize) -> Result<Vec<SearchResult>>;
    async fn search_batch(&self, queries: Vec<Query>, k: usize);
}
}

Configuration:

[retrieval]
strategy = "hybrid"                    # or "vector", "bm25", "pagerank", "adaptive"
k = 10                                 # Top-k results
enable_lightrag = true                 # Dual-level retrieval
fusion_weights = { vector = 0.4, bm25 = 0.3, pagerank = 0.3 }

Stage 6: Query Processing - 3 Analyzers

Query Intent Types:

#![allow(unused)]
fn main() {
pub enum QueryIntent {
    Factual,     // "What is X?"
    Relational,  // "How is X related to Y?"
    Temporal,    // "When did X happen?"
    Causal,      // "Why did X happen?"
    Comparative, // "Compare X and Y"
    Exploratory, // "Tell me about X"
}
}

ROGRAG Decomposition:

Complex: "Compare Tom's and Huck's roles in finding the treasure"

Decomposed:
  1. "What role did Tom play in finding the treasure?"
  2. "What role did Huck play in finding the treasure?"
  3. [Synthesis] "Compare the two roles"

Accuracy: 60% → 75% (+15% boost!)

Configuration:

[query_processing]
analyzer = "advanced"                  # or "basic", "rograg"
enable_decomposition = true
max_sub_queries = 5
confidence_threshold = 0.6

Stage 7: Answer Generation - 4 LLM Backends

Caching Layer (6x cost reduction):

#![allow(unused)]
fn main() {
// src/caching/cached_client.rs
let cache_key = generate_semantic_key(prompt);
if let Some(cached) = cache.get(&cache_key) {
    return cached;  // 80%+ hit rate!
}
let response = llm.generate(prompt).await?;
cache.put(cache_key, response.clone());
}

Trait Implementation:

#![allow(unused)]
fn main() {
pub trait LanguageModel {
    fn complete(&self, prompt: &str) -> Result<String>;
    fn complete_with_params(&self, prompt: &str, params: GenerationParams);
    fn is_available(&self) -> bool;
}

#[async_trait]
pub trait AsyncLanguageModel {
    async fn complete(&self, prompt: &str) -> Result<String>;
    async fn complete_batch(&self, prompts: &[&str]) -> Result<Vec<String>>;
    async fn complete_streaming(&self, prompt: &str) -> Stream<String>;
}
}

Configuration:

[generation]
backend = "ollama"                     # or "webllm", "mock"
model = "llama3.1:8b"
temperature = 0.7
max_tokens = 1000
enable_caching = true
cache_ttl_seconds = 3600

Configuration Matrix: Choose Your Stack

Use Case: Production Server

[pipeline]
chunk_size = 800
chunk_overlap = 200

[embeddings]
provider = "ollama"
model = "nomic-embed-text"
device = "cuda"

[entity_extraction]
method = "gleaning"
llm_model = "llama3.1:8b"

[graph]
backend = "qdrant"
enable_pagerank = true

[retrieval]
strategy = "hybrid"
enable_lightrag = true

[generation]
backend = "ollama"
model = "llama3.1:8b"
enable_caching = true

Use Case: WASM Browser (Privacy-First)

[embeddings]
provider = "onnx_web"
model = "all-MiniLM-L6-v2"
device = "webgpu"

[entity_extraction]
method = "pattern"                     # No LLM required

[graph]
backend = "in-memory"
enable_pagerank = true

[retrieval]
strategy = "hybrid"
enable_lightrag = true

[generation]
backend = "webllm"
model = "Phi-3-mini"

Use Case: Testing/Development

[embeddings]
provider = "hash"                      # <1ms, deterministic

[entity_extraction]
method = "pattern"

[graph]
backend = "in-memory"

[retrieval]
strategy = "vector"

[generation]
backend = "mock"                       # Instant responses

Module Reference:

• Core Traits: src/core/traits.rs (lines 1-1291) - All pluggable abstractions
• Hybrid Embedder: src/embeddings/hybrid.rs - Auto-fallback system
• Retrieval Strategies: src/retrieval/ - 5 retrieval implementations
• Configuration: src/config/toml_config.rs - TOML-based setup

How to Customize Parameters and Tools

GraphRAG-rs offers 3 progressive levels of customization - from simple TOML files to programmatic trait implementations.

Level 1: TOML Configuration Files (Easiest)

Modify 60+ parameters without touching code using TOML configuration.

Where to Write Alternative Settings?

✅ Option 1: Use Pre-Built Templates (Copy & Modify)

# 1. Copy a template that matches your use case
cp config/templates/narrative_fiction.toml my_config.toml

# 2. Edit the file to change settings
nano my_config.toml

# 3. Run GraphRAG with your config
cargo run --bin simple_cli my_config.toml "Your question"

✅ Option 2: Create Your Own Config File

# 1. Create a new .toml file anywhere
touch my_custom_config.toml

# 2. Add your settings (see examples below)
nano my_custom_config.toml

# 3. Use it
cargo run --bin simple_cli my_custom_config.toml

✅ Option 3: Edit Existing Examples

# Modify the example configs
nano docs-example/symposium_config.toml
nano docs-example/config_tom_sawyer_complete.toml

How TOML Configuration Works

TOML files specify alternative implementations like this:

# Example: my_config.toml

# Stage 2: Choose embedding provider
[embeddings]
provider = "ollama"          # Alternative: "neural", "hybrid", "hash"
model = "nomic-embed-text"   # Alternative: "all-MiniLM-L6-v2"
device = "cuda"              # Alternative: "cpu", "auto"

# Stage 3: Choose entity extraction method
[pipeline.entity_extraction]
model_name = "llama3.1:8b"   # Uses LLM for extraction
temperature = 0.1            # Alternative: 0.7 for creative
entity_types = ["PERSON", "LOCATION", "CONCEPT"]  # Customize types!

# Stage 5: Choose retrieval strategy
[retrieval]
strategy = "hybrid"          # Alternative: "vector", "bm25", "pagerank", "adaptive"
enable_lightrag = true       # Alternative: false (standard retrieval)

# Stage 7: Choose LLM backend
[generation]
backend = "ollama"           # Alternative: "webllm", "mock"
model = "llama3.1:8b"        # Alternative: any Ollama model
enable_caching = true        # Alternative: false (no cache)

The system automatically uses your settings! No code changes needed.

Pre-Built Templates (Recommended Starting Point)

Located in config/templates/, optimized for different document types:

Example: Customize for Your Document Type

# 1. Copy a template
cp config/templates/narrative_fiction.toml my_config.toml

# 2. Edit parameters (see full list below)
nano my_config.toml

# 3. Use your config
cargo run --bin simple_cli my_config.toml "Your question"

Complete TOML Configuration Reference

A. General Settings

[general]
input_document_path = "path/to/document.txt"  # Your document
output_dir = "./output/my_project"            # Results directory
log_level = "info"                            # error|warn|info|debug|trace
max_threads = 4                               # 0 = auto-detect CPU cores
enable_profiling = true                       # Performance metrics

B. Pipeline Workflows

[pipeline]
workflows = [
    "extract_text",        # Stage 1: Chunking
    "extract_entities",    # Stage 3: Entity extraction
    "build_graph",         # Stage 4: Graph construction
    "detect_communities"   # Stage 4: Community detection
]
parallel_execution = true  # Enable concurrent processing

C. Stage 1: Text Chunking

[pipeline.text_extraction]
chunk_size = 800              # Characters per chunk
chunk_overlap = 300           # Overlap for context (typically 25-50% of chunk_size)
min_chunk_size = 200          # Skip chunks smaller than this
clean_control_chars = true    # Remove \r, \t, etc.
normalize_whitespace = true   # Collapse multiple spaces

# Optional text cleaning
[pipeline.text_extraction.cleaning]
remove_urls = false           # Strip http:// links
remove_emails = false         # Strip email addresses
remove_special_chars = false  # Keep punctuation by default

D. Stage 2: Embeddings

[embeddings]
provider = "ollama"           # Options: ollama, neural, hybrid, hash
model = "nomic-embed-text"    # Model name (depends on provider)
dimension = 768               # Embedding vector size
batch_size = 32               # Embeddings per batch
device = "cuda"               # Options: cuda, cpu, auto
cache_size = 10000            # Number of cached embeddings

# Ollama-specific settings
[ollama]
base_url = "http://localhost:11434"
embedding_model = "nomic-embed-text"
generation_model = "llama3.1:8b"
timeout_seconds = 300

E. Stage 3: Entity Extraction

[pipeline.entity_extraction]
model_name = "llama3.1:8b"    # LLM for extraction
temperature = 0.1             # Lower = more deterministic (0.0-1.0)
max_tokens = 1500             # Maximum response length
confidence_threshold = 0.6    # Minimum confidence to keep entity

# Entity types to extract (fully customizable!)
entity_types = [
    "PERSON",                 # People, characters
    "LOCATION",               # Places, settings
    "CONCEPT",                # Abstract ideas, themes
    "EVENT",                  # Actions, occurrences
    "ORGANIZATION",           # Groups, institutions
    "OBJECT",                 # Physical items
    "EMOTION",                # Feelings, states
    "THEME"                   # Overarching topics
]

# Advanced: Entity filtering
[pipeline.entity_extraction.filters]
min_entity_length = 2         # Minimum characters
max_entity_length = 100       # Maximum characters
allowed_patterns = [          # Regex patterns to allow
    "^[A-Z][a-zA-Z\\s'-]+$"   # Capitalized words
]
excluded_patterns = [         # Regex patterns to exclude
    "^(the|and|but)$",        # Common stop words
    "^\\d+$"                  # Pure numbers
]

# Gleaning (multi-pass extraction)
[entity_extraction]
use_gleaning = true           # Enable iterative extraction
max_gleaning_rounds = 4       # Number of refinement passes
gleaning_improvement_threshold = 0.08  # Min improvement to continue

F. Stage 4: Graph Construction

[pipeline.graph_building]
relation_scorer = "cosine_similarity"  # or "jaccard", "levenshtein"
min_relation_score = 0.4      # Minimum similarity to create edge
max_connections_per_node = 25 # Limit edges per entity
bidirectional_relations = true # A→B implies B→A
character_centrality_boost = 1.5  # Boost importance of main entities

# Community detection
[pipeline.community_detection]
algorithm = "leiden"          # Options: leiden, louvain
resolution = 0.6              # Lower = tighter communities
min_community_size = 2        # Minimum entities per community
max_community_size = 15       # Maximum entities per community

# Semantic merging (entity deduplication)
[entity_extraction]
semantic_merging = true
merge_similarity_threshold = 0.85  # How similar to merge (0.0-1.0)
automatic_linking = true
linking_confidence_threshold = 0.7

G. Stage 5: Retrieval

[retrieval]
strategy = "hybrid"           # Options: vector, bm25, pagerank, hybrid, adaptive
k = 10                        # Top-k results to return
enable_lightrag = true        # Dual-level retrieval
enable_pagerank = true        # Graph importance scoring

# Hybrid strategy weights (must sum to ~1.0)
[retrieval.fusion_weights]
vector = 0.4                  # Semantic similarity weight
bm25 = 0.3                    # Keyword matching weight
pagerank = 0.3                # Graph importance weight

H. Stage 6: Query Processing

[query_processing]
analyzer = "advanced"         # Options: basic, advanced, rograg
enable_decomposition = true   # Break complex queries into sub-queries
max_sub_queries = 5           # Maximum decomposition depth
confidence_threshold = 0.6    # Minimum confidence for query understanding

I. Stage 7: Answer Generation

[generation]
backend = "ollama"            # Options: ollama, webllm, mock
model = "llama3.1:8b"
temperature = 0.7             # Creativity (0.0-1.0)
max_tokens = 1000             # Maximum answer length
top_p = 0.9                   # Nucleus sampling (0.0-1.0)
enable_caching = true         # Cache LLM responses
cache_ttl_seconds = 3600      # Cache expiration (1 hour)

J. Performance Tuning

[performance]
batch_size = 32               # Items per batch
max_concurrent_requests = 10  # Parallel API calls
embedding_cache_size = 10000  # Cached embeddings
enable_gpu = true             # GPU acceleration
gpu_device = 0                # GPU device ID (0 = first GPU)

K. Experimental Features

[experimental]
enable_rograg = true          # Query decomposition (+15% accuracy)
enable_fast_graphrag = true   # PageRank retrieval (27x faster)
enable_lightrag = true        # Dual-level retrieval (6000x tokens)

Real-World Example: Optimizing for Plato’s Symposium

# config/symposium_optimized.toml
[general]
input_document_path = "Symposium.txt"
output_dir = "./output/symposium"

[pipeline.text_extraction]
chunk_size = 800              # Larger for complete philosophical arguments
chunk_overlap = 300           # High overlap for dialogue continuity

[pipeline.entity_extraction]
temperature = 0.1             # Low for consistent concept extraction
entity_types = [
    "PERSON",                 # Socrates, Phaedrus, etc.
    "CONCEPT",                # Eros, Beauty, Love
    "ARGUMENT",               # Philosophical positions
    "DIALOGUE_SPEAKER",       # Who said what
    "MYTHOLOGICAL_REFERENCE"  # Gods, myths
]
confidence_threshold = 0.6    # Lower for philosophical nuance

[pipeline.graph_building]
min_relation_score = 0.4      # Lower for subtle philosophical connections
max_connections_per_node = 25 # Higher for complex concept networks

[retrieval]
strategy = "hybrid"           # Best for philosophical queries
enable_lightrag = true
fusion_weights = { vector = 0.5, bm25 = 0.2, pagerank = 0.3 }

Results:

• ✅ Captures 189 philosophical entities (vs 120 with defaults)
• ✅ Identifies speaker-argument relationships
• ✅ 85% query accuracy on philosophical questions

Level 2: Runtime API Configuration (Intermediate)

Modify parameters programmatically using the Builder API.

#![allow(unused)]
fn main() {
use graphrag_rs::{GraphRAG, ConfigPreset};

let mut graphrag = GraphRAG::builder()
    // Choose preset as starting point
    .with_preset(ConfigPreset::PerformanceOptimized)

    // Override specific parameters
    .chunk_size(1024)                     // Stage 1
    .chunk_overlap(256)

    .embedding_model("all-mpnet-base-v2") // Stage 2
    .embedding_dimension(768)

    .entity_confidence(0.7)               // Stage 3
    .max_gleaning_rounds(3)

    .enable_pagerank(true)                // Stage 4
    .enable_lightrag(true)                // Stage 5

    .retrieval_strategy("hybrid")         // Stage 5
    .top_k(15)

    .llm_temperature(0.8)                 // Stage 7
    .max_tokens(1500)

    // Auto-detect available tools
    .auto_detect_llm()
    .auto_detect_embedder()

    .build()?;

// Process document
graphrag.add_document("Your text")?;

// Query with custom parameters
let answer = graphrag.ask_with_params(
    "Your question",
    QueryParams {
        max_results: 10,
        min_confidence: 0.7,
        enable_decomposition: true,
    }
)?;
}

Available Builder Methods:

Level 3: Custom Trait Implementations (Advanced)

Replace entire pipeline stages with custom implementations.

Example: Custom Embedder

#![allow(unused)]
fn main() {
use graphrag_rs::core::traits::{Embedder, Result};

pub struct MyCustomEmbedder {
    api_key: String,
    model: String,
}

impl Embedder for MyCustomEmbedder {
    type Error = std::io::Error;

    fn embed(&self, text: &str) -> Result<Vec<f32>> {
        // Your custom embedding logic
        // Call external API, use custom model, etc.
        let embedding = my_api_call(text, &self.api_key)?;
        Ok(embedding)
    }

    fn embed_batch(&self, texts: &[&str]) -> Result<Vec<Vec<f32>>> {
        texts.iter()
            .map(|text| self.embed(text))
            .collect()
    }

    fn dimension(&self) -> usize {
        1024  // Your embedding dimension
    }

    fn is_ready(&self) -> bool {
        !self.api_key.is_empty()
    }
}

// Use your custom embedder
let custom_embedder = MyCustomEmbedder {
    api_key: "your-key".to_string(),
    model: "custom-model-v1".to_string(),
};

let graphrag = GraphRAG::builder()
    .with_embedder(Box::new(custom_embedder))
    .build()?;
}

Example: Custom Entity Extractor

#![allow(unused)]
fn main() {
use graphrag_rs::core::traits::{EntityExtractor, Result};
use graphrag_rs::core::Entity;

pub struct MyCustomNER {
    model_path: String,
}

impl EntityExtractor for MyCustomNER {
    type Entity = Entity;
    type Error = std::io::Error;

    fn extract(&self, text: &str) -> Result<Vec<Entity>> {
        // Your custom NER logic
        // Could use spaCy, Flair, custom ML model, etc.
        let entities = my_ner_model(text, &self.model_path)?;
        Ok(entities)
    }

    fn extract_with_confidence(&self, text: &str) -> Result<Vec<(Entity, f32)>> {
        let entities = self.extract(text)?;
        entities.into_iter()
            .map(|e| (e, 0.95))  // Add confidence scores
            .collect()
    }

    fn set_confidence_threshold(&mut self, threshold: f32) {
        // Store threshold for filtering
    }
}
}

Available Traits to Implement

See: src/core/traits.rs (lines 1-1291) for complete trait definitions.

Configuration Validation & Testing

# 1. Validate TOML configuration
cargo run --bin simple_cli my_config.toml --validate

# 2. Dry-run with mock LLM (instant, no API calls)
cargo run --bin simple_cli my_config.toml --dry-run

# 3. Profile performance with your config
cargo run --bin simple_cli my_config.toml --profile

# 4. Compare configurations
cargo run --bin benchmark_configs config1.toml config2.toml

Quick Reference: Key Parameters by Use Case

Pro Tips:

1. Start with templates: config/templates/ covers 90% of use cases
2. Iterate: Run with defaults → profile → adjust → rerun
3. Document-specific: Longer chunks (800-1024) for narrative, shorter (512) for technical
4. Temperature: Lower (0.1-0.3) for factual, higher (0.7-0.9) for creative
5. Confidence threshold: Lower (0.5-0.6) for nuanced texts, higher (0.7-0.8) for precision
6. Retrieval: hybrid is best general-purpose, bm25 for exact matches, vector for semantic

Module References:

• TOML Config: src/config/toml_config.rs - All configuration structures
• Builder API: src/builder.rs - Fluent API for runtime config
• Core Traits: src/core/traits.rs - Pluggable implementations
• Templates: config/templates/ - Pre-optimized configurations

Three Deployment Architectures

GraphRAG-rs uniquely supports three distinct deployment modes - choose based on your requirements:

1. Server-Only (Production Ready ✅)

Architecture:

┌─────────────┐
│ Client App  │ (React/Vue/Mobile)
└──────┬──────┘
       │ REST API
┌──────▼────────────────────┐
│  graphrag-server          │
│  ├─ Actix-web REST API    │
│  ├─ Apistos OpenAPI 3.0.3 │
│  ├─ Qdrant Vector DB      │
│  ├─ Ollama Embeddings     │
│  └─ GPU Acceleration      │
└───────────────────────────┘

Best For:

• Multi-tenant SaaS (>1000 users)
• Large datasets (>1M documents)
• GPU-accelerated inference
• Mobile apps (thin clients)

Tech Stack:

Backend: Rust + Actix-web 4.9 + Apistos (OpenAPI 3.0.3) + Tokio
Vector DB: Qdrant (scales to 100M+ vectors)
Embeddings: Ollama (nomic-embed-text, GPU)
LLM: Ollama (llama3.1:8b, GPU)
Binary Size: 5.2 MB (optimized release)

Performance:

• Startup: <1s
• Query: 500ms-2s (end-to-end)
• Throughput: 20 queries/sec

2. WASM-Only (60% Complete )

Architecture:

┌───────────────────────────┐
│       Browser             │
│  ┌─────────────────────┐  │
│  │ Leptos UI (WASM)    │  │
│  │ ├─ ONNX Embeddings  │  │ ← GPU via WebGPU
│  │ ├─ WebLLM Inference │  │ ← 40-62 tok/s GPU
│  │ ├─ Voy Vector Search│  │ ← 75KB pure Rust
│  │ └─ IndexedDB Storage│  │ ← Offline persistence
│  └─────────────────────┘  │
└───────────────────────────┘
     ↑ NO SERVER REQUIRED!

Best For:

• Privacy-first applications
• Offline-first tools
• Zero infrastructure cost
• Edge deployment (CDN)

Tech Stack:

Frontend: Leptos 0.8 + Trunk
ML: ONNX Runtime Web (WebGPU, 3-8ms embeddings)
LLM: WebLLM (WebGPU, 40-62 tok/s)
Vector Search: Voy (75KB k-d tree)
Storage: IndexedDB + Cache API
WASM Size: ~2MB (gzipped)

Performance:

• Cold start: 2-3s (model loading)
• Embeddings: 3-8ms per chunk (GPU)
• LLM: 40-62 tok/s (GPU)
• Storage: 50% browser quota (~5-10GB)

3. Hybrid (Planned )

Architecture:

┌───────────────────────────┐
│       Browser             │
│  ┌─────────────────────┐  │
│  │ WASM Client (Fast)  │  │ ← Real-time UI
│  │ + GPU Embeddings    │  │ ← 3-8ms GPU
│  │ + Local Cache       │  │ ← Offline-first
│  └──────────┬──────────┘  │
└─────────────┼─────────────┘
              │ Optional WebSocket
┌─────────────▼─────────────┐
│  Server (Heavy Compute)   │
│  ├─ Batch Processing      │ ← Large documents
│  ├─ Multi-user Sync       │ ← Shared knowledge
│  └─ Background Jobs       │ ← Scheduled updates
└───────────────────────────┘

Best For:

• Enterprise applications
• Multi-device sync
• Best UX + Scalability
• Collaborative knowledge management

Status: Architecture designed, Phase 3 implementation

Optional Components & Features

GraphRAG-rs is modular - enable only what you need via feature flags:

LightRAG (Dual-Level Retrieval)

What: Searches entities (low-level) + communities (high-level) simultaneously

Impact:

• ✅ 6000x token reduction vs traditional GraphRAG
• ✅ 60ms query time (vs 2-5 seconds)
• ✅ Better context retention

Enable:

# Cargo.toml
[features]
lightrag = []

# Usage
cargo build --features lightrag

Module: src/lightrag/dual_retrieval.rs

PageRank (Fast-GraphRAG)

What: Ranks entities by graph importance, personalizing to query context

Impact:

• ✅ 27x performance boost in retrieval
• ✅ 6x cost reduction
• ✅ Better relevance ranking

Enable:

[features]
pagerank = []

# Usage
cargo build --features pagerank

Module: src/graph/pagerank.rs

ROGRAG (Query Decomposition)

What: Breaks complex queries into sub-queries with logic-based reasoning

Impact:

• ✅ 15% accuracy improvement (60% → 75%)
• ✅ Handles multi-hop questions
• ✅ Structured reasoning traces

Enable:

[features]
rograg = []

Module: src/rograg/logic_form.rs

GPU Acceleration

Options:

Example:

# NVIDIA GPU acceleration
cargo build --release --features "neural-embeddings,cuda,ollama"

# Apple Silicon
cargo build --release --features "neural-embeddings,metal,ollama"

Intelligent Caching

What: Caches LLM responses with semantic key generation

Impact:

• ✅ 80%+ hit rate in production
• ✅ 6x cost reduction
• ✅ 16-20x latency reduction (100ms → 5ms)

Enable:

[features]
caching = ["moka"]

Module: src/caching/cached_client.rs

Monitoring & Metrics

GraphRAG-rs includes comprehensive performance tracking across the entire pipeline.

PipelineStage Tracking

#![allow(unused)]
fn main() {
// src/monitoring/metrics.rs
pub enum PipelineStage {
    QueryExpansion,
    HybridRetrieval,
    BM25Search,
    VectorSearch,
    ResultFusion,
    Reranking,
    ConfidenceFiltering,
    TotalPipeline,
}
}

Real-Time Metrics

#![allow(unused)]
fn main() {
let mut timer = TimingBreakdown::new();

timer.start_stage(PipelineStage::VectorSearch);
let results = vector_search(query).await?;
let duration = timer.end_stage(PipelineStage::VectorSearch);

println!("Vector search: {:?}", duration);
// Output: Vector search: 23ms
}

Performance Breakdown

Query Performance Breakdown:
  Total time: 342ms
  Expanded queries: 3
  Raw results: 45
  Final results: 10
  Average confidence: 0.87

  Stage timings:
    QueryExpansion: 52ms (15.2%)
    VectorSearch: 103ms (30.1%)
    BM25Search: 45ms (13.2%)
    ResultFusion: 67ms (19.6%)
    Reranking: 48ms (14.0%)
    ConfidenceFiltering: 27ms (7.9%)

Module: src/monitoring/metrics.rs, src/monitoring/benchmark.rs

Learn More

Documentation

• ARCHITECTURE.md - Deep technical dive into implementation
• examples/ - Hands-on code examples
• IMPLEMENTATION_PLAN.md - Development roadmap
• diagram.md - Visual architecture diagrams

Practical Examples

Getting Started:

• examples/01_basic_usage.rs - One-line API
• examples/02_stateful_api.rs - Multi-query sessions
• examples/03_builder_api.rs - Full configuration

Advanced:

• examples/real_ollama_pipeline.rs - Complete 7-stage walkthrough
• examples/multi_document_pipeline.rs - Incremental graph construction
• examples/graphrag_multi_doc_server.rs - Production REST API

Configuration Templates

Pre-optimized configs for different document types:

config/templates/
├── narrative_fiction.toml      # Books, novels (800-char chunks)
├── academic_research.toml      # Papers, studies (1024-char chunks)
├── technical_documentation.toml # Manuals, specs (512-char chunks)
├── legal_documents.toml        # Contracts, laws (512-char, low temp)
├── web_blog_content.toml       # Articles, blogs (600-char chunks)
└── dynamic_universal.toml      # General-purpose (adaptive)

Research Papers

GraphRAG-rs implements cutting-edge research:

1. Microsoft GraphRAG (2024) - “From Local to Global: A Graph RAG Approach”

   • Base architecture foundation
   • Community detection algorithms

2. Fast-GraphRAG (2024) - PageRank-based retrieval

   • 27x performance improvement
   • 6x cost reduction

3. LightRAG (2024) - “Simple and Fast Retrieval-Augmented Generation”

   • Dual-level retrieval
   • 6000x token reduction

4. ROGRAG (2024) - Robust query processing

   • Query decomposition
   • 60% → 75% accuracy boost

Quick Start: See It In Action

1. One-Liner (Simplest)

#![allow(unused)]
fn main() {
use graphrag_rs::simple;

let answer = simple::answer(
    "Tom found treasure in the cave",
    "What did Tom find?"
)?;
// Output: "Tom found treasure in the cave."
}

2. Multi-Query Session

#![allow(unused)]
fn main() {
use graphrag_rs::easy::SimpleGraphRAG;

let mut graph = SimpleGraphRAG::from_text("Your document")?;

graph.ask("What are the main themes?")?;
graph.ask("Who are the characters?")?;
}

3. Production Server

# Start Ollama
ollama serve &
ollama pull llama3.1:8b
ollama pull nomic-embed-text

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

# Query via REST API
curl -X POST http://localhost:8080/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What did Tom find in the cave?"}'

4. WASM Browser (100% client-side)

cd graphrag-wasm
trunk serve --open

# Visit http://localhost:8080
# Upload document → Build graph → Query → Get answers (100% client-side!)

Configuration-Driven Behavior: Complete Examples

Example 1: Fast Pattern-Based Pipeline (No LLM)

Use Case: Testing, development, offline deployment, resource-constrained environments

Configuration (fast_config.toml):

[general]
log_level = "info"

[entity_extraction]
enabled = true
min_confidence = 0.7
use_gleaning = false          # ← Pattern-based extraction

[ollama]
enabled = false               # ← No LLM required

[embeddings]
backend = "hash"              # ← Fast hash-based embeddings
dimension = 128

[retrieval]
strategy = "vector"           # ← Simple vector search

Runtime Behavior:

[INFO] Configuration loaded from: fast_config.toml
[INFO] Using pattern-based entity extraction
  ✓ Regex + capitalization-based
  ✓ No LLM required
[INFO] Using hash-based embeddings (128 dimensions)
[INFO] Using vector retrieval strategy

Pipeline Performance:
  Chunking:           0.01s
  Embeddings:         0.002s (<1ms per chunk)
  Entity Extraction:  0.005s (<10ms per chunk)
  Graph Construction: 0.05s
  Query Processing:   0.03s
  TOTAL:              0.097s (~100ms)

Results: ✅ Ultra-fast, ✅ No dependencies, ✅ Offline-capable, Good quality (not excellent)

Example 2: High-Accuracy LLM Pipeline (Symposium Philosophy)

Use Case: Academic analysis, philosophical texts, high-quality extraction

Configuration (symposium_config.toml):

[general]
input_document_path = "info/Symposium.txt"
log_level = "info"

[entity_extraction]
enabled = true
min_confidence = 0.6          # ← Lower for philosophical nuance
use_gleaning = true           # ← LLM-based extraction
max_gleaning_rounds = 4       # ← 4 refinement passes
semantic_merging = true
automatic_linking = true

[pipeline.entity_extraction]
model_name = "llama3.1:8b"
temperature = 0.1             # ← Low for consistent concept extraction
entity_types = [
    "PERSON",                 # Socrates, Phaedrus
    "CONCEPT",                # Eros, Beauty, Love
    "ARGUMENT",               # Philosophical positions
    "MYTHOLOGICAL_REFERENCE"  # Gods, myths
]

[ollama]
enabled = true
host = "http://localhost"
port = 11434
chat_model = "llama3.1:8b"    # ← AI-powered extraction
embedding_model = "nomic-embed-text"
fallback_to_hash = false      # ← Error if Ollama fails

[embeddings]
backend = "ollama"
model = "nomic-embed-text"
dimension = 768

[retrieval]
strategy = "hybrid"           # ← Best for philosophical queries
enable_lightrag = true

Runtime Behavior:

[INFO] Configuration loaded from: symposium_config.toml
[INFO] Using LLM-based entity extraction with gleaning (max_rounds: 4)
  ✓ Ollama client initialized
  ✓ Model: llama3.1:8b
  ✓ Entity types: PERSON, CONCEPT, ARGUMENT, MYTHOLOGICAL_REFERENCE

Processing Symposium.txt (189 KB, 455 chunks):

Chunk 1/455:
  Round 1: Extract entities → Found 8 entities (PERSON: 2, CONCEPT: 4, ARGUMENT: 2)
  Round 2: "Did you miss any entities?" → Found 2 more (CONCEPT: 2)
  Round 3: "Find relationships" → Found 3 relationships
  Round 4: "Final check" → Found 1 subtle concept
  ✅ Extraction complete: 11 entities, 3 relationships

... (processing all chunks) ...

[INFO] Final Results:
  Entities:      317 (PERSON: 89, CONCEPT: 156, ARGUMENT: 45, MYTHOLOGICAL_REFERENCE: 27)
  Relationships: 455
  Communities:   12 (speaker groups, concept clusters)
  Processing Time: 325ms per chunk average

[INFO] Using Ollama embeddings: nomic-embed-text (768 dimensions)
[INFO] Using hybrid retrieval: vector (40%) + bm25 (30%) + pagerank (30%)

Query: "What is love according to Socrates?"
  VectorSearch:   123ms
  BM25Search:     45ms
  PageRankScore:  67ms
  Fusion (RRF):   28ms
  TOTAL:          263ms

Answer: "According to Socrates in the Symposium, love (Eros) is the
         pursuit of beauty and wisdom. Socrates relates Diotima's teaching
         that love is not a god but a spirit that mediates between mortals
         and the divine..."

Results: ★★★★★ Excellent quality, ✅ Contextual understanding, ✅ Custom entity types, Requires Ollama/GPU

Example 3: Hybrid Configuration (Tom Sawyer Narrative)

Use Case: Fiction analysis, balanced quality/performance

Configuration (tom_sawyer_config.toml):

[entity_extraction]
enabled = true
min_confidence = 0.65
use_gleaning = true           # ← LLM-based
max_gleaning_rounds = 2       # ← Only 2 rounds (faster)

[ollama]
enabled = true
chat_model = "llama3.1:8b"

[embeddings]
backend = "ollama"            # ← Real semantic embeddings
model = "nomic-embed-text"
fallback_to_hash = true       # ← Fallback if Ollama unavailable

[retrieval]
strategy = "hybrid"
enable_lightrag = true        # ← Dual-level retrieval

Runtime Behavior:

[INFO] Using LLM-based entity extraction with gleaning (max_rounds: 2)
[INFO] Using Ollama embeddings with hash fallback

Processing Tom Sawyer (434 KB, 492 chunks):
  Chunking:           0.01s
  Embeddings:         0.08s (Ollama, 768-dim)
  Entity Extraction:  0.6s (LLM, 2 rounds)
  Graph Construction: 0.05s
  TOTAL:              0.74s (~750ms)

Query: "How did Tom and Huck find the treasure?"
  Low-level retrieval:  23ms (entities: Tom, Huck, treasure)
  High-level retrieval: 31ms (community: treasure hunting storyline)
  Fusion:               12ms
  TOTAL:                66ms

Answer: "Tom and Huck discovered the treasure in McDougal's Cave after
         witnessing Injun Joe hide it there..."

Results: ★★★★ Very good quality, Balanced performance, ✅ Fallback safety

Configuration Comparison Matrix

Key Insight: The same codebase adapts automatically - you control behavior through configuration!

Key Takeaways

1. 7 Stages: Text → Chunks → Vectors → Entities → Graph → Retrieval → Query → Answer
2. 3 Architectures: Server-Only ✅ | WASM-Only | Hybrid
3. Configuration-Driven: Same code, different behavior via TOML settings
4. Dynamic Selection: Pipeline adapts based on use_gleaning, ollama.enabled, retrieval.strategy
5. State-of-the-Art: LightRAG (6000x reduction) + PageRank (27x speedup) + ROGRAG (+15% accuracy)
6. Production-Ready: 5.2MB binary, <1s startup, 500ms-2s queries
7. Modular: Enable only what you need via feature flags
8. GPU-Accelerated: CUDA, Metal, Vulkan, WebGPU support

GraphRAG transforms documents into intelligent knowledge that answers questions with unprecedented accuracy and context awareness - all controlled by simple TOML configuration.

Last Updated: October 2025 | GraphRAG-rs v1.0