Enterprise RAG Platform

This repository contains the complete implementation of a production-grade, enterprise-ready knowledge assistant. It features an end-to-end RAG (Retrieval-Augmented Generation) template that minimizes manual pipeline configuration while delivering maximum retrieval precision and grounding reliability.

Core Features

• Intelligent Query Routing: Classifies incoming questions via LLM into appropriate retrieval strategies (kb_only, web_search, knowledge_graph, kb_and_web, kb_and_kg, or all) and targets matching knowledge branches.
• Multi-Source Retrieval & Fusion: Merges internal vector/keyword search with external web search (Tavily API) and entity relationships (NetworkX in-memory Knowledge Graph) using generalized Reciprocal Rank Fusion (RRF).
• Contextual Ingestion: Situates raw document chunks in their parent document's context during ingestion for significantly higher vector match rates.
• HyDE (Hypothetical Document Embeddings): Optional query transformation module that generates candidate answers to improve dense retrieval accuracy.
• Grounded Generation & Citations: Synthesizes structured markdown responses strictly grounded on retrieved sources, complete with source-type citation badges (📄 KB Chunk, 🌐 Web Result, 🔗 KG Triplet).
• HEX / Clean Architecture: Implements a strict port-and-adapter hexagonal layout separating core business logic (packages/rag_core) from external API gateways and services (apps/).

---

Repository Layout

apps/
  api/          Backend API (FastAPI) orchestrating routes and trace logs.
  web/          Web application frontend.
  worker/       Async ingestion and indexing worker processing document queues.

packages/
  rag_core/     Shared core RAG services, pipelines, contracts, and adapters.
  shared/       Database models, database schemas, and shared enums.

config/
  Fixed enterprise template and folder structure configs.

prompts/
  System instructions for query routing, entity extraction, HyDE, and grounding.

tests/
  Unit and integration test suites covering all routing and pipeline flows.

---

Installation and setup

Use Python 3.11 or 3.12 and Node.js 22. Runtime and development dependencies are locked with hashes so CI and production images install the same artifacts:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --require-hashes -r requirements-dev.txt
Copy-Item .env.example .env

Put local overrides, including OPENAI_API_KEY and an optional OPENAI_BASE_URL, in the ignored .env.local. Never commit credentials or company documents. Apply migrations and create the local owner account once:

python -m alembic upgrade head
python scripts/seed.py
cd apps/web
npm.cmd ci
cd ..\..

For a direct development run, use separate terminals:

# API
python -m uvicorn app.main:app --app-dir apps/api --host 127.0.0.1 --port 8000 --reload

# Worker
python apps/worker/worker/main.py

# Web (from apps/web)
npm.cmd run dev

The production Compose file is the preferred reproducible deployment path. It requires the secret-managed values in .env.production and starts Postgres, Redis, Elasticsearch, Qdrant, API, worker, and the web gateway with health-gated dependencies:

docker compose --env-file .env.production -f compose.production.yml up -d --build
docker compose --env-file .env.production -f compose.production.yml ps

---

Verification & Testing

Verify code correctness and backward compatibility using the test suite. The pytest bootstrap automatically uses an isolated SQLite database when APP_ENV is not already set to test, so a plain local test run cannot modify rag.db:

python -m pytest -q --cov --cov-report=term-missing

The automated suite covers API/auth/tenancy, document ingestion, query routing, hybrid retrieval, semantic chunking, citation grounding, knowledge graph traversal, backup safety, and production controls. The configured coverage gate is 45%; the latest local run reached the gate with 56 passed. See docs/12-testing-evaluation.md for evaluation tiers and interpretation.

For the complete terminal-by-terminal startup sequence, role capability matrix, disposable user creation, API smoke test, and Docker verification, follow docs/14-local-runbook.md. The supported chat API contract is session-based: create a session at /chat/sessions, then post the question to /chat/sessions/{session_id}/messages.