Evidence-gated rearchitecture: measured retrieval/synthesis overhaul, eval harness, code-review fix-set

.env.example

@@ -0,0 +1,101 @@
+# localGPT environment configuration
+#
+# Copy to .env and edit. Every variable below is read by code; the value shown
+# after "default:" is what the code uses when the variable is unset.
+#
+#   cp .env.example .env
+#
+# For Docker use docker.env instead (it is passed with --env-file and also
+# supplies build-time values for the frontend).
+
+# ---------------------------------------------------------------------------
+# Services
+# ---------------------------------------------------------------------------
+
+# Ollama server. Read by backend/ollama_client.py and rag_system/main.py.
+# In Docker this becomes http://host.docker.internal:11434.
+# default: http://localhost:11434
+OLLAMA_HOST=http://localhost:11434
+
+# Base URL of the RAG API. backend/server.py builds /chat and /index from it.
+# In Docker compose this is http://rag-api:8001.
+# default: http://localhost:8001
+RAG_API_URL=http://localhost:8001
+
+# Browser-facing URLs, read by the Next.js frontend (src/lib/api.ts).
+# NEXT_PUBLIC_* values are inlined at build time, so change them before `npm run build`.
+# default: http://localhost:8000
+NEXT_PUBLIC_API_URL=http://localhost:8000
+# default: http://localhost:8001
+NEXT_PUBLIC_RAG_API_URL=http://localhost:8001
+
+# ---------------------------------------------------------------------------
+# Storage
+# ---------------------------------------------------------------------------
+
+# SQLite database holding sessions, messages and index metadata.
+# Set this to a shared path so the backend and the RAG API use one file.
+# default: backend/chat_data.db (local) or /app/backend/chat_data.db (Docker)
+# DB_PATH=backend/chat_data.db
+
+# LanceDB vector store. Defaults to the `storage.lancedb_uri` of the active
+# pipeline config in rag_system/main.py.
+# default: ./lancedb
+# LANCEDB_PATH=./lancedb
+
+# ---------------------------------------------------------------------------
+# Models
+# ---------------------------------------------------------------------------
+
+# Answer generation (Ollama). Options: qwen3.6:27b (high-end, ~17GB), qwen3.5:4b (light).
+# default: qwen3.5:9b
+GENERATION_MODEL=qwen3.5:9b
+
+# Routing, triage, query decomposition, contextual enrichment and verification
+# (Ollama). Light option: qwen3.5:2b.
+# default: qwen3.5:4b
+ENRICHMENT_MODEL=qwen3.5:4b
+
+# Embeddings (HuggingFace). The default is MIT-licensed, 1.2GB, 1024-dim, and
+# measured best on our gold set (eval/DECISIONS.md).
+# Option: Qwen/Qwen3-Embedding-4B for multilingual / long-context corpora.
+# Changing this requires re-indexing every existing index - the stored vectors
+# belong to the old model's vector space. localGPT records the embedding model
+# on each table and refuses to query it with a different one.
+# default: microsoft/harrier-oss-v1-0.6b
+EMBEDDING_MODEL=microsoft/harrier-oss-v1-0.6b
+
+# Reranker (HuggingFace). Only loaded when reranking is switched on - the
+# default profile ships with it OFF, because the first stage above already
+# outranks the cheap cross-encoder (eval/DECISIONS.md). When you do switch it
+# on (UI "AI reranker" toggle, or reranker.enabled in the profile) this is the
+# model that gets loaded, lazily.
+# Options: BAAI/bge-reranker-v2-m3 (low latency, only pays off with a weaker
+# embedder), answerdotai/answerai-colbert-small-v1, Qwen/Qwen3-Reranker-0.6B.
+# default: Qwen/Qwen3-Reranker-4B
+RERANKER_MODEL=Qwen/Qwen3-Reranker-4B
+
+# ---------------------------------------------------------------------------
+# Optional tuning
+# ---------------------------------------------------------------------------
+
+# Seconds the backend waits for a RAG API chat response.
+# default: 600
+# RAG_API_TIMEOUT=600
+
+# Seconds the backend waits for a RAG API indexing run.
+# default: 3600
+# RAG_API_INDEX_TIMEOUT=3600
+
+# LLM backend selector for rag_system (`ollama` or `watsonx`).
+# WatsonX additionally needs the WATSONX_* variables - see env.example.watsonx.
+# default: ollama
+# LLM_BACKEND=ollama
+
+# HuggingFace token, only needed for gated model downloads.
+# HF_TOKEN=
+
+# Ollama divides its context window (and any per-request num_ctx) across its
+# parallel slots — with 2 slots a 32k request is served as a 16k window and
+# oversized prompts are silently front-truncated. For single-user localGPT:
+# OLLAMA_NUM_PARALLEL=1

.github/ISSUE_TEMPLATE/bug_report.md

@@ -53,7 +53,7 @@ Please include relevant error messages or logs:
 
 ## 🔧 Configuration
 - Deployment method: [Docker / Direct Python]
-- Models used: [e.g. qwen3:0.6b, qwen3:8b]
+- Models used: [e.g. qwen3.5:9b, qwen3.5:4b]
 - Document types: [e.g. PDF, DOCX, TXT]
 
 ## 📎 Additional Context

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  gateway-routing:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install test dependencies
+        run: pip install requests python-dotenv
+
+      # Plain-script test (no pytest/unittest cases); exits non-zero on failure.
+      # backend/server.py guards its rag_system import, so only the two light
+      # dependencies above are needed.
+      - name: Run gateway routing test
+        run: python backend/test_gateway_routing.py

.gitignore

@@ -63,16 +63,28 @@ logs/
 
 # SQLite or other database files
 *.db
-#backend/*.db
-# backend/chat_history.db
 backend/chroma_db/
 backend/chroma_db/**
 
 # Document and user-uploaded files (PDFs, images, etc.)
 rag_system/documents/
 *.pdf
 
-# Ensure docker.env remains tracked
+# Ensure docker.env and .env.example remain tracked
 !docker.env
-!backend/chat_data.db
+!.env.example
 
+# Phase 0 evaluation harness (eval/) — rebuildable artefacts only.
+# The corpora, gold set, scripts and BASELINE.md are tracked.
+eval/.eval_indexes/
+eval/results/
+!eval/corpora/*.pdf
+# The Phase 4 cross-reference corpus lives one directory deeper.
+!eval/corpora/acquisition/*.pdf
+
+
+# local virtualenv
+.venv/
+
+# agent worktree / session state
+.claude/