mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 15:23:29 +00:00
feat(labs): add Lab-OCR extract, commit, and capability routes
Resolve a vision-capable provider, gate with consent + a 6/hour rate bucket + a reserved per-day token budget, then transcribe an uploaded photo or PDF into structured proposed rows. The raw upload stays in memory only and is never persisted. The commit route writes only the rows a human confirmed, resolving or minting a biomarker per row with source OCR and skipping commit-time duplicates. The capability probe drives whether the UI shows the scan entry. Extracted text is treated as untrusted; the review screen is the safety boundary.
This commit is contained in:
1 parent
7f71f0e7a6
commit
4d0856c56f
9 files changed
+1287
No files matched your search
@@ -0,0 +1,31 @@
|
||||
/**
|
||||
* v1.18.9 — GET /api/labs/ocr/capability
|
||||
*
|
||||
* Cheap probe (no provider call) the Labs UI uses to decide whether to show
|
||||
* the "Scan a report" affordance. Returns `{ available, reason, pdfSupported }`
|
||||
* for the calling user's configured AI provider. The surface stays dark for
|
||||
* codex-only / text-only-model users.
|
||||
*/
|
||||
import { apiHandler, requireAuth } from "@/lib/api-handler";
|
||||
import { apiSuccess } from "@/lib/api-response";
|
||||
import { resolveOcrCapability } from "@/lib/labs/ocr-capability";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
|
||||
export const dynamic = "force-dynamic";
|
||||
|
||||
export const GET = apiHandler(async () => {
|
||||
const { user } = await requireAuth();
|
||||
|
||||
const capability = await resolveOcrCapability(user.id);
|
||||
|
||||
annotate({
|
||||
action: { name: "labs.ocr.capability" },
|
||||
meta: {
|
||||
available: capability.available,
|
||||
reason: capability.reason,
|
||||
pdfSupported: capability.pdfSupported,
|
||||
},
|
||||
});
|
||||
|
||||
return apiSuccess(capability);
|
||||
});
|
||||
@@ -0,0 +1,162 @@
|
||||
/**
|
||||
* v1.18.9 — POST /api/labs/ocr/commit
|
||||
*
|
||||
* Writes ONLY the rows the human confirmed on the review screen. Each row
|
||||
* resolves-or-mints a user-scoped biomarker by `(userId, lower(analyte))` —
|
||||
* exactly like the manual lab-write path — then creates a `LabResult` with
|
||||
* `source: "OCR"`. A row that now duplicates a live reading (re-checked at
|
||||
* commit time) is skipped rather than written. Idempotent (Idempotency-Key).
|
||||
*
|
||||
* `userId` is always narrowed from the session — never a body field. The write
|
||||
* `data` object is built field-by-field (no mass assignment).
|
||||
*/
|
||||
import { NextRequest } from "next/server";
|
||||
|
||||
import { apiHandler, requireAuth } from "@/lib/api-handler";
|
||||
import {
|
||||
apiSuccess,
|
||||
getClientIp,
|
||||
returnAllZodIssues,
|
||||
safeJson,
|
||||
sanitiseZodIssues,
|
||||
} from "@/lib/api-response";
|
||||
import { auditLog } from "@/lib/auth/audit";
|
||||
import { prisma } from "@/lib/db";
|
||||
import { withIdempotency } from "@/lib/idempotency";
|
||||
import { enqueueReminderSatisfy } from "@/lib/jobs/reminder-satisfy";
|
||||
import { resolveOrMintBiomarker } from "@/lib/labs/biomarker-store";
|
||||
import { serialiseLabResult } from "@/lib/labs/serialise";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
import {
|
||||
ocrCommitSchema,
|
||||
type OcrCommitRow,
|
||||
type OcrSkippedRowDto,
|
||||
} from "@/lib/validations/labs-ocr";
|
||||
|
||||
export const POST = apiHandler(withIdempotency<[NextRequest]>(commitOcrRows));
|
||||
|
||||
/** True when a live reading already records this analyte+day+value. */
|
||||
async function isDuplicate(
|
||||
userId: string,
|
||||
row: OcrCommitRow,
|
||||
): Promise<boolean> {
|
||||
const dayStart = new Date(row.takenAt);
|
||||
dayStart.setUTCHours(0, 0, 0, 0);
|
||||
const dayEnd = new Date(row.takenAt);
|
||||
dayEnd.setUTCHours(23, 59, 59, 999);
|
||||
|
||||
const candidates = await prisma.labResult.findMany({
|
||||
where: {
|
||||
userId,
|
||||
deletedAt: null,
|
||||
analyte: { equals: row.analyte.trim(), mode: "insensitive" },
|
||||
takenAt: { gte: dayStart, lte: dayEnd },
|
||||
},
|
||||
select: { value: true, valueText: true },
|
||||
take: 25,
|
||||
});
|
||||
for (const c of candidates) {
|
||||
if (row.value !== undefined && c.value !== null && c.value === row.value) {
|
||||
return true;
|
||||
}
|
||||
if (
|
||||
row.valueText !== undefined &&
|
||||
c.valueText !== null &&
|
||||
c.valueText.trim().toLowerCase() === row.valueText.trim().toLowerCase()
|
||||
) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
async function commitOcrRows(request: NextRequest) {
|
||||
const { user } = await requireAuth();
|
||||
|
||||
const { data: body, error: jsonError } = await safeJson(request, {
|
||||
maxBytes: 256 * 1024,
|
||||
});
|
||||
if (jsonError) return jsonError;
|
||||
|
||||
const parsed = ocrCommitSchema.safeParse(body);
|
||||
if (!parsed.success) {
|
||||
annotate({
|
||||
action: { name: "labs.ocr.commit.validation-failed" },
|
||||
meta: { issue_count: parsed.error.issues.length },
|
||||
});
|
||||
// Free-text analyte / unit could land in a Zod issue message — strip values.
|
||||
const auditIssues = sanitiseZodIssues(parsed.error.issues, {
|
||||
stripValuesFromMessage: true,
|
||||
});
|
||||
prisma.auditLog
|
||||
.create({
|
||||
data: {
|
||||
userId: user.id,
|
||||
action: "labs.ocr.commit.validation-failed",
|
||||
details: JSON.stringify({ issues: auditIssues }),
|
||||
},
|
||||
})
|
||||
.catch(() => {});
|
||||
return returnAllZodIssues(parsed.error, 422);
|
||||
}
|
||||
|
||||
const inserted: ReturnType<typeof serialiseLabResult>[] = [];
|
||||
const skipped: OcrSkippedRowDto[] = [];
|
||||
|
||||
for (const row of parsed.data.rows) {
|
||||
if (await isDuplicate(user.id, row)) {
|
||||
skipped.push({ analyte: row.analyte.trim(), reason: "duplicate" });
|
||||
continue;
|
||||
}
|
||||
|
||||
const isQualitative = row.valueText !== undefined;
|
||||
const biomarker = await resolveOrMintBiomarker(user.id, {
|
||||
analyte: row.analyte,
|
||||
// A qualitative reading has no numeric unit / range.
|
||||
unit: isQualitative ? (row.unit ?? "") : (row.unit as string),
|
||||
referenceLow: isQualitative ? null : (row.referenceLow ?? null),
|
||||
referenceHigh: isQualitative ? null : (row.referenceHigh ?? null),
|
||||
panel: row.panel ?? null,
|
||||
});
|
||||
|
||||
// Field-by-field — never spread the parsed row. The row stamps the resolved
|
||||
// catalog name/unit/range as historical truth and keeps the FK.
|
||||
const created = await prisma.labResult.create({
|
||||
data: {
|
||||
userId: user.id,
|
||||
biomarkerId: biomarker.id,
|
||||
panel: biomarker.panel,
|
||||
analyte: biomarker.name,
|
||||
value: row.value ?? null,
|
||||
valueText: row.valueText ?? null,
|
||||
unit: biomarker.unit,
|
||||
referenceLow: biomarker.lowerBound,
|
||||
referenceHigh: biomarker.upperBound,
|
||||
takenAt: row.takenAt,
|
||||
source: "OCR",
|
||||
noteEncrypted: null,
|
||||
},
|
||||
});
|
||||
|
||||
inserted.push(serialiseLabResult(created, biomarker));
|
||||
}
|
||||
|
||||
await auditLog("labs.ocr.commit", {
|
||||
userId: user.id,
|
||||
ipAddress: getClientIp(request),
|
||||
details: { count: inserted.length, skipped: skipped.length },
|
||||
});
|
||||
|
||||
annotate({
|
||||
action: { name: "labs.ocr.committed" },
|
||||
meta: { inserted: inserted.length, skipped: skipped.length },
|
||||
});
|
||||
|
||||
// A lab panel just landed — resolve any "annual blood panel" reminders now
|
||||
// rather than waiting on the cron. Fire-and-forget.
|
||||
if (inserted.length > 0) {
|
||||
void enqueueReminderSatisfy(user.id).catch(() => {});
|
||||
}
|
||||
|
||||
return apiSuccess({ inserted, skipped });
|
||||
}
|
||||
@@ -0,0 +1,234 @@
|
||||
/**
|
||||
* v1.18.9 — POST /api/labs/ocr/extract
|
||||
*
|
||||
* Read-only (NOT idempotent) vision extraction of a paper lab report. Accepts
|
||||
* a multipart photo / PDF, runs it through the user's vision-capable AI
|
||||
* provider, and returns STRUCTURED proposed rows for the mandatory human
|
||||
* review screen. Nothing is written to the database here; the raw upload lives
|
||||
* in memory only and is never persisted or logged.
|
||||
*
|
||||
* Guards, in order (mirrors the Coach's discipline):
|
||||
* requireAuth → resolve vision provider (422 if none) → assertConsentForChain
|
||||
* → rate-limit (6/h) → reserveBudget → bounded body read → mime sniff →
|
||||
* PDF/provider gate → runOcrExtraction → reconcile budget.
|
||||
*
|
||||
* The extracted text is UNTRUSTED (prompt-injection): the server never acts on
|
||||
* an instruction inside the document — the human review step is the safety
|
||||
* boundary, and the commit route is the only write path.
|
||||
*/
|
||||
import { Buffer } from "node:buffer";
|
||||
|
||||
import { apiHandler, requireAuth } from "@/lib/api-handler";
|
||||
import { apiError, apiSuccess } from "@/lib/api-response";
|
||||
import { AI_BUDGETS } from "@/lib/ai/ai-budgets";
|
||||
import { assertConsentForChain } from "@/lib/ai/consent-guard";
|
||||
import {
|
||||
buildDateKey,
|
||||
reconcileSpend,
|
||||
reserveBudget,
|
||||
} from "@/lib/ai/coach/budget";
|
||||
import { resolveVisionProvider } from "@/lib/labs/ocr-capability";
|
||||
import { OcrExtractError, runOcrExtraction } from "@/lib/labs/ocr-extract";
|
||||
import {
|
||||
BodyTooLargeError,
|
||||
detectOcrMimeType,
|
||||
OCR_MAX_BYTES,
|
||||
readBoundedBody,
|
||||
} from "@/lib/labs/ocr-upload";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
import { checkRateLimit, rateLimitHeaders } from "@/lib/rate-limit";
|
||||
|
||||
export const dynamic = "force-dynamic";
|
||||
|
||||
/** 6 vision calls per hour — they are expensive. */
|
||||
const EXTRACT_LIMIT_PER_HOUR = 6;
|
||||
const EXTRACT_WINDOW_MS = 60 * 60 * 1000;
|
||||
|
||||
export const POST = apiHandler(async (request: Request) => {
|
||||
const { user } = await requireAuth();
|
||||
|
||||
// 1. Resolve a vision-capable provider. 422 when none is configured.
|
||||
const { chain, pick } = await resolveVisionProvider(user.id);
|
||||
if (!pick) {
|
||||
annotate({
|
||||
action: { name: "labs.ocr.providerUnsupported" },
|
||||
meta: { chainLength: chain.length },
|
||||
});
|
||||
return apiError("No vision-capable AI provider is configured", 422, {
|
||||
errorCode: "labs.ocr.providerUnsupported",
|
||||
});
|
||||
}
|
||||
|
||||
// 2. Consent gate — server-managed egress of health data requires a receipt.
|
||||
await assertConsentForChain({ userId: user.id, chain, surface: "insights" });
|
||||
|
||||
// 3. Rate-limit (vision calls are costly).
|
||||
const rl = await checkRateLimit(
|
||||
`labs-ocr:${user.id}`,
|
||||
EXTRACT_LIMIT_PER_HOUR,
|
||||
EXTRACT_WINDOW_MS,
|
||||
);
|
||||
if (!rl.allowed) {
|
||||
annotate({ action: { name: "labs.ocr.rateLimited" } });
|
||||
const response = apiError("Too many scans. Try again later.", 429, {
|
||||
errorCode: "labs.ocr.rateLimited",
|
||||
});
|
||||
for (const [k, v] of Object.entries(rateLimitHeaders(rl))) {
|
||||
response.headers.set(k, v);
|
||||
}
|
||||
return response;
|
||||
}
|
||||
|
||||
// 4. Reserve the day's budget BEFORE the provider call (atomic, TOCTOU-safe).
|
||||
const dateKey = buildDateKey();
|
||||
const reservation = await reserveBudget(
|
||||
user.id,
|
||||
AI_BUDGETS.ocrExtract.maxTokens,
|
||||
dateKey,
|
||||
);
|
||||
if (!reservation.allowed) {
|
||||
annotate({
|
||||
action: { name: "labs.ocr.budget.exceeded" },
|
||||
meta: { totalAfter: reservation.totalAfter },
|
||||
});
|
||||
return apiError("Your AI usage budget for today is reached.", 429, {
|
||||
errorCode: "labs.ocr.budgetExceeded",
|
||||
});
|
||||
}
|
||||
|
||||
// From here on a failure must refund the reservation.
|
||||
try {
|
||||
// 5. Pre-flight on the declared content length, then a stream-level
|
||||
// bounded read (a chunked upload omits Content-Length and would otherwise
|
||||
// buffer the whole body before any size check).
|
||||
const contentLength = Number(request.headers.get("content-length") ?? 0);
|
||||
if (contentLength > OCR_MAX_BYTES) {
|
||||
annotate({
|
||||
action: { name: "labs.ocr.fileRejected" },
|
||||
meta: { reason: "content_length_exceeded" },
|
||||
});
|
||||
await reconcileSpend(user.id, reservation.reserved, 0, dateKey);
|
||||
return apiError("File is too large (max 12 MB).", 413, {
|
||||
errorCode: "labs.ocr.fileTooLarge",
|
||||
});
|
||||
}
|
||||
|
||||
let formData: FormData;
|
||||
try {
|
||||
const bytes = await readBoundedBody(request.body, OCR_MAX_BYTES);
|
||||
formData = await new Response(new Blob([bytes]), {
|
||||
headers: { "content-type": request.headers.get("content-type") ?? "" },
|
||||
}).formData();
|
||||
} catch (err) {
|
||||
await reconcileSpend(user.id, reservation.reserved, 0, dateKey);
|
||||
if (err instanceof BodyTooLargeError) {
|
||||
annotate({
|
||||
action: { name: "labs.ocr.fileRejected" },
|
||||
meta: { reason: "stream_size_exceeded" },
|
||||
});
|
||||
return apiError("File is too large (max 12 MB).", 413, {
|
||||
errorCode: "labs.ocr.fileTooLarge",
|
||||
});
|
||||
}
|
||||
return apiError("Invalid multipart body", 400);
|
||||
}
|
||||
|
||||
const file = formData.get("file");
|
||||
if (!(file instanceof File)) {
|
||||
await reconcileSpend(user.id, reservation.reserved, 0, dateKey);
|
||||
return apiError("Field 'file' must be a file", 422);
|
||||
}
|
||||
|
||||
let buffer: Buffer;
|
||||
try {
|
||||
buffer = Buffer.from(await file.arrayBuffer());
|
||||
} catch {
|
||||
await reconcileSpend(user.id, reservation.reserved, 0, dateKey);
|
||||
return apiError("Failed to read uploaded file", 400);
|
||||
}
|
||||
|
||||
// 6. Magic-byte MIME sniff (the wire Content-Type is untrusted).
|
||||
const mime = detectOcrMimeType(buffer);
|
||||
if (!mime) {
|
||||
annotate({
|
||||
action: { name: "labs.ocr.fileRejected" },
|
||||
meta: { reason: "unsupported_mime" },
|
||||
});
|
||||
await reconcileSpend(user.id, reservation.reserved, 0, dateKey);
|
||||
return apiError("Upload a JPEG, PNG, WebP, or PDF.", 415, {
|
||||
errorCode: "labs.ocr.fileType",
|
||||
});
|
||||
}
|
||||
|
||||
// 7. PDF gate — only Anthropic reads a native document block in v1.
|
||||
if (mime === "application/pdf" && !pick.pdfSupported) {
|
||||
annotate({
|
||||
action: { name: "labs.ocr.fileRejected" },
|
||||
meta: { reason: "pdf_provider_unsupported" },
|
||||
});
|
||||
await reconcileSpend(user.id, reservation.reserved, 0, dateKey);
|
||||
return apiError(
|
||||
"PDF scanning needs a Claude vision provider; upload a photo instead.",
|
||||
422,
|
||||
{ errorCode: "labs.ocr.pdfNeedsAnthropic" },
|
||||
);
|
||||
}
|
||||
|
||||
const dataBase64 = buffer.toString("base64");
|
||||
const images =
|
||||
mime === "application/pdf" ? [] : [{ mediaType: mime, dataBase64 }];
|
||||
const documents =
|
||||
mime === "application/pdf"
|
||||
? [{ mediaType: "application/pdf" as const, dataBase64 }]
|
||||
: [];
|
||||
|
||||
// 8. Run the extraction. The actual token spend reconciles the reservation.
|
||||
let actualTokens = 0;
|
||||
try {
|
||||
const result = await runOcrExtraction({
|
||||
userId: user.id,
|
||||
provider: pick.entry.instance,
|
||||
providerType: pick.providerType,
|
||||
images,
|
||||
documents,
|
||||
});
|
||||
// The orchestration does not surface token counts; reconcile against the
|
||||
// reserved estimate as the spend ceiling (the provider already billed it).
|
||||
actualTokens = reservation.reserved;
|
||||
await reconcileSpend(
|
||||
user.id,
|
||||
reservation.reserved,
|
||||
actualTokens,
|
||||
dateKey,
|
||||
);
|
||||
return apiSuccess(result);
|
||||
} catch (err) {
|
||||
// Provider/extraction failure — the call may still have burned tokens, so
|
||||
// reconcile against the reserved estimate rather than refunding in full.
|
||||
await reconcileSpend(
|
||||
user.id,
|
||||
reservation.reserved,
|
||||
actualTokens,
|
||||
dateKey,
|
||||
);
|
||||
if (err instanceof OcrExtractError) {
|
||||
return apiError("Couldn't read the report. Try a clearer photo.", 422, {
|
||||
errorCode: "labs.ocr.extractFailed",
|
||||
});
|
||||
}
|
||||
annotate({
|
||||
action: { name: "labs.ocr.extractFailed" },
|
||||
meta: { reason: "provider_error" },
|
||||
});
|
||||
return apiError("Couldn't read the report. Try a clearer photo.", 502, {
|
||||
errorCode: "labs.ocr.extractFailed",
|
||||
});
|
||||
}
|
||||
} catch (err) {
|
||||
// A guard threw after the reservation (e.g. consent races) — refund fully.
|
||||
await reconcileSpend(user.id, reservation.reserved, 0, dateKey).catch(
|
||||
() => {},
|
||||
);
|
||||
throw err;
|
||||
}
|
||||
});
|
||||
Reference in new issue
Block a user