WA Health Summary

Washington Health Summary (WAHS) · Engine reference

WAHS engine reference.

Technical detail for people building against or reviewing the WAHS engine: how the services connect, where state lives, the wire contract, the build record and the internals. For the plain-language overview, start with the AI strategy page.

Updated November 2026 · Source: wahs-engine on GitHub · Current-state review: Engine architectural & functional audit

On this page
  1. Service architecture
  2. Worked example
  3. Sessions and scope
  4. Wire contract
  5. Build record
  6. Engine internals

Service architecture

Service-to-service flow across WAHS clients, fhir-auth, wahs-engine, and pluggable GPU inference

The target WAHS architecture keeps client frontends lightweight, delegates per-user data access control to WAHS’s existing fhir-auth security proxy, isolates FHIR condensation and clinical reasoning inside a lean standalone wahs-engine middleware service, and speaks standard OpenAI /v1/chat/completions on both sides for plug-and-play model portability.

[1. Client-Agnostic WAHS Frontends & Server-Side BFF] • Unified responsive SvelteKit app (uwcirg/shl-ips) + interoperable mobile-first companion clients • Authenticate via Keycloak OIDC; read/write datasets via fhir-auth and share IPS via shl-server • Browser posts chat turn + optional chart filter to app BFF (/api/chat, Vercel AI SDK), never straight to GPU │ ▼ Internal network · OpenAI POST /v1/chat/completions (Bearer <keycloak_jwt> + optional wahs.chart_scope) [2. Standalone WAHS Engine Middleware (wahs-engine · Zero Med Agent Hub Dependency)] • Zero HAPI admin credentials: forwards caller's Bearer JWT to fhir-auth (jwt-proxy, meta.security.code == sub) • Bundle Assembler walks masterPatient.link[] → paginated Patient/{datasetId}/$everything (provider imports + My Story/Goals) • Applies optional wahs.chart_scope (source/category/section/IPS filter) + merges unsaved wahs.overlay_resources • Runs wahs_core: 90%–99% condensation (condenser.py) + 4-Layer Clinical KB + ClinicalEntityGraph + Tier-0 lookup • Isolates dataset & KV prefix caches strictly by (verified_sub, datasets_fingerprint, scope_hash) │ ▼ Standard OpenAI POST /v1/chat/completions (LLM_BASE_URL · fixed chart prefix + stream=true) [3. Pluggable OpenAI-Compatible Inference Backend (UW CIRG GPU / Agency Host)] • Default pilot: LiteLLM / Ollama / vLLM on UW CIRG GPU server (Gemma 4 12B default · 26B · E4B) • Zero-code portability: swap approved open-weight models or local agency GPU hosts via config alone • Streams tokens immediately; wahs-engine appends x_wahs ([N] → FHIR UUID/source map + HL7 AI-Provenance)
Session Isolation & Timeliness

Prefix-cached follow-ups with strict HAPI invalidation

  • Cryptographic tenant boundary: Raw dataset caches key on (verified_sub, dataset_id, lastUpdated), and condensed prompt prefixes key on (verified_sub, datasets_fingerprint, scope_hash), preventing cross-user or cross-filter bleed.
  • Immediate record timeliness: Whenever a patient imports new EHR records, updates a goal, or deletes a dataset in HAPI, meta.lastUpdated shifts and rebuilds the condensed chart automatically.
  • Deterministic fallback: Placing the [1]...[N] condensed ledger first lets the GPU reuse its KV cache (< 0.3s follow-up prefill), while any cache eviction simply recomputes the identical prompt.
Portability & Lean Packaging

Decoupled clients, swappable models & zero R&D bloat

  • Lean standalone engine vs. R&D workbench: wahs-engine packages pure-Python wahs_core + a thin FastAPI service (~60 MB image, zero OpenMRS/Catalyst dependencies). Med Agent Hub and Validation Harness import wahs_core upstream so benchmarks and production never drift.
  • Frontend independence: Decoupled Keycloak, fhir-auth, shl-server, and wahs-engine services let both the unified SvelteKit web app and mobile-first companion interfaces operate over the exact same patient record.
  • EHIgnite model agnosticism: Standard southbound OpenAI /v1 lets state public-health agencies swap local open-weight models or inference gateways via environment variables while preserving HL7 AI-Provenance transparency.

Worked example: tracing “What are my diabetes labs?” through wahs-engine

To keep follow-up questions fast while reflecting live HAPI FHIR updates, wahs-engine splits every GPU request into two prompt regions: a query-invariant chart prefix at messages[0] and a query-conditioned suffix at messages[-1].

Region 2 · Query-Conditioned Suffix (messages[-1], Layer-3 enrichment)

Targeted diabetes KB, patient graph & [N] source pills

  • Clinical concept mapping: Injects matched LOINC/ADA rules connecting “diabetes labs” to HbA1c, fasting glucose, eGFR, and urine albumin-creatinine ratio so smaller models do not miss differently named labs.
  • Patient relationship subgraph: Attaches verified edges such as Type 2 diabetes [4] --[MONITORED_BY]--> HbA1c 7.8% [12] plus conditional Tier-0 overflow / Note-RAG excerpts when omitted_clinical_items > 0.
  • Streamed provenance: Sits after prior chat history so messages[0] hits the GPU’s KV cache while x_wahs maps [12] to the exact FHIR Observation UUID and clinic pill.

Session and scope layers across the stack

Separating authentication, chat history, chart freshness, and GPU KV caching eliminates any need for a stateful session database on the GPU server or custom session APIs in WAHS client backends.

State / Session Layer Where It Lives Wire Contract, Ollama KV Connection & Security Guarantee
1. User Auth Identity Keycloak · shl-ips · fhir-auth Authorization: Bearer <keycloak_jwt> travels end-to-end from browser BFF to wahs-engine to fhir-auth; wahs-engine holds zero HAPI admin credentials.
2. Chat Turn History Browser tab RAM (messages[]) Ephemeral conversation array sent over stateless OpenAI /v1/chat/completions. Requires no POST /new-chat-session endpoint and intentionally avoids LiteLLM’s Postgres-backed /v1/responses (previous_response_id) so no PHI prompts or chat transcripts persist on the shared GPU server (store_prompts_in_spend_logs: false).
3. Chart & Prefix Cache wahs-engine in-memory LRU Checks live HAPI meta.lastUpdated via fhir-auth on every turn; reuses (verified_sub, datasets_fingerprint, scope_hash) in < 1 ms when unchanged and re-fetches only modified datasets after EHR imports or patient edits.
4. GPU KV-Cache Slots Ollama / vLLM VRAM Stateless HTTP calls match the unchanged messages[0] token prefix automatically across OLLAMA_NUM_PARALLEL warm VRAM slots, cutting warm 32k follow-ups on UW CIRG H200 MIG 2g.35gb to 2.5s–4.0s median latency with zero session_id and zero cross-patient bleed (slots activate only when the caller already sends matching patient tokens).
Scope Boundary Owner What It Controls & Why It Stays Separate
1. Security & Ownership Scope fhir-auth (jwt-proxy) Hard authorization boundary enforcing meta.security.code == jwt.sub before wahs-engine sees any record.
2. User View Filter wahs.chart_scope + overlay_resources Optional patient-chosen UI lens over their own authorized data (clinic sources, resource categories, date window, specific ips_bundle_id, or unsaved drafts).
3. Token-Budget Priority wahs_core (condenser.py) Deterministic 2-stage monotonic structural condensation (512–131,072 tokens) pinning the HL7 IPS safety core and longitudinal [TEMPORAL DIGEST] first while logging any trimmed items in [2] Completeness Manifest.
4. Explicit Sharing Posture sharing_posture Separates private patient self-Q&A (patient_self) from explicit external summary/IPS sharing (external_share).
Inspect OpenAI /v1/chat/completions middleware contract, wahs.chart_scope schema & x_wahs provenance

Server-side routes in WAHS (such as SvelteKit /api/chat/+server.ts using the Vercel AI SDK @ai-sdk/openai-compatible provider) call wahs-engine using standard OpenAI chat completion payloads. Vanilla OpenAI requests with no wahs extension field default automatically to the signed-in user’s full fhir-auth record at the model’s recommended budget; optional wahs.chart_scope and wahs.overlay_resources fields control per-turn filtering and unsaved draft notes, while the final streamed chunk attaches x_wahs citation and HL7 AI Transparency metadata.

POST /v1/chat/completions Authorization: Bearer <keycloak_access_token> Content-Type: application/json { "model": "wahs-12b-kb", "stream": true, "messages": [ { "role": "user", "content": "Do any of my heart or kidney medications conflict across clinics?" } ], "wahs": { "target_budget_tokens": 8192, "chart_scope": { "include_sources": ["UW Medicine", "MultiCare", "My Story"], "exclude_categories": [], "include_resource_types": [], "exclude_resource_ids": [], "ips_bundle_id": null, "date_from": null, "date_to": null }, "overlay_resources": [] } } ──► Standard OpenAI SSE token stream (data: {"object":"chat.completion.chunk", ...}) ──► Final chunk attaches x_wahs provenance for clickable [N] source pills & HL7 AI-Provenance: { "x_wahs": { "citation_map": { "7": { "resourceType": "MedicationRequest", "id": "med-spiro-01", "date": "2026-01-12", "source": "UW Medicine", "display": "Spironolactone 25 MG Oral Tablet" }, "10": { "resourceType": "Observation", "id": "obs-k-56", "date": "2026-01-16", "source": "MultiCare", "display": "Potassium 5.6 mEq/L" } }, "condensation": { "budget_tokens": 8192, "actual_tokens": 6410, "datasets_included": 3, "omitted_clinical_items": 0 }, "ai_provenance": { "model": "ollama/gemma4:12b", "kb_enabled": true, "human_review_required": true } } }

Build record

Five of six build milestones are verified

Each verified milestone links to the code or test behind it. The sixth, stress testing with long notes and records over 100 MB, continues toward ONC/ASTP EHIgnite Phase 2.

Step Workstream Concrete Deliverable Status / Reference
1 Stand Up Standalone wahs-engine (wahs_core + FastAPI) & Invert Hub Dependency Package the pure-stdlib clinical core (wahs_core: condenser.py, clinical_graph.py, 4-Layer KB, wahs_tools.py) and thin OpenAI-compatible wahs_engine server in a dedicated WAHS repository with zero med-agent-hub dependency, while med-agent-hub imports wahs_core upstream for zero-drift benchmarking. Verified
wahs-engine repo ↗
2 Implement Zero-Privilege fhir-auth Bundle Assembler & chart_scope Build the star-graph HAPI assembler that forwards the caller’s Keycloak Bearer token to fhir-auth, paginates linked Patient/$everything datasets (including patient-authored My Story and Goals), applies chart_scope filters and overlay_resources, and emits x_wahs source-pill mappings. Verified
assembler.py ↗
3 Wire Service-to-Service /api/chat BFF Across WAHS Frontends Connect the SvelteKit server route (Vercel AI SDK @ai-sdk/openai-compatible) in shl-ips and interoperable mobile-first companion views to wahs-engine on the internal Docker network, surfacing clickable [N] FHIR provenance drawers, chart-scope chips, and HL7 AI-Provenance badges across swappable OpenAI /v1 inference hosts. Verified
Portability Rehearsal ↗
4 Seed Shared Dev Stack & Verify Session Isolation / Cache Timeliness Pre-seed wahs-environments with multi-source personas and historical Connectathon test accounts, and enforce automated gates across three invariants. Security: zero cross-user sub, session ID, or KV prefix bleed, and no external-share privacy leaks; Data timeliness: immediate cache invalidation whenever HAPI meta.lastUpdated changes; Reliability: cache misses or restarts never alter clinical output. Verified
Verification report ↗
5 Benchmark Condensation vs. Note Embeddings & Dynamic FHIR Querying Run 3-seed evaluations (384 runs across Gemma 4 E4B, 12B, 26B and Qwen 3.5 9B) in Validation Harness comparing wahs_core condensation + Tier-0 overflow (64.6% pass), single-patient Note-RAG + condensation (76.0% pass, 99.3% atomic entailment), dynamic FHIR tool querying (61.5% overall; 95.8% on 26B), and offline raw FHIR (18.8% pass, 12/12 leaks). Verified (384 Runs)
3-Seed Report ↗
6 Long-Note (4k–14k Tokens) & 100 MB+ Record Stress Testing Verified single-patient BM25 Note-RAG lifting deep inpatient and longitudinal note recall from 0% to 83.3%–100.0% at a compact 4k chart budget; next phase scales shared multi-tenant H200 GPU load testing and 100 MB+ partner exports ahead of ONC/ASTP EHIgnite Phase 2. EHIgnite Phase 2
Long-Note Readout ↗

Engine internals

Two-stage monotonic condensation, [TEMPORAL DIGEST], ClinicalEntityGraph, and Layer-3 enrichment

For engineers inspecting the shared wahs_core clinical modules (packaged without R&D dependencies in standalone wahs-engine and imported upstream by Med Agent Hub), every condensed chart undergoes 2-stage monotonic structural condensation: Stage A normalizes records and emits patient demographics at [1], a machine-readable Completeness Manifest at [2], and a chronological [TEMPORAL DIGEST] for numeric trajectories; Stage B packs the IPS safety core and longitudinal sections under dynamic per-model and tokenizer budget reservations. When a KB-guided profile executes (such as wahs-12b-kb or wahs-26b-kb), Layer-3 enrichment runs conditional Tier-0 / Note-RAG overflow recovery, constructs a typed ClinicalEntityGraph, and attaches matched clinical guidelines without a hardcoded 800-token ceiling before calling the model.

The engine API accepts a chart size of 512 to 131,072 tokens per request, with a default of 8,192. The 256k row below applies to the Explorer sandbox and the benchmark matrix.

Budget Window Condensation Strategy Omitted Clinical Items Tier-0 Overflow Recovery
256k / 128k Max-window stress-test ceiling expanding multi-decade and ICU charts up to 251,641 extracted clinical tokens. omitted_clinical_items = 0 Skipped (overflow_triggered: false)
64k / 32k / 16k Full longitudinal clinical ledger preserving complete lab timelines, encounters, and decoded UTF-8 clinical notes. omitted_clinical_items = 0 on standard charts Skipped unless massive 7,000-entry export overflows
8k / 4k Recommended Limit sweet spot: preserves active conditions, active medications, allergies, immunizations, and folded lab trajectories. 0 on typical charts; non-zero on multi-decade exports Conditional: runs only when omitted_clinical_items > 0
2k / 1k Strict HL7 IPS Safety Core micro-capsule; older clinical notes and routine historical lab panels overflow the ceiling. omitted_clinical_items > 0 Active: wahs_tools.py recovers question-matched notes and labs with sequential [N] citations
Inspect ClinicalEntityGraph typed relationship edges & orchestration prompt block

wahs_core/clinical_graph.py links seven FHIR resource categories (Condition, MedicationRequest, Observation, DocumentReference, AllergyIntolerance, Immunization, and Organization) across five typed clinical edges while preserving original [N] citation numbers so 4B–12B models do not have to infer multi-hop cardiorenal or anticoagulation hazards from raw text alone. Paired wahs-*-raw profiles omit this block for zero-hint baseline ablations.

Graph Edge Type Source → Target Nodes Clinical Logic & Knowledge Base Grounding
TREATS MedicationRequest → Condition Maps active medications to documented clinical indications via RxNorm class lookup and AHA/ACC/ADA/KDIGO mappings (e.g., Apixaban [6] --[TREATS]--> Atrial fibrillation [5]).
CONTRAINDICATED_OR_DOSE_ADJUST_IN MedicationRequest → Condition / Observation / AllergyIntolerance Flags renal dosing thresholds, hyperkalemia hazards, supratherapeutic INR, NSAID nephrotoxicity/bleeding, and allergy cross-reactivity (e.g., Spironolactone [7] --[CONTRAINDICATED_OR_DOSE_ADJUST_IN]--> Potassium 5.6 mEq/L [10]).
MONITORED_BY Condition / MedicationRequest → Observation Connects chronic diseases and high-alert therapies to their longitudinal LOINC laboratory and vital trajectories (eGFR, Creatinine, Potassium, HbA1c, INR, NT-proBNP, LDL-C, TSH).
CONTRADICTED_OR_MODIFIED_BY_NOTE Condition (Active ↔ Resolved) Detects structured cross-organization discrepancies where the same condition is marked active at one clinic and resolved at another, while full narrative notes route through Note-RAG / Tier-0 overflow.
REPORTED_BY_ORG Clinical Node → Organization Preserves multi-facility care provenance (e.g., primary health system vs. outside urgent care or external reference laboratory).
[WAHS CLINICAL CONTEXT ENRICHMENT] 1. Tier-0 Overflow Recovery (ACTIVE: omitted_clinical_items=6 [clinical_note=2, lab_observation=4]; recovered=3 records via wahs_tools): [6] (2026-01-18) Tier-0 Recovered Clinical Note: Outside Urgent Care Walk-In Note. Walk-in visit at UrgentCare Plus Medical Center: Holding spironolactone pending repeat potassium check... [UUID: note-outside-urgentcare-99] 2. Patient Clinical Entity Subgraph (8 nodes, 7 edges): - [7] Spironolactone 25 MG Oral Tablet --[CONTRAINDICATED_OR_DOSE_ADJUST_IN]--> [10] Potassium (latest 5.6 mEq/L) | RAAS / MRA cardiorenal safety - [5] Heart failure --[CONTRADICTED_OR_MODIFIED_BY_NOTE]--> [11] Heart failure (RESOLVED) | Cross-clinic status discrepancy (ACTIVE vs. RESOLVED) 3. Question-Conditioned Clinical Knowledge Base (4 matched guidelines): - [KB wahs-kb-rx-hyperkalemia-01 | AHA/ACC/HFSA & KDIGO] Spironolactone & Hyperkalemia in Stage 3B/4 CKD: Hold MRA when serum K+ > 5.0–5.5 mEq/L...

Back to top