• EQ vs LightRAG Acc Bench — measured scorecard
• BUSINESS_REPORT.md — regenerated by make bench (n=200)
• EXEC_SUMMARY.txt
• peers.json
• Protocol: 000-index · 001-first-principles
• Context: 055 · 063

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 EDGEQUAKEDEVMODE=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 EDGEQUAKEDEVMODE=false
export EDGEQUAKEAUTHENABLED=true
export EDGEQUAKEBOOTSTRAPADMIN_USERNAME=admin
export EDGEQUAKEBOOTSTRAPADMIN_PASSWORD='ChangeMe123!'   # min 8 chars, mixed complexity
export EDGEQUAKEBOOTSTRAPADMIN_EMAIL=admin@example.com   # optional
export NEXTPUBLICAUTH_ENABLED=true
export NEXTPUBLICDISABLEDEMOLOGIN=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 (Docker quickstart) or http://localhost:3010/login (make dev).

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).

Ingestion cancel & restart (v0.19+)

From v0.19, cancel and restart are durable (SPEC-057): UI shows Stopping… until terminal Cancelled (not Failed); Pending tasks survive process restart via Postgres claim/lease (FOR UPDATE SKIP LOCKED). See Ingestion cancel and fairness.

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 (Docker) or http://localhost:3010 (make dev).

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 (EDGEQUAKEGRAPHWALK=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 (EDGEQUAKEFAITHFULNESSJUDGE)
• ACC CI gate — make spec046-acc writes a deterministic AccReport JSON (no API key)

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:

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

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

# Pin full stack to this release
EDGEQUAKE_VERSION=0.24.3 docker compose -f docker-compose.quickstart.yml up -d
Pin PostgreSQL major (optional; default tag follows EDGEQUAKE_VERSION → PG18)
EDGEQUAKEVERSION=0.24.3 EDGEQUAKEPOSTGRES_TAG=0.21.0-pg16 \
  docker compose -f docker-compose.quickstart.yml up -d

cd edgequake/docker && docker compose up -d

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

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 edgequakewebui/.env.local.example edgequakewebui/.env.local
make dev                        # Start full stack (PostgreSQL + Backend + Frontend)
Web UI defaults to http://localhost:3010 — confirm with: make status

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.19+)

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
SPEC-001 LightRAG Acc (local mandatory before tag — not in CI / release_gates.sh):
make bench001-doctor
make bench                      # EQ vs LightRAG Acc n=200 + publish/latest
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 | | SPEC-001 LightRAG Acc | EQ vs LightRAG GraphRAG-Bench Acc (n=200) | Local only (make bench) | | 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