feat(documents): extract structured facts from clinical documents

Ingest an uploaded doctor report / discharge letter through the existing
dedicated OCR/vision provider rails (the v1.22 document-scan provider/key,
reused — no new provider) and transcribe structured facts into staging.

The safety line is extract, never interpret: the prompt frames the document
as untrusted data to reproduce verbatim. Diagnoses map to Condition,
measured values to Observation, medications to MedicationStatement — with
STATED status only. A code survives only when the document writes it and its
system matches the resource (SNOMED/ICD-10 for a diagnosis, LOINC for a
value, RxNorm/ATC for a medication); nothing is inferred, no value is
range-flagged, no condition is linked to a medication. Every fact carries
per-field provenance and a confidence score; a fact below the confidence
floor fails closed — it cannot be approved until the user edits it.

Routes (apiHandler + Zod + session-narrowed userId, opt-in module-gated):
- POST/GET /api/documents/inbound — upload+extract (vision or local-OCR
  text), and list. The raw document is stored encrypted at rest.
- GET/DELETE /api/documents/inbound/[id] — review detail; soft-delete.
- PATCH .../facts/[factId] — correct a staged fact before approval.
- POST .../confirm — the only write path: approved facts flow into the
  labs / conditions / medications stores through their normal create paths;
  rejected facts are discarded; low-confidence facts are refused.
This commit is contained in:
Marc-André Bombeck committed 2026-06-28 16:57:06 +02:00
1 parent 5280c183bd
commit 98ca0b9d61
9 files changed
+1874

No files matched your search

+171
View File
@@ -0,0 +1,171 @@
/**
* v1.25 (W-DOCS-IN) — commit an APPROVED staged fact into a structured store.
*
* The only write path out of the staging area. Each approved fact is routed to
* its existing structured store through the same field-by-field create the
* manual / OCR paths use — no mass assignment, owner-scoped:
* - OBSERVATION → `LabResult` (resolve-or-mint the biomarker)
* - CONDITION → `IllnessEpisode` (condition journal)
* - MEDICATION_STATEMENT → `Medication` (as-needed record, no reminders)
*
* The app reproduces what the document stated; it never interprets. A Condition
* is stored with `type = OTHER` (mapping a free-text diagnosis to a clinical
* category would BE interpretation) and the stated status/code is transcribed
* verbatim into the encrypted note. A MedicationStatement is recorded as an
* as-needed medication with notifications off — a record of what the patient
* takes, never a prescription action. An Observation never carries a
* range-flag; the reference bounds ride along only as the document stated them.
*/
import { encryptToBytes } from "@/lib/ai/coach/bytes-codec";
import { prisma } from "@/lib/db";
import { resolveOrMintBiomarker } from "@/lib/labs/biomarker-store";
import type { ExtractedFact } from "@/generated/prisma/client";
import type {
ConditionFactData,
MedicationStatementFactData,
ObservationFactData,
} from "@/lib/validations/inbound-documents";
/** A per-fact commit failure the caller maps to a per-fact 422 entry. */
export class FactCommitError extends Error {
code: string;
constructor(code: string, message: string) {
super(message);
this.name = "FactCommitError";
this.code = code;
}
}
export interface CommittedRecordRef {
recordType: "labResult" | "illnessEpisode" | "medication";
recordId: string;
}
/** Parse a stated YYYY-MM-DD into a UTC instant, or fall back to now. */
function statedDateOrNow(date: string | null): Date {
if (date && /^\d{4}-\d{2}-\d{2}$/u.test(date)) {
return new Date(`${date}T00:00:00.000Z`);
}
return new Date();
}
async function commitObservation(
userId: string,
data: ObservationFactData,
): Promise<CommittedRecordRef> {
const isQualitative = typeof data.value !== "number";
// A numeric reading needs a unit so the catalog has something to mint with —
// we never coerce or assume one (fail closed; the user adds it on the review
// screen).
if (!isQualitative && (!data.unit || !data.unit.trim())) {
throw new FactCommitError(
"observation.unitRequired",
"A numeric value needs a unit before it can be saved",
);
}
const biomarker = await resolveOrMintBiomarker(userId, {
analyte: data.label,
unit: isQualitative ? (data.unit ?? "") : (data.unit as string),
referenceLow: isQualitative ? null : data.referenceLow,
referenceHigh: isQualitative ? null : data.referenceHigh,
panel: null,
});
const created = await prisma.labResult.create({
data: {
userId,
biomarkerId: biomarker.id,
panel: biomarker.panel,
analyte: biomarker.name,
value: isQualitative ? null : (data.value as number),
valueText: isQualitative ? data.valueText : null,
unit: biomarker.unit,
referenceLow: biomarker.lowerBound,
referenceHigh: biomarker.upperBound,
takenAt: statedDateOrNow(data.effectiveDate),
source: "DOCUMENT",
noteEncrypted: null,
},
});
return { recordType: "labResult", recordId: created.id };
}
async function commitCondition(
userId: string,
data: ConditionFactData,
): Promise<CommittedRecordRef> {
// Reproduce the stated status + code verbatim in the note — never interpret
// it into the `type` / `lifecycle` enums (that would assign meaning). The
// type stays OTHER so the diagnosis is recorded, not categorised.
const noteParts: string[] = [];
if (data.clinicalStatus) noteParts.push(`Status: ${data.clinicalStatus}`);
if (data.verificationStatus) {
noteParts.push(`Verification: ${data.verificationStatus}`);
}
if (data.code && data.codeSystem) {
noteParts.push(`Code: ${data.codeSystem} ${data.code}`);
}
const note = noteParts.length > 0 ? noteParts.join(" · ") : null;
const created = await prisma.illnessEpisode.create({
data: {
userId,
label: data.label,
type: "OTHER",
lifecycle: "ACUTE",
onsetAt: statedDateOrNow(data.onsetDate),
resolvedAt: null,
parentConditionId: null,
noteEncrypted: note ? encryptToBytes(note) : null,
},
});
return { recordType: "illnessEpisode", recordId: created.id };
}
async function commitMedication(
userId: string,
data: MedicationStatementFactData,
): Promise<CommittedRecordRef> {
const created = await prisma.medication.create({
data: {
userId,
name: data.name,
// The document may not state a dose; record it as unspecified rather
// than invent a number. A blank dose is not allowed by the column.
dose: data.dose && data.dose.trim() ? data.dose.trim() : "unspecified",
// A MedicationStatement is a RECORD of what the patient takes, not a
// prescription action: as-needed (no schedule) with reminders off.
asNeeded: true,
notificationsEnabled: false,
...(data.atcCode ? { atcCode: data.atcCode } : {}),
...(data.rxNormCode ? { rxNormCode: data.rxNormCode } : {}),
},
});
return { recordType: "medication", recordId: created.id };
}
/**
* Commit one approved fact into its structured store. Throws `FactCommitError`
* on a per-fact validation miss (e.g. a numeric observation with no unit) so
* the confirm route can report it without failing the whole batch.
*/
export async function commitApprovedFact(
userId: string,
fact: ExtractedFact,
): Promise<CommittedRecordRef> {
if (fact.factType === "OBSERVATION") {
return commitObservation(
userId,
fact.dataJson as unknown as ObservationFactData,
);
}
if (fact.factType === "CONDITION") {
return commitCondition(
userId,
fact.dataJson as unknown as ConditionFactData,
);
}
return commitMedication(
userId,
fact.dataJson as unknown as MedicationStatementFactData,
);
}