feat(eval,training): deterministic evaluation harness, training pipeline, and fine-tuning experiment (Milestones 2–3C)

.gitignore

@@ -20,3 +20,22 @@ cortex.toml
 .DS_Store
 .idea/
 .vscode/
+
+# Training raw data and checkpoints (do not commit)
+training/raw/
+training/*.jsonl
+training/checkpoints/
+training/models/
+
+# Frontend build artefacts. frontend/dist regenerated by npm run build; node_modules by npm install. Source only under frontend/src.
+frontend/dist/
+frontend/**/node_modules/
+frontend/**/*.tsbuildinfo
+frontend/.vite/
+
+# Root checkpoints (legacy path, use training/checkpoints)
+checkpoints/
+
+# Personal learnings — local only, never pushed
+learnings/
+.venv-mesh/

README.md

@@ -106,8 +106,9 @@ cd cortex
 # 2. Install editable package
 pip install -e .
 
-# 3. Query sample vault using offline deterministic embedder
-cortex query "What are the notes on pectin and fermentation?" --offline
+# 3. Search sample vault (offline, no model needed) — or synthesize an answer
+cortex search "pectin and fermentation" --vault examples/sample-vault --offline
+# cortex ask "What are the notes on pectin and fermentation?" --vault examples/sample-vault --offline
 ```
 
 ---
@@ -155,10 +156,37 @@ cortex status                         # index size, thermal state
 cortex providers                      # who may see private content, and why
 cortex graph --note "Retrieval.md"    # inspect wikilinks
 cortex watch                          # run continuously
+cortex serve                          # local web app + voice + chat UI
 ```
 
 Everything works without a model configured — pass `--offline` to use a deterministic hashing embedder. Useful for trying the pipeline before pulling gigabytes.
 
+### Talk to it in the browser — `cortex serve`
+
+A Vite-built React app runs alongside the Python backend on one port. Streaming
+chat, citations, voice input (browser Web Speech API), TTS read-aloud, a vault
+search sidebar and a memory-folder browser — all in one window, all local.
+
+```bash
+uv pip install -e ".[server]"            # adds fastapi + uvicorn
+cd frontend && npm install && npm run build  # one-time, builds the SPA
+cd .. && cortex serve                    # opens http://127.0.0.1:7331
+```
+
+The mobile layout collapses the left rail into a slide-in drawer and pins a
+tab bar to the bottom of the viewport; on desktop the sidebar stays put.
+
+**Voice.** Hold the mic button (or type) and the browser's Web Speech API
+transcribes in real time. A "Read aloud" button on each assistant message
+plays it back via the browser's `SpeechSynthesis` with the voice you pick in
+Settings. Both rely on browser-native engines; for fully local STT/TTS, route
+audio to a local Whisper / Piper daemon on the server and we'll hook them up.
+
+**Privacy, in the UI.** Every assistant message carries a provider chip
+(`groq · no-train`, `nvidia · no-train`, `openrouter · zdr`, etc.) so you can
+see at a glance where each answer came from. The "Local only" toggle on the
+composer forces the request to stay on-device.
+
 ### Connect it to Antigravity
 
 Cortex speaks MCP, so Antigravity can query your notes directly. Add to `~/.gemini/antigravity-cli/mcp_config.json`:
@@ -331,7 +359,7 @@ uv pip install -e ".[dev,all]"
 make check      # ruff + mypy --strict + pytest
 ```
 
-465 tests, mypy strict, zero lint warnings. The privacy gate is tested as a security boundary — including the subtle leak where a preferred provider fails and a naive chain falls through to a training one.
+The privacy gate is tested as a security boundary — including the subtle leak where a preferred provider fails and a naive chain falls through to a training one. The HTTP surface (`src/cortex/server/`) is covered by `tests/test_server.py` using httpx against the ASGI app directly, so the chat SSE event sequence is asserted in CI.
 
 Architecture decisions and their tradeoffs are recorded in [`docs/adr/`](docs/adr/).
 

cortex.example.toml

@@ -65,18 +65,58 @@ critical_speed_limit = 60
 min_battery_for_backfill = 30
 sample_interval = 10.0
 
+[serve]
+# Settings for `cortex serve` -- the local web app (chat + voice + vault view).
+# Defaults assume you only ever reach it from the same machine; bind 0.0.0.0
+# only if you actually want other devices on the LAN talking to it, and then
+# only on a trusted network. There is no auth -- this is a single-user tool.
+host = "127.0.0.1"
+port = 7331
+open_browser = true
+# cors_origins = ["http://localhost:7331", "http://localhost:5173"]  # add origins here
+
 # Providers patch the shipped defaults -- name an existing one to override
 # single fields, or give base_url + model to add a new endpoint.
 #
+# Shipped chain (priority is "lower sorts earlier"):
+#   * ollama    -- local qwen3:4b. Hot path; ~no remote latency when the
+#                 model is already resident. On Apple Silicon without the
+#                 Metal JIT hang fix (``OLLAMA_NUM_GPU=0``), this is
+#                 CPU-only -- still very fast for short completions.
+#   * groq      -- llama-3.3-70b-versatile on the LPU. ~350 tok/s. Best
+#                 quality-per-second at this tier; default for synthesis
+#                 that doesn't fit the local context window.
+#   * nvidia    -- Llama-3.3-70B-Instruct on NVIDIA NIM. Overflow when
+#                 Groq is rate-limited; same capability, slower.
+#   * openrouter -- llama-3.1-8b-instruct with the ZDR contract enforced
+#                 on the wire. Pinned (not ``openrouter/free``) so the
+#                 model identifier survives the weekly free roster
+#                 rotation. ``meta-llama/*`` is one of the few model
+#                 families consistently served by ZDR-endpoint providers
+#                 on the lower credit tiers.
+#
+# On a fresh install, set the OPENROUTER ZDR contract before sending
+# private notes through it:
+#
 # [[providers]]
 # name = "openrouter"
 # zdr_enabled = true      # ONLY after enabling zero-data-retention on your account
 #
+# To upgrade local hot-path capacity for a beefier machine, swap
+# the ollama model here without touching the shipped defaults:
+#
+# [[providers]]
+# name = "ollama"
+# model = "qwen3:8b"
+# priority = 0
+#
+# Adding a new endpoint (e.g. Cerebras) follows the same shape -- name
+# anything not in the shipped chain and we append it:
+#
 # [[providers]]
-# name = "cerebras"
 # base_url = "https://api.cerebras.ai/v1"
-# model = "llama3.1-8b"
+# model = "llama-3.3-70b"
 # policy = "no_train"
 # api_key_env = "CEREBRAS_API_KEY"
-# tpd = 1000000
+# rpm = 30
 # priority = 15