Document Intelligence

Executive summary

Document Intelligence reads what patients and other providers send — referrals, lab results, prior records — and turns it into reviewable structured data. Each upload is malware-scanned, then read, classified, extracted and interpreted in four stages, with mechanical stages on a cheaper tier and safety-relevant stages on the pro tier. Extracted values become proposed facts only through clinician review.

Overview

ProductionProduce · Document Intelligence
Bring outside documents into the structured record without retyping, and without letting an extraction error become a fact.

Pipeline

Upload passes a ClamAV scan and magic-byte checks.
Ingest (OCR) and classification run on the flash tier.
Extraction of structured values and clinical interpretation run on the pro tier.
Results land as artifacts with value snapshots; patient-attribution suggestions are offered when the document’s patient is uncertain.
On acceptance, a fact writer emits extracted values as proposed facts.

Data owned

Documents
Holds
Uploaded files and metadata
Document AI value snapshots
Holds
What each stage extracted, versioned
Patient suggestions and attribution records
Holds
Which patient a document belongs to, and how that was decided

Store	Holds
Documents	Uploaded files and metadata
Document AI value snapshots	What each stage extracted, versioned
Patient suggestions and attribution records	Which patient a document belongs to, and how that was decided

Models and engines

Ingest (OCR), classify
Model or engine
Gemini 3 Flash-Lite (flash tier)
Notes
Extraction temperature 0.1
Extract, interpret
Model or engine
Gemini 3 Flash (pro tier)
Notes
Tier pinned by a contract test

Step	Model or engine	Notes
Ingest (OCR), classify	Gemini 3 Flash-Lite (flash tier)	Extraction temperature 0.1
Extract, interpret	Gemini 3 Flash (pro tier)	Tier pinned by a contract test

Guardrails

Every file is scanned before any model sees it.
Safety-relevant stages run on the pro tier, enforced by tests/ai/modelTierContract.
Extracted values are review-required; acceptance is the only path to facts.
Ambiguous patient attribution blocks rather than guesses.

Rollout and status

ProductionFour-stage analysis
Enabled by default
PlannedDocument re-attribution
ADR 0029 accepted; implementation behind a flag that is off

Interfaces

Consumes
What
Uploads and integration documents
Emits
What
Extraction and interpretation artifacts
Emits
What
Proposed facts on acceptance

Direction	What
Consumes	Uploads and integration documents
Emits	Extraction and interpretation artifacts
Emits	Proposed facts on acceptance

Invariants

Document Intelligence invariants (truth-state vocabulary, stop-the-line rule)

Known limits

Clinical uploads are stored on instance disk today; moving them to Cloud Storage is ADR 0015.

SOURCE OF TRUTH

server/routes/ai/documentAnalysisRun.ts
server/services/documents/
docs/clinical-invariants/documents.md
docs/adr/0029-document-reattribution.md