AI Gateway Service — AI Integration
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 03 platform-services · 14 compliance-security-extended
This service is the AI integration plane. All AI calls for every other service flow through it. There are no AI calls made from this service that bypass its own pipeline.
1. Registered AI features (v1)
| Feature key | Caller service | Purpose | Prompt template | Moderation | HITL |
|---|---|---|---|---|---|
patient_chart.note_summary | patient-chart-service | Summarise a set of clinical notes | chart.note.summary | pre+post | required_for_phi |
patient_chart.differential_dx | patient-chart-service | Suggest differential diagnoses from S/O/A | chart.ddx | pre+post | required |
medication.interaction_narrative | medication-service | Explain detected drug-drug interactions | med.interaction | pre+post | required_for_phi |
medication.reconciliation_assist | medication-service | Propose reconciliation across sources | med.reconcile | pre+post | required |
radiology.preread_chest_xray | radiology-service | Pre-read narrative (non-diagnostic) | rad.preread.chest_xray | pre+post | required |
laboratory.result_narrative | laboratory-service | Plain-language result explanation | lab.narrative | pre+post | required_for_phi |
portal.triage | patient-portal-service | Patient-facing symptom triage | portal.triage | pre+post strict | required |
vcare.soap_scaffold | virtual-care-service | Generate SOAP scaffold from transcript | vcare.soap | pre+post | required |
interop.document_classification | interop-service | Classify inbound documents | interop.doc_class | post only | sampled |
comms.message_draft | communication-service | Draft clinician-to-patient message | comms.message_draft | pre+post | required |
pophealth.cohort_explanation | population-health-service | Human-readable cohort logic explanation | pop.cohort_explain | post only | none (de-identified) |
2. Prompt template contract
| Field | Detail |
|---|---|
| Storage | Secure registry (outside primary DB); template_hash in prompt_template table |
| Semver | Major bumps require re-approval; minor for wording, patch for whitespace |
| Guardrails | System-message portion; references policy language and safety stance |
| Inputs | Jinja2-style placeholders; validated against feature schema |
| Localisation | ps-AF, fa-AF, en, ar-AE, ur — separate versions |
3. Moderation
| Stage | Classifier(s) | Purpose |
|---|---|---|
| Input | Local fastText PHI sniffer + prompt-injection detector + provider-side moderation (when available) | Refuse prompts that leak beyond feature scope or attempt jailbreak |
| Output | Provider moderation (Anthropic/OpenAI) + local self-harm / medical-safety classifier | Catch harmful output before returning |
Thresholds configurable per feature in config-service. Block verdict returns 422 / sets draftText=null.
4. HITL orchestration
| Policy | Behaviour |
|---|---|
none | Draft returned directly; caller may auto-accept |
required | Draft state under_review; reviewer queue; cannot be auto-accepted |
required_for_phi | As required when resource touches PHI, else none |
sampled | % configured; pulled decisions go to review queue |
Reviewer assignment policy: by facility + feature; escalation path configured in config-service.
5. AIProvenance — every clinical AI artifact
Every accepted draft's provenance record is referenced by the owning clinical service when creating the final FHIR resource. The Provenance resource (FHIR) links:
target→ clinical resource (DocumentReference,Observation,MedicationRequest)agent.who.reference→Device/ai-gateway-serviceentity.what.reference→ Provenance record in this service (viaidentifier.value = prv_...)reason.text→ featureKey
6. Provider matrix (default)
| Feature | Primary | Fallback | Residency constraints |
|---|---|---|---|
| patient_chart.* | Anthropic Claude Sonnet 4 | Azure OpenAI GPT-4o | Tenant KMS region |
| medication.* | Anthropic Claude Sonnet 4 | On-prem vLLM Llama-3.1-70B | AF residency uses on-prem |
| radiology.preread_* | On-prem medical model (vLLM) | None (fail closed) | Always on-prem |
| portal.triage | Azure OpenAI GPT-4o (content-filtered) | Anthropic Claude Sonnet 4 | Region = tenant residency |
| interop.document_classification | Small OSS classifier (Ollama) | OpenAI | N/A |
| pophealth.* | Azure OpenAI GPT-4o | Anthropic | De-identified only |
7. Explicit non-goals
- No autonomous clinical decision making — every clinical-impact feature has HITL or post-moderation block.
- No training/fine-tuning.
- No persistent chat state — each assist is a stateless request.