EdgeQuake

High-Performance Graph-RAG Framework in Rust
Transform documents into intelligent knowledge graphs for superior retrieval and generation

---

Quick Start

No Rust, no Node.js, no build. Just Docker.

curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/quickstart.sh | sh

The wizard guides you through provider selection (OpenAI / Ollama), model choice, and starts the full stack.
Open http://localhost:3000 and you're in — no login required (quickstart runs with open API via EDGEQUAKE_DEV_MODE=true).

Alternative: docker compose directly

curl -fsSL https://raw.githubusercontent.com/raphaelmansuy/edgequake/edgequake-main/docker-compose.quickstart.yml \
  -o docker-compose.quickstart.yml
docker compose -f docker-compose.quickstart.yml up -d

Headless / CI (no interactive terminal):

# OpenAI
EDGEQUAKE_LLM_PROVIDER=openai \
  OPENAI_API_KEY=sk-... \
  docker compose -f docker-compose.quickstart.yml up -d

# Ollama (on host)
EDGEQUAKE_LLM_PROVIDER=ollama \
  EDGEQUAKE_LLM_MODEL=gemma4:e4b \
  EDGEQUAKE_EMBEDDING_PROVIDER=ollama \
  OLLAMA_EMBEDDING_MODEL=embeddinggemma \
  docker compose -f docker-compose.quickstart.yml up -d

Service	URL
Web UI	http://localhost:3000
REST API	http://localhost:8080
Swagger	http://localhost:8080/swagger-ui
Health	http://localhost:8080/health

Verify:

curl -s http://localhost:8080/health | python3 -m json.tool

Pin a version: EDGEQUAKE_VERSION=0.16.0 sh quickstart.sh

Authentication (v0.15+)

From v0.15, the API enables authentication secure by default (SPEC-027). Identity lives in PostgreSQL; login requires at least one user with a real password hash.

Scenario	What to set
Quickstart / demo	Nothing — compose defaults to EDGEQUAKE_DEV_MODE=true (open API, no login)
Production with login	Bootstrap admin before first API start (see below)
Local dev from source	make dev (auth off) or make dev-auth (auth on + demo login hidden)

Enable login on Docker / production:

export EDGEQUAKE_DEV_MODE=false
export EDGEQUAKE_AUTH_ENABLED=true
export EDGEQUAKE_BOOTSTRAP_ADMIN_USERNAME=admin
export EDGEQUAKE_BOOTSTRAP_ADMIN_PASSWORD='ChangeMe123!'   # min 8 chars, mixed complexity
export EDGEQUAKE_BOOTSTRAP_ADMIN_EMAIL=admin@example.com   # optional
export NEXT_PUBLIC_AUTH_ENABLED=true
export NEXT_PUBLIC_DISABLE_DEMO_LOGIN=true
docker compose -f docker-compose.quickstart.yml up -d

The API creates the bootstrap admin on startup. Sign in at http://localhost:3000/login.

Upgrades from pre-v0.15: legacy KV auth:user:* records are imported into PostgreSQL automatically when present.

See Runtime Auth Hardening for master API keys, OIDC, and troubleshooting (GitHub #288).

---

First Steps

Upload a document (PDF, TXT, MD):

curl -X POST http://localhost:8080/api/v1/documents/upload \
  -F "file=@your-document.pdf"

Or drag-and-drop in the Web UI at http://localhost:3000.

Query the knowledge graph:

curl -X POST http://localhost:8080/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What are the main concepts?", "mode": "hybrid"}'

---

Why EdgeQuake?

Traditional RAG retrieves document chunks by vector similarity alone. This works for keyword lookups but fails on multi-hop reasoning, thematic questions, and relationship queries. Vectors capture similarity but lose structural relationships.

EdgeQuake implements the LightRAG algorithm in Rust: documents are decomposed into a knowledge graph of entities and relationships. At query time, the system traverses both the vector space and the graph structure — combining the speed of embeddings with the reasoning power of graph traversal.

Metric	EdgeQuake	Traditional RAG	Improvement
Query Latency (hybrid)	< 200ms	~1000ms	5x faster
Entity Extraction	~2-3x more	Baseline	3x
Concurrent Users	1000+	~100	10x
Memory per Document	2MB	~8MB	4x

---

Features

Knowledge Graph

• Entity Extraction — LLM-powered detection of people, organizations, locations, concepts, technologies, and products
• Relationship Mapping — Automatic identification of connections with keyword tagging
• Multi-Pass Gleaning — Second-pass extraction catches 15-25% more entities
• Community Detection — Louvain clustering groups related entities for thematic queries
• Custom Entity Types — 5 domain presets (General, Manufacturing, Healthcare, Legal, Research), up to 50 types per workspace
• Knowledge Injection — Domain glossaries, acronym definitions, and synonym mappings

Query Engine — 6 Modes

Mode	Best For	Latency
Naive	Keyword-like lookups	~100-300ms
Local	Specific entity relationships	~200-500ms
Global	Thematic / high-level questions	~300-800ms
Hybrid (default)	Balanced, comprehensive results	~400-1000ms
Mix	Weighted vector + graph blend	configurable
Bypass	Direct LLM (no RAG)	LLM-dependent

Hybrid RAG (v0.16 / SPEC-046)

Production Hybrid RAG with fail-closed ops and science-grade retrieval defaults:

• PPR-default graph walk — Personalized PageRank expands entity neighborhoods (EDGEQUAKE_GRAPH_WALK=bfs escape hatch)
• Bipartite dual-node pick — entity∪chunk adjacency for Local / Global / Mix chunk selection
• HNSW fail-closed + /ready — missing ANN index blocks traffic instead of silent degradation
• Intent-gated Mix/Hybrid arms — skip irrelevant retrieval arms; GenAI rag.retrieval spans
• Failed-chunk retry → merge — persist / list / retry extraction failures into the knowledge graph
• Faithfulness sampling — heuristic + optional LLM judge (EDGEQUAKE_FAITHFULNESS_JUDGE)
• ACC CI gate — make spec046-acc writes a deterministic AccReport JSON (no API key)

Ops runbooks: specs/046-graphrag-study/13-OPS-RUNBOOKS.md.

PDF Vision Pipeline

• Text Mode — Fast pdfium-based extraction (default, zero-config, embedded in binary)
• Vision Mode — GPT-4o, Claude, Gemini read each page as an image
• Table Reconstruction — Recovers complex tables that text parsers mangle
• Multi-Column Layout — LLM understands reading order across columns
• Automatic Fallback — Vision failures gracefully fall back to text extraction

Production Ready

• REST API — OpenAPI 3.0, SSE streaming, batch ingestion, health checks
• Multi-Tenant — Fail-closed workspace isolation for query, delete, and recovery
• Auth & Audit — Built-in authentication, authorization, and compliance logging
• PostgreSQL 16/17/18 — Triple-track support with pgvector + Apache AGE
• Multi-Arch Docker — linux/amd64 + linux/arm64, published to GHCR on every release
• MCP Integration — Expose capabilities to AI agents via Model Context Protocol
• React 19 Frontend — Real-time streaming, interactive Sigma.js graph visualization, drag-and-drop upload

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  Frontend (React 19 + TypeScript)                                   │
│  Document Upload · Query Interface · Graph Visualization · Config   │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│  REST API (Axum)                                                    │
│  /api/v1/documents · /api/v1/query · /api/v1/graph                  │
│  OpenAPI 3.0 · SSE Streaming · Health Checks                        │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
              ┌────────────────┴────────────────┐
              ▼                                 ▼
┌──────────────────────────┐   ┌────────────────────────────────────┐
│  LLM Providers           │   │  Storage                           │
│  OpenAI · Anthropic      │   │  PostgreSQL 16 / 17 / 18           │ 
│  Gemini · Mistral        │   │  ├─ pgvector (embeddings)          │
│  Ollama · LM Studio      │   │  └─ Apache AGE (knowledge graph)   │
│  xAI · Azure · VertexAI  │   │                                    │
└──────────────────────────┘   └────────────────────────────────────┘

Data flow: Document → Chunks → Entity Extraction → Knowledge Graph → Vector + Graph Storage
Query flow: Question → Graph Traversal + Vector Search → LLM → Answer with Sources

EdgeQuake is built from 11 Rust crates: edgequake-core, edgequake-storage, edgequake-api, edgequake-pipeline, edgequake-query, edgequake-pdf, edgequake-auth, edgequake-audit, edgequake-tasks, edgequake-rate-limiter, edgequake-observability. LLM providers are handled by the external edgequake-llm crate.

See Architecture Overview and LightRAG Algorithm Deep Dive.

---

Docker Deployment

Three options depending on your setup:

Option A — API Only (bring your own PostgreSQL)

docker run -d --name edgequake -p 8080:8080 \
  -e DATABASE_URL="postgres://user:pass@your-db:5432/edgequake" \
  -e EDGEQUAKE_LLM_PROVIDER=openai \
  -e OPENAI_API_KEY="sk-..." \
  ghcr.io/raphaelmansuy/edgequake:latest

Option B — Full Stack with Prebuilt Images (recommended)

cd edgequake/docker
cp .env.example .env
docker compose -f docker-compose.prebuilt.yml up -d

Service	Port	Image
API	8080	ghcr.io/raphaelmansuy/edgequake:0.16.0 (:latest)
Frontend	3000	ghcr.io/raphaelmansuy/edgequake-frontend:0.16.0 (:latest)
PostgreSQL	5432	ghcr.io/raphaelmansuy/edgequake-postgres:0.16.0 (PG18 default)

PostgreSQL major tags (multi-arch amd64 + arm64):

Tag	PostgreSQL
0.16.0 / latest / 0.16.0-pg18 / latest-pg18	PG18
0.16.0-pg17 / latest-pg17	PG17
0.16.0-pg16 / latest-pg16	PG16

# Pin full stack to this release
EDGEQUAKE_VERSION=0.16.0 docker compose -f docker-compose.quickstart.yml up -d

# Pin PostgreSQL major (optional; default tag follows EDGEQUAKE_VERSION → PG18)
EDGEQUAKE_VERSION=0.16.0 EDGEQUAKE_POSTGRES_TAG=0.16.0-pg16 \
  docker compose -f docker-compose.quickstart.yml up -d

Also works with latest-pg16 / latest-pg17 / latest-pg18.

Option C — Build from Source

cd edgequake/docker && docker compose up -d

Environment Variables

Variable	Default	Description
EDGEQUAKE_LLM_PROVIDER	ollama	openai, anthropic, gemini, mistral, ollama, azure, vertexai
EDGEQUAKE_EMBEDDING_PROVIDER	(same as LLM)	Separate embedding provider for hybrid mode
EDGEQUAKE_MODELS_CONFIG	—	Path to custom models.toml (see bundled catalog in repo)
OPENAI_API_KEY	—	Required for openai
ANTHROPIC_API_KEY	—	Required for anthropic
GEMINI_API_KEY	—	Required for Gemini Developer API (gemini provider)
GOOGLE_CLOUD_PROJECT	—	Required for Vertex AI (vertexai provider)
GOOGLE_CLOUD_REGION	us-central1	Vertex AI regional endpoint
GOOGLE_APPLICATION_CREDENTIALS	—	Service account JSON path (Vertex identity auth)
MISTRAL_API_KEY	—	Required for mistral
OLLAMA_HOST	http://host.docker.internal:11434	Ollama server URL
EDGEQUAKE_VERSION	latest	GHCR image tag
EDGEQUAKE_DEV_MODE	true (quickstart)	Open API without login — do not use in production
EDGEQUAKE_AUTH_ENABLED	false (quickstart)	Require JWT/API key on protected routes
EDGEQUAKE_BOOTSTRAP_ADMIN_USERNAME	admin	First-run admin username when auth is on
EDGEQUAKE_BOOTSTRAP_ADMIN_PASSWORD	—	First-run admin password (required for login on fresh installs)
EDGEQUAKE_MASTER_API_KEY	—	Bootstrap key for POST /api/v1/users without JWT
NEXT_PUBLIC_AUTH_ENABLED	false (quickstart)	Web UI login gate + session handling
NEXT_PUBLIC_DISABLE_DEMO_LOGIN	false	Hide “Continue without login” on the login page
EDGEQUAKE_CHUNK_TIMEOUT_SECS	180	Per-chunk LLM timeout (seconds)
EDGEQUAKE_MAX_CONCURRENT_EXTRACTIONS	16	Max parallel LLM calls
RUST_LOG	info	Log level

Vertex AI vs Gemini: gemini uses a static API key (GEMINI_API_KEY). vertexai uses OAuth2 identity (ADC or service account) — not an API key. Local setup:

gcloud auth application-default login   # not: gcloud auth login application-default
export GOOGLE_CLOUD_PROJECT=your-gcp-project
export GOOGLE_CLOUD_REGION=europe-west1   # optional; default us-central1

If ~/.edgequake/models.toml omits vertexai, point at the bundled catalog: export EDGEQUAKE_MODELS_CONFIG=edgequake/models.toml. See Configuration — Vertex AI.

---

SDKs

Language	Link
Python	sdks/python/
TypeScript	sdks/typescript/
Rust	sdks/rust/
Go, Java, Kotlin, C#, PHP, Ruby, Swift	sdks/

---

Development

For contributors building from source. Most users should use the Quick Start above.

git clone https://github.com/raphaelmansuy/edgequake.git && cd edgequake
make install
cp edgequake_webui/.env.local.example edgequake_webui/.env.local
make dev                        # Start full stack (PostgreSQL + Backend + Frontend)

cd edgequake && cargo test --workspace --lib --locked   # Unit / lib suite
cargo clippy --workspace --lib --locked -- -D warnings
cargo fmt --all -- --check
cd .. && make status && make stop

Pre-delivery checklist (v0.16+)

Run these before tagging a release. Prefer Makefile targets — they set required env vars.

# Fast local gates (mirrors CI first principles: fail cheap → compile once → proofs)
make ops17-smoke                # PG extension pin SSOT (pg16/17/18)
make spec046-acc                # SPEC-046 ACC + AccReport JSON
make release-gates              # fmt + workspace clippy + SPEC-006/018 + WebUI + version parity
make test-e2e-lint              # Playwright flake anti-patterns
# Optional UI-only (no backend): make test-e2e-ui

Gate	What it proves	CI workflow
Migration checksum	Immutable SQL lockfile	CI → migration-checksum-guard
fmt + clippy + lib tests	Code quality	CI → check / test (nextest)
SPEC-006 / SPEC-018	Resource + observability proofs	CI + Release Gates
Invariants + test floor	Reliability floor (≥870 lib)	Test Quality Gates
SPEC-046 ACC	Hybrid RAG science ACC	SPEC-046 ACC
OPS-17 pins	pgvector/AGE pin matrix	PostgreSQL Matrix Nightly

CI speed principles (see .github/workflows/ci.yml): shared cargo cache across jobs, CARGO_INCREMENTAL=0 + sparse index, --locked, cancel-in-progress, no duplicate workspace lib suite in sibling workflows, release gates skip per-crate clippy / lib re-run when CI already owns them.

See AGENTS.md for the full developer workflow and Release & CD for the release process.

---

Documentation

Category	Links
Getting Started	Installation · Quick Start
Tutorials	First RAG App · PDF Ingestion · Multi-Tenant
Architecture	Overview · Data Flow · Crate Reference
Deep Dives	LightRAG Algorithm · Query Modes · PDF Processing
Operations	Deployment · Configuration · Runtime Auth · Monitoring
API Reference	REST API · Extended API
Integrations	MCP Server · OpenWebUI · LangChain
Release & CD	Release Cycle · CHANGELOG

Full index: docs/README.md

---

Contributing

EdgeQuake uses a Specification-Driven Development approach. See CONTRIBUTING.md.

• GitHub Issues — Bug reports and feature requests
• GitHub Discussions — Questions and community help

---

Acknowledgments

EdgeQuake implements the LightRAG algorithm by Zirui Guo, Lianghao Xia, Yanhua Yu, Tu Ao, and Chao Huang. Also inspired by Microsoft's GraphRAG.

License

Apache License, Version 2.0 — see LICENSE.
Copyright 2024-2026 Raphaël MANSUY

---

Star History