Communication Service — AI Integration

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

1. AI touch points

All AI access goes through ai-gateway-service behind Kong at /v1/ai/*. No vendor SDKs in this service. No browser-exposed model keys. AI outputs are assistive only — they never auto-send messages or auto-admit participants.

Feature	Purpose	Prompt template	Moderation	HITL
Message draft assistant	Clinicians draft replies / escalation messages	comms.message_draft.v1	Pre-send moderation + PHI leak classifier	User must press Send
Smart triage summarization	Summarize long patient-initiated threads into a triage note	comms.thread_triage.v1	Output redaction, no PHI in logs	Triage nurse reviews and accepts
Virtual session live transcription	Generate STT transcript for recording capture	comms.vc_transcription.v1	Provider consent required; per-tenant flag	Provider can delete transcript
Suggested reply (patient)	Short canned suggestions for patient replies	comms.patient_suggest.v1	Low-risk category; no diagnosis suggestions	Patient taps to send
Notification tone / localization	Localize template variables into target language	comms.notif_localize.v1	No PHI in variables	Offline fallback = untranslated template

2. Provenance

Every AI-assisted artifact carries AIProvenance { modelName, modelVersion, promptTemplateKey, promptTemplateVersion, moderationVerdict, redactions[], createdAt } attached to the created message or virtual session record. Records written to chart (via Communication or triage notes) include Provenance references when the user accepts the AI output.

3. HITL enforcement

• UI shows an "AI-generated draft" banner until the user edits or explicitly accepts.
• POST /v1/communication/threads/{id}/messages accepts an aiProvenanceId that audit-links to the raw AI call.
• Audit event ai.completion.accepted.v1 is emitted by ai-gateway-service; communication-service records linkage.

4. Offline behavior

Per FR-AI-008: when cloud AI is unavailable, UI degrades gracefully — the composer becomes a plain text field, no smart triage suggestions appear, and transcription pauses with a user-visible notice.

5. PHI handling

• Prompts built from user input only (never PHI shared with foreign tenants).
• ai-gateway-service applies ABAC / minimum-necessary before enriching prompts with FHIR context.
• Dispatch-related AI calls (notification localization) never receive raw PHI; variables are opaque.

6. Open questions

• OQ-COMMS-AI-001: Do we allow on-device STT for low-bandwidth deployments instead of cloud STT? (TBD; tracked under NFR-AI-018.)