Terraphim Clinical Pipeline: Graph-Based Safety Gates for MedGemma -- From Class Suggestions to Specific Drug-Dose Evidence

A production-ready clinical decision support system using Google's MedGemma with Terraphim Knowledge Graph grounding. Rust multi-agent architecture with 543+ tests passing, 18/18 evaluation cases grounded, and real GGUF inference on GPU (23.5s/case) and CPU (165s/case) -- no mock fallback.

Demo video: demo-video.mp4 (85s, 1920x1080) -- recorded with Playwright against the live API with real MedGemma GPU inference.

---

The Problem

Raw LLMs produce vague or incorrect drug recommendations. Measured A/B comparison (ab_comparison example, reproduced 2026-02-24):

The knowledge graph constrains MedGemma from vague class-level suggestions to specific, evidence-validated drug-dose recommendations.

---

Architecture

Patient Input --> Entity Extraction (Aho-Corasick LeftmostLongest, <1ms, 1.4M SNOMED patterns)
             --> Knowledge Graph Query (SNOMED CT + PrimeKG, <1ms, symbolic embeddings)
             --> PGx Validation (CPIC guidelines, <1ms)
             --> MedGemma Inference (KG-augmented prompt, 2-5s cloud / 23.5s GPU / 165s CPU)
             --> Safety Validation (KG grounding gate -- blocks ungrounded recommendations)
             --> Grounded Clinical Recommendation

---

Quick Start

Prerequisites

cargo --version   # Rust 1.70+
cp .env.template .env  # Edit with your HF_TOKEN and MEDGEMMA_GGUF_PATH

Run Tests

cargo test --workspace  # 543+ tests, ~50s

API Server with Interactive Demo

# GPU (recommended)
cargo run -p terraphim-api --features "local-gguf,cuda" --release
# CPU only
cargo run -p terraphim-api --features "local-gguf" --release

# Visit http://localhost:3001/
# Toggle to Live mode, click Run for real MedGemma inference

Playwright E2E Tests (requires API server running)

npx playwright test tests/e2e/demo-live.spec.js      # 8 functional tests
npx playwright test tests/e2e/record-demo.spec.js     # Record demo video

18-Case Evaluation Harness

cargo run -p terraphim-evaluation --features "local-gguf,cuda" --bin evaluation-runner -- \
  --cases tests/evaluation/data/smoke_suite.json \
  --output tests/evaluation/output

Full E2E Pipeline (real GGUF inference, no mock)

# GPU
cargo run --release --example e2e_pipeline --package terraphim-demo --features medgemma-client/cuda
# CPU
cargo run --release --example e2e_pipeline --package terraphim-demo

A/B Comparison (Raw MedGemma vs KG-Grounded)

cargo run --release --example ab_comparison --package terraphim-demo --features medgemma-client/cuda

---

Evaluation Results

Three runs using real MedGemma GGUF inference with no mock fallback. GPU delivers 7x speedup (RTX 2070, 99 layers offloaded). Gate score variation between runs reflects expected LLM output variance.

Test suite: 543+ unit/integration tests + 9 Playwright e2e tests, 0 failures

---

Project Structure

medgemma-competition/
  crates/
    medgemma-client/          # Multi-backend MedGemma inference (Vertex AI, GGUF, Mock)
    terraphim-api/            # Axum REST/WebSocket API server with shared LLM state
    terraphim-demo/           # CLI demo + consultation workflow + state machines
    terraphim-evaluation/     # 3-gate evaluation harness (18 cases)
    terraphim-automata/       # SNOMED/UMLS entity extraction (Aho-Corasick LeftmostLongest)
    terraphim-pgx/            # Pharmacogenomics (CPIC guidelines)
    terraphim-medical-agents/ # Multi-agent orchestration (OTP supervision, 60 state machine tests)
    terraphim-medical-roles/  # Specialist role definitions
    terraphim-medical-learning/ # Case-based learning
    terraphim-thesaurus/      # Medical term mappings
  tests/
    e2e/demo-live.spec.js     # 8 Playwright e2e tests (API, WebSocket, UI, GPU inference)
    e2e/record-demo.spec.js   # Demo video recorder (85s walkthrough)
    evaluation/
      data/smoke_suite.json   # 18 evaluation cases
      output/                 # Generated reports (JSON + Markdown)
  data/
    artifacts/                # Pre-built UMLS automata (209MB)
    snomed_thesaurus.json     # Curated SNOMED mappings
  static/
    demo.html                 # Self-contained interactive demo UI (Demo + Live modes)
    dashboard.html            # Dashboard UI
  demo-video.mp4              # 85s demo video (Playwright, real GPU inference)
  docs/demo-video/            # WebM backup of demo video
  .env.template               # Environment variable template for judges

---

Key Differentiator: Graph-Based Symbolic Embeddings

Unlike RAG systems with vector search, Terraphim uses symbolic graph embeddings (Jaccard 0.7 + path distance 0.3) over a typed medical knowledge graph. This provides:

• Determinism: Same input always produces same grounding (no embedding model drift)
• Auditability: Traceable evidence paths (Drug->Treats->Disease->HasVariant->Gene->CitedIn->Trial)
• Safety gate: Every MedGemma recommendation validated against the KG treatment subgraph
• LeftmostLongest matching: Entity extractor always grounds to the most specific SNOMED concept (e.g., "non-small cell lung carcinoma" not "lung carcinoma"), ensuring correct treatment lookups

---

Documentation

• Technical Writeup -- Competition submission
• Competition Evidence -- Real inference evidence with GPU/CPU timing
• Handover Document -- Current state and next steps
• Lessons Learned -- Technical discoveries across 5 sessions

---

License

Dual-licensed under MIT (source code) and CC BY 4.0 (documentation and non-code content). See LICENSE for details.