Skip to content

USER_GUIDE.md

Latest commit

 

History

History
935 lines (681 loc) · 19.7 KB

USER_GUIDE.md

File metadata and controls

935 lines (681 loc) · 19.7 KB

🚀 GraphRAG-CLI Complete User Guide

GraphRAG-CLI is a modern Terminal User Interface (TUI) for GraphRAG operations, built with Ratatui for interactive knowledge graph exploration.

📋 Table of Contents

🔧 Installation & Build

Prerequisites

  • Rust 1.70 or higher
  • Ollama installed and running (for LLM models)

Building

# From the project root directory
cargo build --release -p graphrag-cli

# The binary will be available at:
# ./target/release/graphrag-cli

Add to PATH (optional)

# Linux/macOS
export PATH="$PATH:$(pwd)/target/release"

# Or create a symbolic link
sudo ln -s $(pwd)/target/release/graphrag-cli /usr/local/bin/graphrag-cli

⚡ Quick Start

1. Launch the Interactive TUI

# Basic launch
./target/release/graphrag-cli

# With configuration file
./target/release/graphrag-cli --config docs-example/symposium_config.toml

# With specific workspace
./target/release/graphrag-cli --workspace my_project

# With debug logging
./target/release/graphrag-cli --debug

2. First Time Setup

  1. Start the TUI:

    ./target/release/graphrag-cli

  2. Load a configuration: In the TUI, press Shift+Tab to enter command mode, then type:

    /config docs-example/symposium_config.toml

  3. Load a document:

    /load docs-example/platos_symposium.txt

  4. Execute queries: Return to Query Mode (press Shift+Tab) and type:

    What does Socrates say about love?

🎯 Usage Modes

GraphRAG-CLI has two primary modes:

📝 Query Mode

  • Purpose: Execute queries on the knowledge graph
  • How to use: Type your question directly
  • Example: What are the main themes in the Symposium?
  • Border color: Green

⚙️ Command Mode

  • Purpose: Execute system commands (slash commands)
  • How to use: Press Shift+Tab to switch from Query Mode
  • Example: /config myfile.toml
  • Border color: Yellow

Switch between modes: Shift+Tab

🔀 Slash Commands

Slash commands are only available in Command Mode.

/config <file>

Load a GraphRAG configuration file (TOML or JSON5)

# Example with TOML
/config docs-example/symposium_config.toml

# Example with absolute path
/config /home/user/graphrag-rs/my_config.toml

# Example with relative path
/config ../config/templates/academic_research.toml

What it does:

  • Loads LLM configuration (Ollama, OpenAI, etc.)
  • Configures embeddings and chunking strategy
  • Initializes the knowledge graph

/load <file>

Load and process a document into the knowledge graph

# Load a text file
/load docs-example/platos_symposium.txt

# Load a markdown file
/load ~/documents/research_paper.md

# Load multiple documents (execute multiple times)
/load document1.txt
/load document2.txt
/load document3.txt

What it does:

  1. Reads the document
  2. Splits into chunks (based on config)
  3. Extracts entities and relationships using REAL LLM calls (not pattern matching!)
  4. Builds the knowledge graph
  5. Generates embeddings

Processing time (with TRUE LLM gleaning extraction):

  • Small docs (5-10 pages): 5-15 minutes
  • Medium docs (50-100 pages): 30-60 minutes
  • Large docs (500-1000 pages): 2-4 hours

This is REAL semantic extraction with multi-round LLM refinement, not instant pattern matching!

/stats

Show knowledge graph statistics

/stats

Output:

Knowledge Graph Statistics:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📚 Documents:      3
📄 Chunks:         127
👤 Entities:       45
🔗 Relationships:  89
📊 Graph Density:  0.087

/entities [filter]

List entities in the knowledge graph with optional filter

# List all entities
/entities

# Filter by name
/entities socrates

# Filter by type
/entities PERSON

# Filter by concept
/entities love

Output:

Entities (filtered: "socrates"):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 Socrates [PERSON]
   Mentions: 34
   Confidence: 0.95
   Description: Greek philosopher, student of Plato...

💡 Socratic Method [CONCEPT]
   Mentions: 12
   Confidence: 0.89
   Description: Method of inquiry through questioning...

/workspace <name>

Switch to a different workspace

# Switch workspace
/workspace my_project

# Switch to different workspace
/workspace philosophy_research

What are workspaces?

  • Separate directories for different projects
  • Each workspace has its own knowledge graph
  • Each workspace has its own query history
  • Allows working on multiple projects simultaneously

/help

Show list of all available commands

/help

🗂️ Workspace Management

Workspaces allow you to organize multiple projects separately.

Terminal Commands

# List all workspaces
./target/release/graphrag-cli workspace list

# Create new workspace
./target/release/graphrag-cli workspace create philosophy_research

# Show workspace information
./target/release/graphrag-cli workspace info <workspace-id>

# Delete workspace
./target/release/graphrag-cli workspace delete <workspace-id>

Example: Create and Use a Workspace

# 1. Create workspace
./target/release/graphrag-cli workspace create philosophy_research

# Output:
# ✅ Workspace created successfully!
#    Name: philosophy_research
#    ID:   a1b2c3d4-e5f6-7890-abcd-ef1234567890
#
# Use it with: graphrag-cli tui --workspace a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 2. Start TUI with the workspace
./target/release/graphrag-cli --workspace a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 3. In the TUI, load configuration and documents
# (command mode)
/config docs-example/symposium_config.toml
/load docs-example/platos_symposium.txt

Workspace Paths

Workspaces are saved in:

~/.local/share/graphrag-cli/workspaces/
└── <workspace-id>/
    ├── metadata.json          # Workspace information
    ├── query_history.json     # Query history
    ├── graph.db              # Knowledge graph (if persistent)
    └── embeddings/           # Vector embeddings

⌨️ Keyboard Shortcuts

General Navigation

Key Action
Shift+Tab Switch mode (Query ↔ Command)
Ctrl+C Exit application
? Show help overlay (in Query Mode)
Esc Close help overlay

Input Mode

Key Action
Enter Execute query/command
↑ / ↓ Navigate query/command history
Ctrl+U Clear input line
Ctrl+W Delete previous word

Results Navigation

Key Action
j / ↓ Scroll down
k / ↑ Scroll up
Ctrl+D / PgDn Page down
Ctrl+U / PgUp Page up
Home Beginning of results
End End of results

Help Mode (pressing ?)

Key Action
Esc Close help
q Close help
↑ / ↓ Scroll help

💡 Practical Examples

Example 1: Philosophy Setup (Plato's Symposium)

# 1. Start TUI
./target/release/graphrag-cli

# 2. In Command Mode (Shift+Tab)
/config docs-example/symposium_config.toml
/load docs-example/platos_symposium.txt

# 3. Wait for processing (30-60 seconds)

# 4. In Query Mode (Shift+Tab to return)
What does Socrates say about love?
Who are the main speakers in the Symposium?
Explain the myth of the androgyne

Example 2: Multi-Document Analysis

# 1. Start with configuration
./target/release/graphrag-cli --config config/templates/academic_research.toml

# 2. Load multiple documents (Command Mode)
/load papers/paper1.txt
/load papers/paper2.txt
/load papers/paper3.txt

# 3. Check statistics
/stats

# 4. Analytical queries (Query Mode)
Compare the methodologies used in the three papers
What are the common themes across all documents?
List all authors mentioned

Example 3: Technical Research

# 1. Create dedicated workspace
./target/release/graphrag-cli workspace create rust_docs

# 2. Start with workspace
./target/release/graphrag-cli --workspace <workspace-id> \
  --config config/templates/technical_documentation.toml

# 3. Load documentation (WARNING: This will take time with real LLM processing!)
/load rust-docs/ownership.md    # ~10-15 minutes per document
/load rust-docs/concurrency.md
/load rust-docs/async.md

# 4. Technical queries
Explain Rust's ownership system
How does async/await work in Rust?
What are the main concurrency primitives?

Example 4: Entity Exploration

# 1. After loading documents
/entities

# 2. Filter by type
/entities PERSON
/entities CONCEPT
/entities LOCATION

# 3. Search specific entities
/entities socrates
/entities love
/entities athens

🔍 Troubleshooting

Problem: "Configuration not loaded"

Symptoms: Cannot load documents or execute queries

Solution:

# 1. Make sure to load configuration first
/config path/to/config.toml

# 2. Verify the file exists
ls -la path/to/config.toml

# 3. Check TOML syntax
cat path/to/config.toml

Problem: "Failed to connect to Ollama"

Symptoms: Errors during document loading or queries

Solution:

# 1. Verify Ollama is running
ollama list

# 2. Start Ollama if necessary
ollama serve

# 3. Test connection
curl http://localhost:11434/api/tags

# 4. Verify configured model is available
ollama list | grep qwen3

Problem: "Document processing is slow"

Symptoms: Document loading takes a very long time

NOTE: This is EXPECTED BEHAVIOR with real LLM-based gleaning extraction!

  • Small docs (5-10 pages): 5-15 minutes
  • Medium docs (50-100 pages): 30-60 minutes
  • Large docs (500-1000 pages): 2-4 hours

This is NOT a bug - it's genuine semantic extraction with real LLM API calls.

If you need faster processing (lower quality):

# Speed optimizations in config.toml

[entities]
max_gleaning_rounds = 2      # Reduce from 4 to 2
use_llm_completion_check = false  # Skip LLM completion check

[text.chunking]
chunk_size = 1000            # Larger chunks = fewer LLM calls
chunk_overlap = 50           # Reduce overlap

[ollama]
chat_model = "llama3.1:3b"   # Use smaller/faster model

Problem: "TUI is corrupted/garbled"

Symptoms: Strange characters, corrupted layout

Solution:

# 1. Reset terminal
reset

# 2. Check TERM variable
echo $TERM
# Should be: xterm-256color or similar

# 3. Set if necessary
export TERM=xterm-256color

# 4. Restart TUI
./target/release/graphrag-cli

Problem: "Workspace not found"

Symptoms: Error loading workspace

Solution:

# 1. List available workspaces
./target/release/graphrag-cli workspace list

# 2. Create new workspace if necessary
./target/release/graphrag-cli workspace create my_project

# 3. Use correct ID
./target/release/graphrag-cli --workspace <correct-id>

Problem: "Out of memory"

Symptoms: Crashes during large document processing

Solution:

# Reduce memory usage in config.toml

[text.chunking]
max_tokens = 300  # Reduce chunk size
overlap = 20      # Reduce overlap

[embeddings]
batch_size = 16   # Reduce batch for embeddings

[caching]
enabled = true    # Enable caching to save RAM
max_size_mb = 100 # Limit cache size

📊 Recommended Configurations

For Small Documents (<100KB)

[text.chunking]
method = "semantic"
max_tokens = 500
overlap = 50

[entity.extraction]
use_gleaning = true
max_iterations = 3

For Large Documents (>1MB)

[text.chunking]
method = "simple"
max_tokens = 300
overlap = 20

[entity.extraction]
use_gleaning = false
max_iterations = 1

[caching]
enabled = true
max_size_mb = 500

For Maximum Performance

[text.chunking]
method = "simple"
max_tokens = 400

[entity.extraction]
use_gleaning = false

[async_processing]
enabled = true
max_concurrent_operations = 8

[caching]
enabled = true
cache_embeddings = true

📝 Configuration Examples

Basic Template (TOML)

# my_config.toml

[llm]
provider = "ollama"
model = "qwen3:8b"
temperature = 0.7
max_tokens = 2000

[embeddings]
provider = "ollama"
model = "nomic-embed-text"
dimensions = 768

[text.chunking]
method = "semantic"
max_tokens = 500
overlap = 50

[entity.extraction]
use_gleaning = true
max_iterations = 2

[graph]
enable_pagerank = true
pagerank_damping = 0.85

[storage]
type = "memory"

Advanced Template (JSON5)

// my_config.json5
{
  llm: {
    provider: "ollama",
    model: "qwen3:8b",
    temperature: 0.7,
    max_tokens: 2000,
  },

  embeddings: {
    provider: "ollama",
    model: "nomic-embed-text",
    dimensions: 768,
  },

  text: {
    chunking: {
      method: "hierarchical",
      max_tokens: 500,
      overlap: 50,
    },
  },

  entity: {
    extraction: {
      use_gleaning: true,
      max_iterations: 3,
      confidence_threshold: 0.7,
    },
  },

  graph: {
    enable_pagerank: true,
    enable_leiden: true,
  },

  caching: {
    enabled: true,
    max_size_mb: 200,
    cache_embeddings: true,
  },
}

🎓 Complete Tutorial: First Project

Follow this step-by-step tutorial for your first GraphRAG project:

Step 1: Preparation

# 1. Create project directory
mkdir -p ~/graphrag-projects/philosophy
cd ~/graphrag-projects/philosophy

# 2. Create configuration file
cat > config.toml << 'EOF'
[llm]
provider = "ollama"
model = "qwen3:8b"
temperature = 0.7

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

[text.chunking]
method = "semantic"
max_tokens = 500

[entity.extraction]
use_gleaning = true
max_iterations = 2
EOF

# 3. Prepare documents
mkdir documents
# Copy your documents to ./documents/

Step 2: Launch and Configuration

# 1. Start GraphRAG-CLI
/path/to/graphrag-rs/target/release/graphrag-cli

# 2. In the TUI, switch to Command Mode
# Press: Shift+Tab

# 3. Load configuration
/config ~/graphrag-projects/philosophy/config.toml

# 4. Verify success (should see confirmation message)

Step 3: Loading Documents

# In Command Mode, load documents one at a time
/load ~/graphrag-projects/philosophy/documents/doc1.txt

# Wait for completion (30-60 seconds)

/load ~/graphrag-projects/philosophy/documents/doc2.txt

# Repeat for all documents

Step 4: Exploration

# 1. Check statistics
/stats

# 2. Explore entities
/entities

# 3. Filter entities by type
/entities PERSON
/entities CONCEPT

Step 5: Querying

# Switch to Query Mode
# Press: Shift+Tab

# Execute analytical queries
What are the main philosophical concepts discussed?

# Queries about specific entities
Tell me about Socrates and his ideas

# Comparative queries
Compare Plato's and Aristotle's views on reality

# Thematic queries
What are the main themes in these documents?

🚀 Tips & Tricks

1. Use Query History

  • Press ↑ / ↓ to navigate previous queries
  • Edit and re-execute queries quickly
  • History is persistent per workspace

2. Organize by Projects

# Create workspace for each project
graphrag-cli workspace create project_A
graphrag-cli workspace create project_B
graphrag-cli workspace create project_C

# Switch quickly between projects
graphrag-cli --workspace <project_A_id>

3. Optimize Performance

# Enable all performance features
[async_processing]
enabled = true
max_concurrent_operations = 8

[caching]
enabled = true
cache_embeddings = true

[parallel]
max_workers = 4

4. Debugging

# Start with debug logging
graphrag-cli --debug

# Logs are saved in:
# Linux: ~/.local/share/graphrag-cli/logs/graphrag-cli.log
# View logs in real-time:
tail -f ~/.local/share/graphrag-cli/logs/graphrag-cli.log

5. Batch Processing

# Use script to load many documents
for file in documents/*.txt; do
  echo "/load $file"
done > commands.txt

# Then execute manually in TUI
# (or integrate with future automation)

📚 Additional Resources

Documentation

Configuration Templates

  • config/templates/academic_research.toml
  • config/templates/technical_documentation.toml
  • config/templates/narrative_fiction.toml

Examples

  • examples/multi_document_pipeline.rs
  • examples/symposium_real_search.rs
  • docs-example/symposium_config.toml

🤝 Contributing

Found a bug or want to contribute? Open an issue or pull request at: https://github.com/stevedores-org/oxidizedRAG

📄 License

MIT License - See LICENSE for details

🎯 Quick Reference Card

╔════════════════════════════════════════════════════════════╗
║              GraphRAG-CLI Quick Reference                  ║
╠════════════════════════════════════════════════════════════╣
║ STARTUP                                                    ║
║   graphrag-cli                      Start TUI              ║
║   graphrag-cli --config FILE        With configuration     ║
║   graphrag-cli --workspace ID       With workspace         ║
║                                                            ║
║ MODES                                                      ║
║   Shift+Tab    Switch Query ↔ Command Mode                ║
║   ?            Show help (Query Mode)                      ║
║   Ctrl+C       Exit                                        ║
║                                                            ║
║ COMMANDS (Command Mode)                                    ║
║   /config FILE      Load configuration                     ║
║   /load FILE        Load document                          ║
║   /stats            Show statistics                        ║
║   /entities [FILT]  List entities (with optional filter)   ║
║   /workspace NAME   Switch workspace                       ║
║   /help             Show all commands                      ║
║                                                            ║
║ WORKSPACE (from terminal)                                  ║
║   workspace list         List workspaces                   ║
║   workspace create NAME  Create workspace                  ║
║   workspace info ID      Workspace info                    ║
║   workspace delete ID    Delete workspace                  ║
║                                                            ║
║ NAVIGATION                                                 ║
║   ↑/↓         Navigate history / scroll results            ║
║   j/k         Vim-style scroll (down/up)                   ║
║   Ctrl+D/U    Page down/up                                 ║
║   Home/End    Beginning/end of results                     ║
║   Ctrl+U      Clear line (in input)                        ║
║   Ctrl+W      Delete word (in input)                       ║
╚════════════════════════════════════════════════════════════╝

Happy GraphRAG-ing! 🚀✨