edgequake

# 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. ```bash 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`). > **Ports:** Docker quickstart maps the Web UI to **http://localhost:3000**. Local `make dev` defaults to **http://localhost:3010** (avoids collisions with other stacks). Alternative: docker compose directly ```bash 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):** ```bash # 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 (Docker quickstart) | URL (`make dev`) | |---------|-------------------------|------------------| | Web UI | http://localhost:3000 | http://localhost:3010 | | REST API | http://localhost:8080 | http://localhost:8090* | | Swagger | http://localhost:8080/swagger-ui | http://localhost:8090/swagger-ui* | | Health | http://localhost:8080/health | http://localhost:8090/health* | \*Local `make dev` picks free ports starting at **8090** (API) / **3010** (UI); see `make status` for the bound ports. **Verify:** ```bash curl -s http://localhost:8080/health | python3 -m json.tool ``` > Pin a version: `EDGEQUAKE_VERSION=0.26.5 sh quickstart.sh` ### What's new in 0.26.4 Patch: SPEC-144 Next.js **16.3.3** Active LTS (August Critical RCEs) + proxy SSOT; SPEC-140/141 list completeness; SPEC-122 bulk-ingest honesty; health poll off by default; distroless API. **No new migration** (schema stays **149**). Pull GHCR `0.26.4` for the patched frontend image. Upgrade: **[upgrade-to-0.26.4.md](docs/operations/upgrade-to-0.26.4.md)** · changelog: [CHANGELOG.md](CHANGELOG.md). ### What's new in 0.26.3 Patch: SPEC-139 mid-cutover engine (iw2 21000, W3 coverage-sum, KV remainder after 119-before-122); Langfuse 3.22/3.225 isolated OTLP stacks. **No new migration** (schema stays **149**). Pull GHCR `0.26.3` — do not stay on `0.26.1` for leftover DROP OLD copy. Upgrade: **[upgrade-to-0.26.3.md](docs/operations/upgrade-to-0.26.3.md)** · changelog: [CHANGELOG.md](CHANGELOG.md). ### What's new in 0.26.2 Patch: Langfuse 3.1.x ingestion fallback (SPEC-124), Kubernetes Helm/kind (SPEC-138), SSE/conversation restore, workspace `include_stats`. **No new migration** (schema stays **149**). Pull GHCR `0.26.2`. Upgrade: **[upgrade-to-0.26.2.md](docs/operations/upgrade-to-0.26.2.md)** · changelog: [CHANGELOG.md](CHANGELOG.md). ### What's new in 0.26.1 Patch: SPEC-137 migrate honesty (`--drop-confirm` alias, unknown apply flags fail-closed, classified DROP abort hints). **No new migration** (schema stays **149**). Pull GHCR `0.26.1` — the `0.26.0` image still has the old CLI. Upgrade: **[upgrade-to-0.26.1.md](docs/operations/upgrade-to-0.26.1.md)** · leftover 091: [upgrade-to-0.26.0.md](docs/operations/upgrade-to-0.26.0.md) · changelog: [CHANGELOG.md](CHANGELOG.md). ### What's new in 0.26.0 Minor: PDF pack-to-budget (SPEC-135), manuscript page-as-unit convert (SPEC-134), Langfuse dev sibling (SPEC-124), wizard persist honesty (SPEC-101), and reliability (#377, #383–#386 + mig **149**). Crates.io: `edgequake-llm` **0.10.8**, `edgequake-pdf2md` **0.9.11**, `edgequake-sdk` **0.4.0**. Upgrade: **[upgrade-to-0.26.0.md](docs/operations/upgrade-to-0.26.0.md)** · changelog: [CHANGELOG.md](CHANGELOG.md). ### What's new in 0.25.0 Minor: Langfuse OTLP/HTTP (SPEC-124), structure-aware markdown pack (SPEC-125), provider KV / prompt cache (SPEC-126), PDF layout overlay (SPEC-128 + mig **148**), omit-temperature / Responses API (SPEC-131 / #379), multi-PDF admit honesty (#378), document status CHECK SSOT (#381), fleet-mirror UUID + target-`->` parse (#380 / SPEC-133). Crates.io deps: `edgequake-llm` **0.10.8**, `edgequake-pdf2md` **0.9.11**. Upgrade: **[upgrade-to-0.25.0.md](docs/operations/upgrade-to-0.25.0.md)** · changelog: [CHANGELOG.md](CHANGELOG.md). ### What's new in 0.24.0 #### Database migration (read this first) **The API never migrates the database.** Schema changes are an explicit operator step. | Situation | What to run | |-----------|-------------| | **Fresh install** | `edgequake migrate` once, then start the API (`make dev` does this for you) | | **Upgrade from ≤ v0.22.0** | Backup → `migrate dry-run` → `migrate` → `migrate --confirm-drop` → `migrate` (applies deferred **142**) → start API | | **Server exits 78** | Schema behind or newer than the binary — run migrate, then restart | Irreversible drops (**125** KV, **126**/**131** vectors) need `--confirm-drop` and a backup; rollback after that is restore-only. Migration **142** asserts empty leftovers (aborts if rows remain; deferred while residue exists). Full plain-language guide: **[Migrate to v0.23.0+](docs/operations/migrate-to-0.23.md)** · production soak: [SPEC-091 upgrade runbook](docs/operations/spec091-upgrade-from-v0.22.0.md). #### Highlights - **SPEC-104 production data-layer monitors** — StorageInspector uses `workspace_id` + `PostgresConfig` AGE graph SSOT; no `42703` / `42P01` probes; INV-03 dual-read; tenant create **201/200/409**. - **SPEC-105 legacy cutover assert** — census SSOT; unknown `VECTOR_BACKEND` → typed; migration **142**; mid-upgrade deferral so expandables soft-exit while residue remains. - **Schema** — migrations through **142** (0.23.0 stopped at **141**). Also in **0.23.0**: SPEC-091 relational cutover (106–141), LD-15 boot gate, SPEC-094 parse API, SPEC-103 LLM cache, wizard/UX. **0.22.0**: SPEC-090 multi-pool + migrate CLI. ### Performance testing Publish Acc is **medical-mid n=200** (`make bench`) — not smoke n=40. Latest publish pack (`medical-mid-20260815T110218Z`): Acc EQ **0.792** vs LR **0.786** (Δ Acc 95% CI **[-0.022, +0.034]** — statistical tie; L2 promote gates unmet — do **not** claim EQ beats LightRAG / Acc Beat). Fair cold latency ratio **1.02×** (`C1COLD_v1`). Smoke peers remain CI/ablation references only. Required local pre-tag gate: see [Release & CD § SPEC-001](docs/operations/release-and-cd.md#spec-001-lightrag-acc-before-tag). - [EQ vs LightRAG Acc Bench](docs/comparisons/eq-vs-lightrag-acc-bench.md) — measured scorecard - [BUSINESS_REPORT.md](specs/001-benchmark/e2e/artifacts/publish/latest/BUSINESS_REPORT.md) — regenerated by `make bench` (n=200) - [EXEC_SUMMARY.txt](specs/001-benchmark/e2e/artifacts/publish/latest/EXEC_SUMMARY.txt) - [peers.json](specs/001-benchmark/e2e/artifacts/peers.json) - Protocol: [000-index](specs/001-benchmark/000-index.md) · [001-first-principles](specs/001-benchmark/001-first-principles.md) - Context: [055](specs/001-benchmark/001-edgquake-improvements/055-post-acc-ceiling-first-principles.md) · [063](specs/001-benchmark/001-edgquake-improvements/063-why-lightrag-faster-cache-fairness.md) ### 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:** ```bash 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 [email protected] # 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 (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](docs/operations/runtime-auth-hardening.md) for master API keys, OIDC, and troubleshooting ([GitHub #288](https://github.com/raphaelmansuy/edgequake/issues/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](docs/ingestion-cancel-and-fairness.md). --- ## First Steps **Upload a document** (PDF, TXT, MD): ```bash curl -X POST http://localhost:8080/api/v1/documents/upload \ -F "[email protected]" ``` Or drag-and-drop in the Web UI at http://localhost:3000 (Docker) or http://localhost:3010 (`make dev`). **Query the knowledge graph:** ```bash 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](https://arxiv.org/abs/2410.05779) 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 (