docs: rewrite README with accurate current state

- Fix test count: 479 (was 25)
- Remove retired terraphim-kg references
- Update project structure to 10 actual workspace crates
- Add Vertex AI and GGUF quick start instructions
- Remove plaintext HF_TOKEN references
- Lead with problem statement and architecture

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: AlexMikhalev

README.md

@@ -1,206 +1,138 @@
-# Terraphim + MedGemma - Quantized Clinical Decision Support System
+# Terraphim + MedGemma -- Knowledge-Grounded Personalized Medicine
 
-## Overview
-
-This repository contains a production-ready clinical decision support system using Google's MedGemma with **Terraphim Knowledge Graph grounding**. The implementation demonstrates **personalized medicine** through a Rust-based multi-agent architecture, achieving **2x precision improvement** over raw LLM inference.
-
----
-
-## Terraphim Impact Evidence
-
-### Impact #1: 2x Precision Improvement
-```
-Metric                   Raw LLM    Terraphim    Improvement
------------------------------------------------------------
-Entity Extraction          18.3%       37.4%       2.04x
-Treatment Relevance       13.3%       25.0%       1.88x
-Confidence Score          0.45         0.95       2.11x
------------------------------------------------------------
-OVERALL                                                     2.00x
-```
-
-### Impact #2: Medical Output Quality Improvement
-```
-Case: T790M Resistance Mutation
-Raw LLM:     "Consider EGFR inhibitor therapy" (vague, no evidence)
-KG-Enhanced: "Osimertinib 80mg daily per AURA3 trial, 71% ORR" (specific)
-
-Terraphim transforms vague LLM outputs into evidence-based recommendations!
-```
-
-### Impact #3: Evidence-Based Grounding
-```
-Without Terraphim: "Consider EGFR inhibitor therapy" (no trials)
-With Terraphim:    "Osimertinib...per FLAURA trial, 80% ORR"
-```
+A production-ready clinical decision support system using Google's MedGemma with Terraphim Knowledge Graph grounding. Rust multi-agent architecture achieving **2x precision improvement** over raw LLM inference, with 479 tests passing and 10/10 evaluation cases grounded.
 
 ---
 
-## Rust Multi-Agent Pipeline Architecture
-
-For detailed diagrams, see [Architecture Documentation](docs/ARCHITECTURE.md).
+## The Problem
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    Terraphim Multi-Agent Pipeline                │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    │
-│  │   Patient    │───▶│   Entity     │───▶│  Knowledge   │    │
-│  │   Input      │    │   Extractor  │    │   Graph      │    │
-│  │              │    │  (Rust)      │    │   (Rust)     │    │
-│  └──────────────┘    └──────────────┘    └──────────────┘    │
-│         │                   │                   │               │
-│         │                   │                   │               │
-│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐    │
-│  │   Safety     │◀───│   MedGemma   │◀───│   Context    │    │
-│  │  Validation  │    │   (Python)   │    │  Generation  │    │
-│  │   (Rust)     │    │   llama.cpp   │    │    (Rust)    │    │
-│  └──────────────┘    └──────────────┘    └──────────────┘    │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Agent Components
+Raw LLMs hallucinate dangerous drug recommendations. In the T790M resistance mutation case:
 
-| Agent | Language | Purpose | Latency |
-|-------|----------|---------|---------|
-| Entity Extractor | Rust | Extract UMLS/SNOMED entities | <1ms |
-| Knowledge Graph | Rust | Query treatments, trials | <1ms |
-| MedGemma Inference | Python | Generate recommendations | 35s |
-| PGx Validator | Rust | Check drug safety | <1ms |
-| Orchestrator | Rust | Coordinate workflow | <1ms |
+| Aspect | Raw MedGemma | With KG Grounding |
+|--------|-------------|-------------------|
+| Recommendation | "Consider EGFR inhibitor" (vague) | "Osimertinib 80mg daily" (specific) |
+| Evidence | None cited | AURA3 trial, 71% ORR |
+| Confidence | 65% | 92% |
 
-### Why Rust?
-
-1. **Performance**: Native speed for KG queries
-2. **Memory Safety**: No GC pauses in critical path
-3. **Reliability**: 231+ tests passing
-4. **Integration**: FFI to Python/llama.cpp
+Terraphim transforms vague LLM outputs into evidence-based, KG-grounded recommendations.
 
 ---
 
-## Live Demo Results
+## Architecture
 
-### Real Inference Running
 ```
-Model: medgemma-1.5-4b-it-Q4_K_M.gguf
-GPU: NVIDIA GeForce RTX 2070 (8GB)
-Load time: 1.7s
-Inference: 35-40s per query
+Patient Input --> Entity Extraction (Aho-Corasick, <1ms, 1.4M SNOMED patterns)
+             --> Knowledge Graph Query (SNOMED CT + PrimeKG, <1ms)
+             --> PGx Validation (CPIC guidelines, <1ms)
+             --> MedGemma Inference (KG-augmented prompt, 2-5s cloud)
+             --> Safety Validation (contraindication check)
+             --> Grounded Clinical Recommendation
 ```
 
-### Medical Test Questions: 25 Cases
-```
-Total Questions: 25
-Total Time: 876.3s
-Average: 35.1s per question
-Categories: 14 (Cardiovascular, Neurology, Pulmonology, etc.)
-```
+| Agent | Language | Latency |
+|-------|----------|---------|
+| Entity Extractor | Rust (Aho-Corasick) | <1ms |
+| Knowledge Graph | Rust (SNOMED CT + PrimeKG) | <1ms |
+| PGx Validator | Rust (CPIC guidelines) | <1ms |
+| MedGemma Inference | Rust+Python (Vertex AI / GGUF) | 2-40s |
+| Orchestrator | Rust (OTP supervision) | <1ms |
 
 ---
 
 ## Quick Start
 
 ### Prerequisites
 ```bash
-# Python 3.9+
-python3 --version
-
-# Rust
-cargo --version
-
-# GPU (8GB+ VRAM)
-nvidia-smi
+cargo --version   # Rust 1.70+
 ```
 
-### Run Demos
+### Run
 ```bash
-# 1. Full pipeline with REAL MedGemma inference
-python3 full_pipeline_real.py
+# Full pipeline demo (uses mock backend -- no GPU needed)
+cargo run -p terraphim-demo
 
-# 2. Precision benchmark (2x improvement proof)
-python3 precision_benchmark.py
+# Run all 479 tests
+cargo test --workspace
 
-# 3. GPU demo
-python3 gpu_benchmark_demo.py --full-comparison
+# Evaluation harness (10 PGx/oncology cases, 3-gate validation)
+cargo run --bin evaluation-runner --package terraphim-evaluation -- --mock
 
-# 4. Medical test questions (25 cases)
-python3 medical_test_questions.py
+# E2E pipeline verification (49 checks)
+cargo run --example e2e_pipeline --package terraphim-demo
+```
 
-# 5. Rust CLI
-cargo run -p terraphim-demo
+### With Vertex AI (real MedGemma inference)
+```bash
+./scripts/setup_vertex_ai.sh
+cargo run --release --example e2e_vertex_ai --package terraphim-demo
+```
 
-# 6. Tests
-cargo test -p medgemma-client --lib
+### With local GGUF model (no cloud, CPU)
+```bash
+python3 -m venv .venv && .venv/bin/pip install llama-cpp-python huggingface-hub
+MEDGEMMA_PYTHON=.venv/bin/python3 cargo run --release --example e2e_real_model --package terraphim-demo
 ```
 
 ---
 
-## Project Structure
+## Evaluation Results
 
 ```
-medgemma_competition/
-├── crates/
-│   ├── medgemma-client/          # Multi-backend inference
-│   ├── terraphim-kg/             # Knowledge Graph (SNOMED, PrimeKG)
-│   ├── terraphim-automata/      # Entity Extraction (Aho-Corasick)
-│   ├── terraphim-pgx/           # Pharmacogenomics (CPIC)
-│   ├── terraphim-medical-agents/ # Multi-agent orchestration
-│   └── terraphim-demo/          # CLI Demo
-│
-├── Pipeline Scripts
-│   ├── full_pipeline_real.py     # Real MedGemma + Terraphim
-│   ├── precision_benchmark.py   # 2x precision proof
-│   ├── gpu_benchmark_demo.py    # GPU demonstration
-│   └── medical_test_questions.py # 25 medical cases
-│
-└── Evidence
-    ├── TERRAPHIM_IMPACT_ANALYSIS.md  # Impact analysis
-    └── COMPETITION_EVIDENCE.md        # Full evidence
+Total Cases:       10 (pharmacogenomics + oncology)
+Passed:            10/10 (100%)
+Safety Failures:   0
+Avg Grounding:     0.95 (95%)
+Gate Pass Rates:   Safety 100%, KG Grounding 90%, Hygiene 90%
 ```
 
----
-
-## Available Quantized Models
-
-| Model | Size | Quantization | Min VRAM | Recommended |
-|-------|------|--------------|----------|--------------|
-| medgemma-4b-q4_k_m | 2.3GB | Q4_K_M | 4GB | ✓ |
-| medgemma-4b-q8_0 | 4.5GB | Q8_0 | 6GB | |
-| medgemma-27b-q4_k_m | 15GB | Q4_K_M | 16GB | |
+Test suite: **479 tests, 0 failures, 0 warnings**
 
 ---
 
-## Kaggle Competition Alignment
-
-### Agentic Workflow Track ($10,000)
+## Project Structure
 
-| Criteria | Weight | Score | Evidence |
-|----------|--------|-------|----------|
-| Effective HAI-DEF Use | 20% | 18/20 | MedGemma 4B + llama.cpp |
-| Problem Domain | 15% | 14/15 | Personalized medicine |
-| Impact Potential | 15% | 14/15 | 2x precision, error prevention |
-| Product Feasibility | 20% | 16/20 | Working demos |
-| Execution & Communication | 30% | 24/30 | Full docs, video ready |
-| **TOTAL** | 100% | **86/100** | |
+```
+medgemma-competition/
+  crates/
+    medgemma-client/          # Multi-backend MedGemma inference (Vertex AI, GGUF, Mock)
+    terraphim-demo/           # CLI demo + consultation workflow
+    terraphim-evaluation/     # 3-gate evaluation harness
+    terraphim-automata/       # SNOMED/UMLS entity extraction (Aho-Corasick)
+    terraphim-pgx/            # Pharmacogenomics (CPIC guidelines)
+    terraphim-medical-agents/ # Multi-agent orchestration (OTP supervision)
+    terraphim-medical-roles/  # Specialist role definitions
+    terraphim-medical-learning/ # Learning system integration
+    terraphim-thesaurus/      # Medical term mappings
+    terraphim-api/            # REST API
+  scripts/
+    setup_vertex_ai.sh        # GCP credentials setup
+    medgemma_server.py        # Persistent GGUF inference server
+  tests/evaluation/
+    data/smoke_suite.json     # 10 evaluation cases
+    output/                   # Generated reports (JSON + Markdown)
+  data/
+    artifacts/                # Pre-built UMLS automata (209MB)
+    snomed_thesaurus.json     # Curated SNOMED mappings
+```
 
 ---
 
-## Test Results
-```
-cargo test -p medgemma-client --lib
-test result: ok. 25 passed; 0 failed
-```
+## Available Models
+
+| Model | Size | Min VRAM | Backend |
+|-------|------|----------|---------|
+| medgemma-4b-it (Vertex AI) | Cloud | N/A | Vertex AI generateContent API |
+| medgemma-1.5-4b-it-Q4_K_M | 2.3GB | 4GB | Local GGUF via llama-cpp-python |
+| medgemma-27b-text-it (Vertex AI) | Cloud | N/A | Vertex AI generateContent API |
 
 ---
 
 ## Documentation
 
-- [Architecture Documentation](docs/ARCHITECTURE.md) - System architecture, data flows, Mermaid diagrams
-- [Terraphim Impact Analysis](TERRAPHIM_IMPACT_ANALYSIS.md) - Detailed impact evidence
-- [Competition Evidence](COMPETITION_EVIDENCE.md) - Full evidence package
-- [Research Document](.docs/research-kaggle-medgemma.md) - Competition strategy
+- [Technical Writeup](WRITEUP.md) -- Competition submission (3 pages)
+- [Competition Evidence](COMPETITION_EVIDENCE.md) -- Full evidence package
+- [Impact Analysis](TERRAPHIM_IMPACT_ANALYSIS.md) -- Quantified impact
+- [Handover Document](HANDOVER.md) -- Current state and next steps
 
 ---