Patient Chart Service — AI Integration

Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · ai-gateway-service

1. Scope

The patient-chart-service uses AI in the clinical-notes and chart snapshot paths only, and always assistive with clinician HITL accept. No AI is called in problems, allergies, or vitals paths.

2. AI calls

#	Purpose	Tier	Feature id	Prompt template	Moderation	HITL
1	Documentation assist — extend or rephrase a note section	Tier A	chart.note.docassist	pt.chart.note.docassist.v1	refusal + PII scrub	Accept chunk required
2	Speech-to-text transcription of virtual-care audio into draft section	Tier A	chart.note.stt	pt.chart.note.stt.v1	refusal + language model filter	Accept transcript required
3	Template fill — populate template slots from source chart context	Tier A	chart.note.templatefill	pt.chart.note.templatefill.v1	refusal	Accept section required
4	Summarize for handoff / snapshot	Tier A	chart.snapshot.summarize	pt.chart.snapshot.summarize.v1	refusal	Accept before export

All calls go through ai-gateway-service at /v1/ai/assist via Kong. No vendor SDK is embedded in this service.

3. Request shape

{
  "feature": "chart.note.docassist",
  "subjectReference": { "noteId": "note_...", "sectionKey": "assessment" },
  "inputs": {
    "contextSummary": "Patient has T2DM, recent HbA1c 8.2 ...",
    "userPrompt": "expand to 4 sentences, formal tone",
    "locale": "en-US"
  },
  "policyContext": {
    "tenantId": "ten_...",
    "actor": "prc_..."
  }
}

4. Response handling

The AI gateway returns a structured response with content, moderationVerdict, and modelVersion. The service treats the response as draft content only; it is never written into note_sections.body_text until the user calls POST /v1/clinical-notes/{noteId}/ai-accepted with:

{
  "sectionKey": "assessment",
  "feature": "chart.note.docassist",
  "modelVersion": "opus-4.7@1m",
  "content": "...",
  "contentHash": "sha256:..."
}

On accept:

1. Section body is updated (draft only; signed notes reject this call).
2. A note_ai_provenance row is inserted.
3. patient_chart.note.ai_accepted.v1 event is emitted.
4. Audit event written with actor and accepted-at.

5. Refusal & safety

• If moderationVerdict=refuse, the service records an audit event ai.refusal.v1 and returns 200 with an empty content and a reason the UI can render.
• The gateway is responsible for PII redaction of echoed content; the service additionally refuses to write any AI output that contains patientId strings back verbatim in a section marked non-identifying.

6. Offline behavior

When the AI gateway is unavailable or the tenant is offline, the docassist/summarize/templatefill features are disabled in the UI via a feature flag returned by config-service. STT may be queued for later processing when the virtual-care audio artifact is available locally.

7. Provenance contract

NoteAIProvenance schema (per §2 DATA_MODEL):

• feature — matches table above.
• modelVersion — opaque string as returned by gateway (e.g., opus-4.7@1m).
• actorId — the clinician who accepted.
• acceptedAt — server time.
• contentHash — sha256 of accepted content for tamper-evidence.

On export to external systems (FHIR Composition or DocumentReference), AI-accepted sections include a platform extension http://ghasi.health/extensions/ai-provenance listing the provenance rows.

8. Data residency

AI calls respect the deployment residency: Afghanistan tenants route to an in-country gateway pool; the gateway enforces the egress policy.

9. Open Questions

• Should STT retention include the original audio buffer (owned by virtual-care-service) or only the accepted transcript plus provenance? Current policy: transcript + provenance in chart; audio is virtual-care's concern.