oxidizedRAG

A fast, modular Rust implementation of GraphRAG — graph-based retrieval-augmented generation — that runs natively, in a server, on the CLI, and in the browser via WebAssembly.

oxidizedRAG turns unstructured text into a knowledge graph and uses it to answer questions with multi-hop reasoning, hybrid retrieval (vector + BM25 + PageRank), and pluggable LLM backends.

Why GraphRAG?

	Traditional RAG	GraphRAG
Knowledge storage	Flat vector chunks	Interconnected knowledge graph
Context	Semantic similarity only	Relationships + entities + hierarchy
Multi-hop reasoning	Limited	Natural via graph traversal
Token efficiency	Baseline	Up to ~6000× reduction (LightRAG-style)
Accuracy	Good	~15% better on empirical benchmarks

Workspace

oxidizedRAG is a Cargo workspace with five crates:

Crate	Purpose
graphrag-core	Core library — graph construction, retrieval, entity extraction, embeddings, pipeline. Native and WASM.
graphrag-server	REST API binary (Actix-web + Apistos / OpenAPI 3.0).
graphrag-cli	Terminal UI + CLI (Ratatui). Talks directly to graphrag-core.
graphrag-wasm	Browser GraphRAG (Leptos + Trunk). Runs the full pipeline in WebAssembly.
graphrag-aivcs	AIVCS integration: run tracking, content-addressed config, observability.

Features

• Three pipeline modes: semantic (LLM/neural), algorithmic (pattern-based, no LLM), hybrid (RRF fusion)
• Pluggable embeddings: HuggingFace, OpenAI, Voyage AI, Cohere, Jina, Mistral, Together AI, Ollama, ONNX
• Pluggable LLMs: Ollama, vLLM / llm-d (OpenAI-compatible), WebLLM (in-browser)
• Hybrid retrieval: vector similarity, BM25, PageRank, adaptive
• Knowledge graph: incremental updates, community detection (Leiden), HippoRAG, LightRAG
• Storage: in-memory, Qdrant, LanceDB, SurrealDB, RocksDB-backed persistent cache
• Content-hash stage caching: 5–10× speedup on repeated runs with unchanged corpus
• WebGPU acceleration in the browser build

Quickstart

CLI

cargo build --release --package graphrag_cli

# Process a document (uses an example config from config/templates/)
./target/release/graphrag_cli load my_document.txt --config my_config.toml

# Query interactively (TUI)
./target/release/graphrag_cli --config my_config.toml tui

# Or query directly
./target/release/graphrag_cli --config my_config.toml query "What are the main themes?"

See graphrag-cli/README.md and graphrag-cli/USER_GUIDE.md.

Server

# With Qdrant
docker compose -f graphrag-server/docker-compose.yml up -d
cargo run --bin graphrag-server --features qdrant

# Without external deps (in-memory)
cargo run --bin graphrag-server --no-default-features

API: http://localhost:8080 — OpenAPI spec at /openapi.json. See graphrag-server/README.md.

Browser (WASM)

rustup target add wasm32-unknown-unknown
cargo install trunk

cd graphrag-wasm
trunk serve  # http://localhost:8080

See graphrag-wasm/README.md and graphrag-wasm/QUICK_START.md.

Library

[dependencies]
graphrag-core = { git = "https://github.com/stevedores-org/oxidizedRAG", branch = "develop" }
tokio = { version = "1", features = ["full"] }
anyhow = "1"

use graphrag_core::embeddings::api_providers::HttpEmbeddingProvider;
use graphrag_core::embeddings::EmbeddingProvider;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let api_key = std::env::var("OPENAI_API_KEY")?;

    let provider = HttpEmbeddingProvider::openai(
        api_key,
        "text-embedding-3-small".to_string(),
    );

    let v = provider.embed("Your text here").await?;
    println!("dim = {}", v.len()); // 1536 for text-embedding-3-small
    Ok(())
}

HttpEmbeddingProvider has matching constructors for OpenAI, Voyage AI, Cohere, Jina AI, Mistral, Together AI — swap ::openai for whichever provider's API key you have. Local HuggingFace / ONNX inference (features = ["neural-embeddings"]) currently returns placeholder vectors and is tracked in #167; use one of the HTTP providers above until that lands.

Configuration

oxidizedRAG is configuration-driven — the same binary can run as a fast pattern-based pipeline (<10 ms entity extraction, no LLM) or a high-accuracy LLM pipeline, controlled entirely by TOML. See config/JSON5_CONFIG_GUIDE.md and the templates in config/templates/.

Documentation

• Architecture deep-dive — the 7-stage pipeline, end to end
• CI architecture — pre-commit, Nix, local-ci, GitHub Actions
• Agents guide (AGENTS.md) — context for AI coding assistants
• CLAUDE.md — Claude Code-specific notes for this repo

Development

just fmt-check     # cargo fmt --all -- --check
just clippy        # cargo clippy --workspace --all-targets -- -D warnings
just test          # cargo test --workspace
just ci            # full local CI

# Reproducible Nix env (preferred)
nix develop
just flake-check

rustfmt.toml uses nightly-only options; run cargo +nightly fmt --all for the canonical format. The CI uses nightly rustfmt; stable cargo fmt may warn on unstable options.

Status

Active development. PRs land on develop; develop → main for releases. See open issues and PRs.

License

MIT — see individual crate Cargo.toml for details.