Run document summaries and filing suggestions in the background

The summary and suggest routes accept `Prefer: respond-async`: after the
same quick refusals they answer 202 with a run id, and the background
document AI worker runs the read under two new run kinds
(DOCUMENT_SUMMARY, DOCUMENT_SUGGEST, migration 0370). Without the header
both routes answer synchronously as before; both paths run one shared
body, so they cannot drift.

The worker asks the capability for the record and re-checks the wire for
the provider it picks before every read. A summary that is to be stored
marks the document PENDING while queued, READY when it lands, and
UNAVAILABLE when the run fails or the write does not land. A second
request attaches to a live run only when it would produce the same thing.

The vault asks for both in the background and shows the same calm
waiting line the index uses, worded so a transient read never promises
that leaving the page keeps it. The egress guard and the route inventory
now hold every run kind to its dispatcher re-check and its capability.
This commit is contained in:
Marc-André Bombeck committed 2026-10-03 20:51:57 +02:00
1 parent 7cd323499e
commit eda5776886
24 files changed
+2061 -800

No files matched your search

+74
View File
@@ -0,0 +1,74 @@
/**
* Pieces the summary, suggest and extract run bodies share: the provider pick
* types, the failure shape, and the answer for a stored original that could
* not be turned into a provider input.
*
* Every failure here carries the status, message and `documents.inbound.*`
* code the synchronous route has always answered with, so the background run
* reports exactly what the request would have.
*/
import type {
requireDocumentTextProvider,
requireDocumentVisionProvider,
} from "@/lib/documents/provider-order";
import type { VisionInput } from "@/lib/documents/ai-route-support";
import type { AiRunOutcome } from "./types";
export type DocumentVisionPick = Awaited<
ReturnType<typeof requireDocumentVisionProvider>
>;
export type DocumentTextPick = Awaited<
ReturnType<typeof requireDocumentTextProvider>
>;
/** Who asked: a request (with its client address) or a background run. */
export interface RunOrigin {
ipAddress: string | null;
worker: boolean;
}
/** A failure in the shape the route would answer with. */
export const runFailure = (f: {
status: number;
message: string;
errorCode: string;
}): AiRunOutcome<never> => ({ ok: false, ...f });
/** The provider error every document read answers with (422 parse, 502 wire). */
export function unreadableDocument(parseError: boolean): AiRunOutcome<never> {
return runFailure({
status: parseError ? 422 : 502,
message: "Couldn't read the document. Try a clearer copy.",
errorCode: "documents.inbound.extractFailed",
});
}
/**
* A stored original that could not become a provider input, as the summary
* and suggest routes have always answered it.
*/
export function visionPreparationFailure(
reason: Extract<VisionInput, { ok: false }>["reason"],
): AiRunOutcome<never> {
if (reason === "pdfNeedsAnthropic") {
return runFailure({
status: 422,
message:
"PDF scanning needs a Claude vision provider; use local OCR instead.",
errorCode: "documents.inbound.pdfNeedsAnthropic",
});
}
if (reason === "fileType") {
return runFailure({
status: 422,
message: "This document can't be scanned. Use local OCR (text mode).",
errorCode: "documents.inbound.fileType",
});
}
return runFailure({
status: 422,
message: "Couldn't read the stored document.",
errorCode: "documents.inbound.extractFailed",
});
}
+12 -3
View File
@@ -23,13 +23,18 @@ import {
* The live run of this kind for this document, if one is queued or running:
* a second press of "Read with AI" (another tab, a double click) attaches to
* it instead of paying for a second read.
*
* `paramsMatch` narrows the attach to a run that will produce the same thing:
* a summary that is to be stored must not attach to a transient transcription
* of the same document.
*/
export async function findLiveDocumentRun(
userId: string,
documentId: string,
kind: DocumentAiRunKindValue,
paramsMatch?: (params: AiRunParams) => boolean,
): Promise<string | null> {
const row = await prisma.documentAiRun.findFirst({
const rows = await prisma.documentAiRun.findMany({
where: {
userId,
documentId,
@@ -37,10 +42,14 @@ export async function findLiveDocumentRun(
status: { in: ["QUEUED", "RUNNING"] },
expiresAt: { gt: new Date() },
},
select: { id: true },
select: { id: true, paramsJson: true },
orderBy: { createdAt: "desc" },
take: 10,
});
return row?.id ?? null;
const live = paramsMatch
? rows.find((row) => paramsMatch(row.paramsJson as unknown as AiRunParams))
: rows[0];
return live?.id ?? null;
}
export async function startAiRun(args: {
+112
View File
@@ -0,0 +1,112 @@
/**
* Filing suggestions for a stored document: the body both the synchronous
* suggest route and the background run execute.
*
* One provider call over the stored original (vision) or text the browser read
* (text) returns a `{ title, kind, documentDate }` draft. Nothing is written to
* the document: the person reviews the draft and saves it on the edit form.
* The reservation the caller took is settled here.
*/
import type { ProviderChainType } from "@/lib/ai/provider-chain";
import { auditLog } from "@/lib/auth/audit";
import {
prepareVisionInput,
refundDocumentAiSlot,
type LoadedDocument,
} from "@/lib/documents/ai-route-support";
import {
DocumentAssistError,
runDocumentAssist,
type DocumentSuggestion,
} from "@/lib/documents/assist";
import { annotate } from "@/lib/logging/context";
import {
unreadableDocument,
visionPreparationFailure,
type DocumentTextPick,
type DocumentVisionPick,
type RunOrigin,
} from "./run-support";
import { settleAiRunBudget } from "./store";
import type {
AiRunBudget,
AiRunOutcome,
DocumentSuggestRunResult,
} from "./types";
/** One provider call. */
export const DOCUMENT_SUGGEST_MODEL_CALLS = 1;
export type DocumentSuggestInput =
| { mode: "text"; text: string; pick: DocumentTextPick; budget: AiRunBudget }
| { mode: "vision"; pick: DocumentVisionPick; budget: AiRunBudget };
/** Suggest filing details for one owned document. The caller authorised and charged it. */
export async function executeDocumentSuggest(args: {
userId: string;
document: LoadedDocument;
input: DocumentSuggestInput;
origin: RunOrigin;
}): Promise<AiRunOutcome<DocumentSuggestRunResult>> {
const { userId, document, input, origin } = args;
const { pick, budget } = input;
const servedBy = pick.entry.providerType as ProviderChainType;
let suggestion: DocumentSuggestion;
try {
if (input.mode === "text") {
suggestion = await runDocumentAssist({
provider: pick.entry.instance,
providerType: pick.providerType,
ocrText: input.text,
});
} else {
const vision = await prepareVisionInput(
document,
input.pick.pdfSupported,
);
if (!vision.ok) {
// Preparation failed before any provider dispatch: the reservation
// and the slot go back.
await settleAiRunBudget(userId, budget, 0, null);
await refundDocumentAiSlot(userId);
return visionPreparationFailure(vision.reason);
}
suggestion = await runDocumentAssist({
provider: pick.entry.instance,
providerType: pick.providerType,
images: vision.images,
documents: vision.documents,
});
}
} catch (err) {
await settleAiRunBudget(userId, budget, 0, null);
if (!(err instanceof DocumentAssistError)) {
annotate({
action: { name: "documents.assist.failed" },
meta: { reason: "provider_error", mode: input.mode },
});
}
return unreadableDocument(err instanceof DocumentAssistError);
}
await settleAiRunBudget(userId, budget, budget.reserved, servedBy);
await auditLog("documents.inbound.suggest", {
userId,
...(origin.worker ? { actorUserId: userId } : {}),
ipAddress: origin.ipAddress,
details: { documentId: document.id, mode: input.mode },
});
annotate({
action: { name: "documents.assist.suggest" },
meta: {
documentId: document.id,
mode: input.mode,
hasTitle: suggestion.title !== null,
hasKind: suggestion.kind !== null,
hasDate: suggestion.documentDate !== null,
},
});
return { ok: true, data: { suggestions: suggestion } };
}
+250
View File
@@ -0,0 +1,250 @@
/**
* A document summary or transcription: the body both the synchronous summary
* route and the background run execute, so the two paths cannot drift.
*
* Vision mode decrypts the stored original and makes one provider call; text
* mode sends text the browser read on the device. The call runs against a
* reservation the caller already took, which is settled here. A summary the
* caller asked to keep is stored on the document (or its refusal recorded as
* a state); a transcription and an ordinary summary stay transient.
*
* Every failure comes back as the outcome the route has always answered with.
*/
import type { ProviderChainType } from "@/lib/ai/provider-chain";
import type { OutboundReason } from "@/lib/ai/safety/outbound-screen";
import { auditLog } from "@/lib/auth/audit";
import { prisma } from "@/lib/db";
import {
prepareVisionInput,
refundDocumentAiSlot,
type LoadedDocument,
} from "@/lib/documents/ai-route-support";
import {
DocumentDescribeError,
documentSummaryBlockedCopy,
runDocumentSummary,
transcribeDocument,
type DescribeInput,
} from "@/lib/documents/describe";
import { encryptDocumentSummary } from "@/lib/documents/store";
import type { Locale } from "@/lib/i18n/config";
import { annotate } from "@/lib/logging/context";
import {
unreadableDocument,
visionPreparationFailure,
type DocumentTextPick,
type DocumentVisionPick,
type RunOrigin,
} from "./run-support";
import { settleAiRunBudget } from "./store";
import type {
AiRunBudget,
AiRunOutcome,
DocumentSummaryRunResult,
} from "./types";
/** One provider call: the summary, or the transcription. */
export const DOCUMENT_SUMMARY_MODEL_CALLS = 1;
export type DocumentSummaryOutput = "summary" | "text";
export type DocumentSummaryInput =
| { mode: "text"; text: string; pick: DocumentTextPick; budget: AiRunBudget }
| { mode: "vision"; pick: DocumentVisionPick; budget: AiRunBudget };
export interface SummaryPersistence {
/** Replace a stored summary; without it only an empty slot is filled. */
replaceExisting: boolean;
}
/**
* Store a screened-clean summary, or record the refusal as a state.
*
* A blocked summary NEVER lands as text: the honest statement the caller shows
* is generated copy for this response, not the model's prose, and persisting it
* would put a refusal where a summary belongs. Only the WITHHELD state is kept,
* and it is not terminal: the person can ask again.
*
* Storing is best-effort. The summary is already in the answer; a failed write
* must not turn that into an error.
*/
async function persistSummary(
userId: string,
documentId: string,
persist: SummaryPersistence,
summary: string,
blocked: OutboundReason | null,
): Promise<"stored" | "withheld" | "failed"> {
try {
if (blocked) {
await prisma.inboundDocument.updateMany({
where: {
id: documentId,
userId,
deletedAt: null,
summaryState: { not: "READY" },
},
// An explicit request is the person reading it on purpose, so an
// import's hold on automatic AI reading ends here.
data: { summaryState: "WITHHELD", aiReadDeferred: false },
});
return "withheld";
}
// Preserve a previously stored summary unless the caller explicitly chose
// the replacement action. Failed or screened attempts never reach this
// write, so the previous clean summary remains available in those cases.
const written = await prisma.inboundDocument.updateMany({
where: {
id: documentId,
userId,
deletedAt: null,
...(persist.replaceExisting ? {} : { summaryEncrypted: null }),
},
data: {
summaryEncrypted: encryptDocumentSummary(summary),
summaryGeneratedAt: new Date(),
summaryState: "READY",
aiReadDeferred: false,
},
});
annotate({
action: { name: "documents.summary.persisted" },
meta: { documentId, stored: written.count > 0 },
});
return written.count > 0 ? "stored" : "failed";
} catch {
annotate({
action: { name: "documents.summary.persistFailed" },
meta: { documentId },
});
return blocked ? "withheld" : "failed";
}
}
/**
* Mark a summary the background run was asked to store as not produced. Only
* the PENDING state the queuing route set is moved, so a summary that landed
* meanwhile (another tab, the automatic job) is never overwritten.
*/
export async function markQueuedSummaryUnavailable(
userId: string,
documentId: string,
): Promise<void> {
try {
await prisma.inboundDocument.updateMany({
where: { id: documentId, userId, summaryState: "PENDING" },
data: { summaryState: "UNAVAILABLE" },
});
} catch {
// The run's failure is already decided; the hourly summary reaper moves a
// PENDING state that outlives its job.
}
}
/**
* Mark a summary as being generated when a run that will store it is queued,
* so the detail view says so across reloads. Never over a stored summary: a
* replacement keeps showing the old one until the new one lands.
*/
export async function markSummaryQueued(
userId: string,
documentId: string,
): Promise<void> {
await prisma.inboundDocument.updateMany({
where: {
id: documentId,
userId,
deletedAt: null,
summaryEncrypted: null,
},
data: { summaryState: "PENDING" },
});
}
/** Summarise or transcribe one owned document. The caller authorised and charged it. */
export async function executeDocumentSummary(args: {
userId: string;
document: LoadedDocument;
input: DocumentSummaryInput;
output: DocumentSummaryOutput;
locale: Locale;
persist: SummaryPersistence | null;
origin: RunOrigin;
}): Promise<AiRunOutcome<DocumentSummaryRunResult>> {
const { userId, document, input, output, locale, origin } = args;
const { pick, budget } = input;
const servedBy = pick.entry.providerType as ProviderChainType;
let describeInput: DescribeInput;
if (input.mode === "text") {
describeInput = {
provider: pick.entry.instance,
providerType: pick.providerType,
ocrText: input.text,
};
} else {
const vision = await prepareVisionInput(document, input.pick.pdfSupported);
if (!vision.ok) {
// Preparation failed before any provider dispatch: the reservation and
// the slot go back.
await settleAiRunBudget(userId, budget, 0, null);
await refundDocumentAiSlot(userId);
return visionPreparationFailure(vision.reason);
}
describeInput = {
provider: pick.entry.instance,
providerType: pick.providerType,
images: vision.images,
documents: vision.documents,
};
}
let result: DocumentSummaryRunResult;
try {
if (output === "text") {
result = await transcribeDocument(describeInput);
} else {
const { summary, blocked } = await runDocumentSummary({
...describeInput,
locale,
});
const persistence = args.persist
? await persistSummary(
userId,
document.id,
args.persist,
summary,
blocked,
)
: undefined;
result = {
summary: blocked ? documentSummaryBlockedCopy(locale) : summary,
...(persistence ? { persistence } : {}),
};
}
} catch (err) {
await settleAiRunBudget(userId, budget, 0, null);
if (!(err instanceof DocumentDescribeError)) {
annotate({
action: { name: "documents.summary.failed" },
meta: { reason: "provider_error", mode: input.mode },
});
}
return unreadableDocument(err instanceof DocumentDescribeError);
}
await settleAiRunBudget(userId, budget, budget.reserved, servedBy);
await auditLog("documents.inbound.summary", {
userId,
// A background run has no request left to attribute the action from.
...(origin.worker ? { actorUserId: userId } : {}),
ipAddress: origin.ipAddress,
details: { documentId: document.id, mode: output, inputMode: input.mode },
});
annotate({
action: { name: "documents.summary.serve" },
meta: { documentId: document.id, mode: output, inputMode: input.mode },
});
return { ok: true, data: result };
}
+45 -1
View File
@@ -8,14 +8,33 @@
* `GET /api/ai-runs/{id}` until the run is terminal. The result lives in the
* row for an hour after it finishes and then the row is deleted.
*/
import type { AiCapabilityKey } from "@/lib/ai/capabilities/types";
import type { Locale } from "@/lib/i18n/config";
import type { InboundDocumentKindValue } from "@/lib/validations/inbound-documents";
import type { OcrExtractResponseDto } from "@/lib/validations/labs-ocr";
export const DOCUMENT_AI_RUN_KINDS = [
"DOCUMENT_INDEX",
"LABS_OCR_EXTRACT",
"DOCUMENT_SUMMARY",
"DOCUMENT_SUGGEST",
] as const;
export type DocumentAiRunKindValue = (typeof DOCUMENT_AI_RUN_KINDS)[number];
/**
* The capability each kind of run answers to: the one its queuing route asks,
* asked again by the worker for the record before anything leaves.
*/
export const DOCUMENT_AI_RUN_CAPABILITY: Record<
DocumentAiRunKindValue,
AiCapabilityKey
> = {
DOCUMENT_INDEX: "documentAi",
LABS_OCR_EXTRACT: "labsOcr",
DOCUMENT_SUMMARY: "documentAi",
DOCUMENT_SUGGEST: "documentAi",
};
export const DOCUMENT_AI_RUN_STATUSES = [
"QUEUED",
"RUNNING",
@@ -64,6 +83,13 @@ export interface AiRunParams {
mime?: "image/jpeg" | "image/png" | "image/webp" | "application/pdf";
/** Present when the enqueue reserved budget for a provider call. */
budget?: AiRunBudget;
/** A summary run: what to produce, whether to store it, and in which language. */
summary?: {
output: "summary" | "text";
persist: boolean;
replace: boolean;
locale: Locale;
};
}
/** "Read with AI": the same body the synchronous index route answers with. */
@@ -74,7 +100,25 @@ export interface DocumentIndexRunResult {
labFactsStaged: number;
}
export type AiRunResult = DocumentIndexRunResult | OcrExtractResponseDto;
/** A summary run: the summary route's body. */
export type DocumentSummaryRunResult =
| { summary: string; persistence?: "stored" | "withheld" | "failed" }
| { text: string };
/** A suggest run: the suggest route's body (drafts, nothing written). */
export interface DocumentSuggestRunResult {
suggestions: {
title: string | null;
kind: InboundDocumentKindValue | null;
documentDate: string | null;
};
}
export type AiRunResult =
| DocumentIndexRunResult
| OcrExtractResponseDto
| DocumentSummaryRunResult
| DocumentSuggestRunResult;
/**
* What one run body produced: the success body, or the failure the
+222 -1
View File
@@ -13,7 +13,11 @@
* in `assertRunMayEgress` turns "refuses when consent was withdrawn" red;
* deleting the `aiCapabilityForJob` check turns "refuses when the operator
* turned reading off" red; dropping the `ends > deadlineAt` comparison turns
* "refuses a read that cannot fit" red.
* "refuses a read that cannot fit" red. For the summary and suggest kinds:
* deleting `afterRunFailed` (or its `markQueuedSummaryUnavailable` call)
* turns "a stored summary that fails is marked UNAVAILABLE" red, and deleting
* the `assertRunMayEgress` call in `pickForDocumentRead`'s text branch turns
* "a text suggestion re-checks the wire" red.
*/
import { beforeEach, describe, expect, it, vi } from "vitest";
@@ -38,9 +42,12 @@ vi.mock("@/lib/ai/capabilities/egress", () => ({
}));
const requireDocumentVisionProvider = vi.fn();
const requireDocumentTextProvider = vi.fn();
vi.mock("@/lib/documents/provider-order", () => ({
requireDocumentVisionProvider: (...a: unknown[]) =>
requireDocumentVisionProvider(...a),
requireDocumentTextProvider: (...a: unknown[]) =>
requireDocumentTextProvider(...a),
}));
const requireLabsOcrProvider = vi.fn();
vi.mock("@/lib/labs/ocr-capability", () => ({
@@ -58,6 +65,20 @@ vi.mock("@/lib/labs/ocr-run", () => ({
executeOcrExtraction: (...a: unknown[]) => executeOcrExtraction(...a),
}));
const executeDocumentSummary = vi.fn();
const markQueuedSummaryUnavailable = vi.fn();
vi.mock("@/lib/documents/ai-runs/summary-run", () => ({
DOCUMENT_SUMMARY_MODEL_CALLS: 1,
executeDocumentSummary: (...a: unknown[]) => executeDocumentSummary(...a),
markQueuedSummaryUnavailable: (...a: unknown[]) =>
markQueuedSummaryUnavailable(...a),
}));
const executeDocumentSuggest = vi.fn();
vi.mock("@/lib/documents/ai-runs/suggest-run", () => ({
DOCUMENT_SUGGEST_MODEL_CALLS: 1,
executeDocumentSuggest: (...a: unknown[]) => executeDocumentSuggest(...a),
}));
const loadOwnedDocument = vi.fn();
vi.mock("@/lib/documents/ai-route-support", () => ({
loadOwnedDocument: (...a: unknown[]) => loadOwnedDocument(...a),
@@ -333,3 +354,203 @@ describe("handleDocumentAiRunJobs", () => {
});
});
});
describe("summary and suggestion runs", () => {
const summaryRun = (overrides: Record<string, unknown> = {}) =>
claimed({
kind: "DOCUMENT_SUMMARY",
params: {
mode: "vision",
budget,
summary: {
output: "summary",
persist: true,
replace: false,
locale: "de",
},
},
...overrides,
});
beforeEach(() => {
executeDocumentSummary.mockResolvedValue({
ok: true,
data: { summary: "Ein Arztbrief.", persistence: "stored" },
});
executeDocumentSuggest.mockResolvedValue({
ok: true,
data: {
suggestions: { title: "Brief", kind: "OTHER", documentDate: null },
},
});
requireDocumentTextProvider.mockResolvedValue({
entry: {
providerType: "local",
instance: { responseTimeoutSeconds: 90 },
},
providerType: "local",
});
});
it("reads a summary after the re-check, with one call's deadline and its options", async () => {
claimAiRun.mockResolvedValue(summaryRun());
requireDocumentVisionProvider.mockResolvedValue(visionPick(300));
expect(await runDocumentAiRun("run1", NOW + 2_700_000, now)).toBe(
"succeeded",
);
expect(aiCapabilityForJob).toHaveBeenCalledWith("u1", "documentAi");
expect(aiEgressRefusal).toHaveBeenCalledWith("documentAi", "u1", [
"anthropic",
]);
expect(updateMany).toHaveBeenCalledWith({
where: { id: "run1", status: "RUNNING" },
data: { expiresAt: new Date(NOW + 300_000 + 60_000) },
});
expect(executeDocumentSummary).toHaveBeenCalledWith(
expect.objectContaining({
input: expect.objectContaining({ mode: "vision", budget }),
output: "summary",
locale: "de",
persist: { replaceExisting: false },
origin: { ipAddress: null, worker: true },
}),
);
expect(completeAiRun).toHaveBeenCalledWith(
"run1",
{ summary: "Ein Arztbrief.", persistence: "stored" },
new Date(NOW),
);
expect(markQueuedSummaryUnavailable).not.toHaveBeenCalled();
});
it("refuses a summary when consent was withdrawn while it waited, and marks it UNAVAILABLE", async () => {
claimAiRun.mockResolvedValue(summaryRun());
aiEgressRefusal.mockResolvedValue(
new AiUnavailableError("documentAi", "consent_required"),
);
expect(await runDocumentAiRun("run1", NOW + 2_700_000, now)).toBe("failed");
expect(executeDocumentSummary).not.toHaveBeenCalled();
expect(settleAiRunBudget).toHaveBeenCalledWith("u1", budget, 0, null);
expect(markQueuedSummaryUnavailable).toHaveBeenCalledWith("u1", "d1");
});
it("a stored summary that fails is marked UNAVAILABLE", async () => {
claimAiRun.mockResolvedValue(summaryRun());
executeDocumentSummary.mockResolvedValue({
ok: false,
status: 502,
message: "Couldn't read the document. Try a clearer copy.",
errorCode: "documents.inbound.extractFailed",
});
expect(await runDocumentAiRun("run1", NOW + 2_700_000, now)).toBe("failed");
expect(markQueuedSummaryUnavailable).toHaveBeenCalledWith("u1", "d1");
});
it("a stored summary that could not be written is marked UNAVAILABLE", async () => {
claimAiRun.mockResolvedValue(summaryRun());
executeDocumentSummary.mockResolvedValue({
ok: true,
data: { summary: "Ein Arztbrief.", persistence: "failed" },
});
expect(await runDocumentAiRun("run1", NOW + 2_700_000, now)).toBe(
"succeeded",
);
expect(markQueuedSummaryUnavailable).toHaveBeenCalledWith("u1", "d1");
});
it("a transient summary that fails leaves the document's state alone", async () => {
claimAiRun.mockResolvedValue(
summaryRun({
params: {
mode: "vision",
budget,
summary: {
output: "text",
persist: false,
replace: false,
locale: "en",
},
},
}),
);
executeDocumentSummary.mockResolvedValue({
ok: false,
status: 502,
message: "Couldn't read the document. Try a clearer copy.",
errorCode: "documents.inbound.extractFailed",
});
expect(await runDocumentAiRun("run1", NOW + 2_700_000, now)).toBe("failed");
expect(markQueuedSummaryUnavailable).not.toHaveBeenCalled();
});
it("refuses a summary that cannot fit the job's expiry", async () => {
claimAiRun.mockResolvedValue(summaryRun());
requireDocumentVisionProvider.mockResolvedValue(visionPick(600));
// One call at ten minutes plus the margin does not fit in ten minutes.
expect(await runDocumentAiRun("run1", NOW + 10 * 60_000, now)).toBe(
"failed",
);
expect(executeDocumentSummary).not.toHaveBeenCalled();
expect(failAiRun).toHaveBeenCalledWith(
"run1",
expect.objectContaining({ errorCode: "aiRuns.timedOut", status: 504 }),
"RUNNING",
new Date(NOW),
);
});
it("fails a summary whose document is gone, settling the reservation once", async () => {
claimAiRun.mockResolvedValue(summaryRun());
loadOwnedDocument.mockResolvedValue(null);
expect(await runDocumentAiRun("run1", NOW + 2_700_000, now)).toBe("failed");
expect(settleAiRunBudget).toHaveBeenCalledOnce();
expect(failAiRun).toHaveBeenCalledWith(
"run1",
expect.objectContaining({
status: 404,
errorCode: "documents.inbound.notFound",
}),
"RUNNING",
new Date(NOW),
);
});
it("a text suggestion re-checks the wire for the text provider and reads the sealed text", async () => {
claimAiRun.mockResolvedValue(
claimed({
kind: "DOCUMENT_SUGGEST",
params: { mode: "text", budget },
input: Buffer.from("Arbeitsunfähigkeitsbescheinigung"),
}),
);
expect(await runDocumentAiRun("run1", NOW + 2_700_000, now)).toBe(
"succeeded",
);
expect(aiEgressRefusal).toHaveBeenCalledWith("documentAi", "u1", ["local"]);
expect(updateMany).toHaveBeenCalledWith({
where: { id: "run1", status: "RUNNING" },
data: { expiresAt: new Date(NOW + 90_000 + 60_000) },
});
expect(executeDocumentSuggest).toHaveBeenCalledWith(
expect.objectContaining({
input: expect.objectContaining({
mode: "text",
text: "Arbeitsunfähigkeitsbescheinigung",
}),
}),
);
});
it("refuses a suggestion when the operator turned reading off", async () => {
claimAiRun.mockResolvedValue(
claimed({ kind: "DOCUMENT_SUGGEST", params: { mode: "vision", budget } }),
);
aiCapabilityForJob.mockResolvedValue({
available: false,
reason: "operator_disabled",
});
expect(await runDocumentAiRun("run1", NOW + 2_700_000, now)).toBe("failed");
expect(executeDocumentSuggest).not.toHaveBeenCalled();
expect(markQueuedSummaryUnavailable).not.toHaveBeenCalled();
});
});
+176 -9
View File
@@ -44,6 +44,15 @@ import {
DOCUMENT_INDEX_MODEL_CALLS,
executeDocumentIndex,
} from "@/lib/documents/ai-runs/index-run";
import {
DOCUMENT_SUGGEST_MODEL_CALLS,
executeDocumentSuggest,
} from "@/lib/documents/ai-runs/suggest-run";
import {
DOCUMENT_SUMMARY_MODEL_CALLS,
executeDocumentSummary,
markQueuedSummaryUnavailable,
} from "@/lib/documents/ai-runs/summary-run";
import {
claimAiRun,
completeAiRun,
@@ -55,11 +64,17 @@ import {
import {
AI_RUN_ERROR_CODES,
AI_RUN_MARGIN_MS,
DOCUMENT_AI_RUN_CAPABILITY,
type AiRunBudget,
type AiRunOutcome,
type AiRunResult,
type DocumentAiRunKindValue,
} from "@/lib/documents/ai-runs/types";
import { requireDocumentVisionProvider } from "@/lib/documents/provider-order";
import {
requireDocumentTextProvider,
requireDocumentVisionProvider,
} from "@/lib/documents/provider-order";
import { coerceLocale } from "@/lib/i18n/config";
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
import { jobDeadline } from "@/lib/jobs/job-budget";
import { jobDone, type JobOutcome } from "@/lib/jobs/job-outcome";
@@ -88,10 +103,7 @@ export interface DocumentAiRunPayload {
}
/** The capability each kind of run answers to. */
const RUN_CAPABILITY: Record<DocumentAiRunKindValue, AiCapabilityKey> = {
DOCUMENT_INDEX: "documentAi",
LABS_OCR_EXTRACT: "labsOcr",
};
const RUN_CAPABILITY = DOCUMENT_AI_RUN_CAPABILITY;
/**
* Hand a created run to the worker. False when no queue is reachable; the
@@ -262,6 +274,155 @@ async function runLabsOcr(
});
}
/** The owned document a run reads, or the route's own 404 when it is gone. */
async function loadRunDocument(run: ClaimedAiRun) {
const document = run.documentId
? await loadOwnedDocument(run.userId, run.documentId)
: null;
if (document) return document;
// The reservation goes back in `runDocumentAiRun`'s catch.
throw new RunRefused({
status: 404,
message: "Document not found",
errorCode: "documents.inbound.notFound",
});
}
/** The reservation a provider read was queued with. */
function runBudget(run: ClaimedAiRun): AiRunBudget {
if (!run.params.budget)
throw new Error("document read without a reservation");
return run.params.budget;
}
/**
* Pick the provider for a document read the way its route does, re-check the
* capability and the wire for exactly that provider, and arm the deadline for
* the calls the read can make.
*/
async function pickForDocumentRead(
run: ClaimedAiRun,
modelCalls: number,
deadlineAt: number | undefined,
now: () => number,
) {
if (run.params.mode === "text") {
const pick = await requireDocumentTextProvider(run.userId);
await assertRunMayEgress("documentAi", run.userId, [pick.providerType]);
await armDeadline(
run.id,
callTimeoutMs({}, pick.entry.instance.responseTimeoutSeconds),
modelCalls,
deadlineAt,
now,
);
return { mode: "text" as const, pick };
}
const pick = await requireDocumentVisionProvider(run.userId);
await assertRunMayEgress("documentAi", run.userId, [pick.providerType]);
await armDeadline(
run.id,
callTimeoutMs({}, pick.entry.instance.responseTimeoutSeconds),
modelCalls,
deadlineAt,
now,
);
return { mode: "vision" as const, pick };
}
/** The text the browser read, sealed into the run by the queuing route. */
function runText(run: ClaimedAiRun): string {
if (!run.input) throw new Error("text read without an input");
return run.input.toString("utf8");
}
async function runDocumentSummaryRead(
run: ClaimedAiRun,
deadlineAt: number | undefined,
now: () => number,
): Promise<AiRunOutcome<AiRunResult>> {
const options = run.params.summary;
if (!options) throw new Error("summary run without its options");
const document = await loadRunDocument(run);
const read = await pickForDocumentRead(
run,
DOCUMENT_SUMMARY_MODEL_CALLS,
deadlineAt,
now,
);
const budget = runBudget(run);
return executeDocumentSummary({
userId: run.userId,
document,
input:
read.mode === "text"
? { mode: "text", text: runText(run), pick: read.pick, budget }
: { mode: "vision", pick: read.pick, budget },
output: options.output,
locale: coerceLocale(options.locale),
persist: options.persist ? { replaceExisting: options.replace } : null,
origin: { ipAddress: null, worker: true },
});
}
async function runDocumentSuggestRead(
run: ClaimedAiRun,
deadlineAt: number | undefined,
now: () => number,
): Promise<AiRunOutcome<AiRunResult>> {
const document = await loadRunDocument(run);
const read = await pickForDocumentRead(
run,
DOCUMENT_SUGGEST_MODEL_CALLS,
deadlineAt,
now,
);
const budget = runBudget(run);
return executeDocumentSuggest({
userId: run.userId,
document,
input:
read.mode === "text"
? { mode: "text", text: runText(run), pick: read.pick, budget }
: { mode: "vision", pick: read.pick, budget },
origin: { ipAddress: null, worker: true },
});
}
type RunDispatcher = (
run: ClaimedAiRun,
deadlineAt: number | undefined,
now: () => number,
) => Promise<AiRunOutcome<AiRunResult>>;
/**
* The body each kind of run executes. Every dispatcher that sends anything to
* a model re-checks the capability and the wire for its provider first
* (`assertRunMayEgress`); `ai-egress-capability-guard.test.ts` holds that.
*/
const RUN_DISPATCH: Record<DocumentAiRunKindValue, RunDispatcher> = {
DOCUMENT_INDEX: runDocumentIndex,
LABS_OCR_EXTRACT: runLabsOcr,
DOCUMENT_SUMMARY: runDocumentSummaryRead,
DOCUMENT_SUGGEST: runDocumentSuggestRead,
};
/**
* What a failed run leaves behind besides itself. A summary that was to be
* stored had its document marked PENDING at enqueue; a failure says it could
* not be produced rather than leaving "being prepared" until the hourly
* reaper notices.
*/
async function afterRunFailed(run: ClaimedAiRun): Promise<void> {
if (
run.kind === "DOCUMENT_SUMMARY" &&
run.params.summary?.persist &&
run.documentId
) {
await markQueuedSummaryUnavailable(run.userId, run.documentId);
}
}
export type DocumentAiRunResult = "succeeded" | "failed" | "skipped";
/**
@@ -281,10 +442,7 @@ export async function runDocumentAiRun(
let outcome: AiRunOutcome<AiRunResult>;
try {
outcome =
run.kind === "DOCUMENT_INDEX"
? await runDocumentIndex(run, deadlineAt, now)
: await runLabsOcr(run, deadlineAt, now);
outcome = await RUN_DISPATCH[run.kind](run, deadlineAt, now);
} catch (err) {
// Everything that throws here threw before the body took over the
// reservation, so it goes back here.
@@ -298,6 +456,7 @@ export async function runDocumentAiRun(
message: "The background read failed.",
};
await failAiRun(run.id, failure, "RUNNING", new Date(now()));
await afterRunFailed(run);
annotate({
action: { name: "ai_runs.failed" },
meta: {
@@ -311,6 +470,13 @@ export async function runDocumentAiRun(
if (outcome.ok) {
await completeAiRun(run.id, outcome.data, new Date(now()));
if (
"persistence" in outcome.data &&
outcome.data.persistence === "failed"
) {
// The summary was read but could not be stored on the document.
await afterRunFailed(run);
}
annotate({
action: { name: "ai_runs.succeeded" },
meta: { kind: run.kind },
@@ -327,6 +493,7 @@ export async function runDocumentAiRun(
"RUNNING",
new Date(now()),
);
await afterRunFailed(run);
annotate({
action: { name: "ai_runs.failed" },
meta: { kind: run.kind, errorCode: outcome.errorCode },
+21 -6
View File
@@ -6,8 +6,9 @@
*
* Part of the OpenAPI route table; aggregated in `./index.ts`.
*
* iOS coordination (v1.40): `POST /api/documents/inbound/{id}/index` keeps
* its 200 body when the request carries no `Prefer` header. A client that
* iOS coordination (v1.40): `POST /api/documents/inbound/{id}/index`,
* `…/summary` and `…/suggest` keep their 200 bodies when the request carries
* no `Prefer` header. A client that
* sends `Prefer: respond-async` gets 202 with a run id and polls the run here;
* the result is the same body the route would have answered with.
* `POST /api/labs/ocr/extract` (web only) always answers 202.
@@ -15,24 +16,38 @@
import type { ZodOpenApiObject } from "zod-openapi";
import { z } from "zod/v4";
import { documentIndexResponse } from "./documents";
import {
documentIndexResponse,
documentSuggestResponse,
documentSummaryResponse,
} from "./documents";
import { ocrExtractResponse } from "./ocr";
import { dataEnvelope, errorEnvelope, stdResponses } from "./shared";
const aiRun = z
.object({
id: z.string(),
kind: z.enum(["DOCUMENT_INDEX", "LABS_OCR_EXTRACT"]),
kind: z.enum([
"DOCUMENT_INDEX",
"LABS_OCR_EXTRACT",
"DOCUMENT_SUMMARY",
"DOCUMENT_SUGGEST",
]),
documentId: z
.string()
.nullable()
.describe("The document a document run reads; null for a lab scan."),
status: z.enum(["QUEUED", "RUNNING", "SUCCEEDED", "FAILED"]),
result: z
.union([documentIndexResponse, ocrExtractResponse])
.union([
documentIndexResponse,
ocrExtractResponse,
documentSummaryResponse,
documentSuggestResponse,
])
.nullable()
.describe(
"Present once `status` is `SUCCEEDED`: the body the queuing route answers with synchronously. `DOCUMENT_INDEX` carries `DocumentIndexResponse`, `LABS_OCR_EXTRACT` carries `OcrExtractResponse`.",
"Present once `status` is `SUCCEEDED`: the body the queuing route answers with synchronously. `DOCUMENT_INDEX` carries `DocumentIndexResponse`, `LABS_OCR_EXTRACT` carries `OcrExtractResponse`, `DOCUMENT_SUMMARY` carries `DocumentSummaryResponse`, `DOCUMENT_SUGGEST` carries `DocumentSuggestResponse`. Decode by `kind`; treat an unknown `kind` as a run this client did not start.",
),
error: z
.object({
+28 -20
View File
@@ -287,6 +287,26 @@ const documentUploadEnvelope = dataEnvelope(
"DocumentUploadEnvelope",
);
/** The suggest route's body; also a `DOCUMENT_SUGGEST` run's result. */
export const documentSuggestResponse = z
.object({
suggestions: z.object({
title: z.string().nullable(),
kind: kindEnum.nullable(),
documentDate: z.string().nullable(),
}),
})
.meta({ id: "DocumentSuggestResponse" });
/** The summary route's body; also a `DOCUMENT_SUMMARY` run's result. */
export const documentSummaryResponse = z
.object({
summary: z.string().optional(),
text: z.string().optional(),
persistence: z.enum(["stored", "withheld", "failed"]).optional(),
})
.meta({ id: "DocumentSummaryResponse" });
/** The index route's body; also a `DOCUMENT_INDEX` run's result. */
export const documentIndexResponse = z
.object({
@@ -954,9 +974,10 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Suggest filing metadata (drafts only)",
description:
'Optional AI assist on an already-stored document. Runs ONE provider call over the stored original (VISION, empty body) or browser-OCR\'d text (TEXT, `application/json` `{ mode: "text", text }`, opt-in local OCR) and returns a `{ title, kind, documentDate }` DRAFT for the edit form. Answers under the `documentAi` capability (403 with the capability envelope when it is closed), then rate / budget gated (shares the per-user document-AI bucket with extract/summary/index — default 6/hour, operator-tunable via `DOCUMENT_AI_LIMIT_PER_HOUR`; a slot is only consumed when the request reaches the provider, and the 429 carries `Retry-After`, the `X-RateLimit-Limit` / `-Remaining` / `-Reset` triple, and `meta.retryAt`). WRITES NOTHING — never stages facts, never flips status; the user reviews and saves. 422 (`documents.inbound.providerUnsupported`) with no provider configured. Never interprets or diagnoses; the title is a neutral filing label.',
"Optional AI assist on an already-stored document. Runs ONE provider call over the stored original (VISION, empty body) or browser-OCR'd text (TEXT, `application/json` `{ mode: \"text\", text }`, opt-in local OCR) and returns a `{ title, kind, documentDate }` DRAFT for the edit form. Answers under the `documentAi` capability (403 with the capability envelope when it is closed), then rate / budget gated (shares the per-user document-AI bucket with extract/summary/index — default 6/hour, operator-tunable via `DOCUMENT_AI_LIMIT_PER_HOUR`; a slot is only consumed when the request reaches the provider, and the 429 carries `Retry-After`, the `X-RateLimit-Limit` / `-Remaining` / `-Reset` triple, and `meta.retryAt`). WRITES NOTHING — never stages facts, never flips status; the user reviews and saves. 422 (`documents.inbound.providerUnsupported`) with no provider configured. Never interprets or diagnoses; the title is a neutral filing label. With `Prefer: respond-async` (v1.40) the read runs in the background: after the same quick refusals the route answers 202 with a run id, a second request while a suggestion read of this document over the same transport is queued or running answers with that run, and `GET /api/ai-runs/{id}` serves this body as the run's `result`.",
parameters: [
{ name: "id", in: "path", required: true, schema: { type: "string" } },
preferRespondAsyncParameter,
],
requestBody: {
required: false,
@@ -976,20 +997,13 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
content: {
"application/json": {
schema: dataEnvelope(
z
.object({
suggestions: z.object({
title: z.string().nullable(),
kind: kindEnum.nullable(),
documentDate: z.string().nullable(),
}),
})
.meta({ id: "DocumentSuggestResponse" }),
documentSuggestResponse,
"DocumentSuggestEnvelope",
),
},
},
},
...aiRunAccepted,
...aiExtractionRefusals("documentAi"),
...stdResponses,
},
@@ -1000,7 +1014,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
tags: ["Documents"],
summary: "Summarise or transcribe a document",
description:
'On-demand description of a stored document. `?mode=summary` (default) returns a short plain-language summary of WHAT the document is; it remains transient unless `persist=true` fills the empty stored-summary slot, while `persist=true&replace=true` explicitly replaces an existing summary. `?mode=text` returns transient raw transcribed text. Neither result reaches coach memory, snapshots, structured stores, or the search index. The summary is descriptive only and never a diagnosis. Same VISION (empty body) / TEXT (`application/json` `{ mode: "text", text }`, opt-in local OCR) dispatch as extract. Answers under the `documentAi` capability (403 with the capability envelope when it is closed), then rate / budget gated. 422 `documents.inbound.providerUnsupported` with no provider.',
"On-demand description of a stored document. `?mode=summary` (default) returns a short plain-language summary of WHAT the document is; it remains transient unless `persist=true` fills the empty stored-summary slot, while `persist=true&replace=true` explicitly replaces an existing summary. `?mode=text` returns transient raw transcribed text. Neither result reaches coach memory, snapshots, structured stores, or the search index. The summary is descriptive only and never a diagnosis. Same VISION (empty body) / TEXT (`application/json` `{ mode: \"text\", text }`, opt-in local OCR) dispatch as extract. Answers under the `documentAi` capability (403 with the capability envelope when it is closed), then rate / budget gated. 422 `documents.inbound.providerUnsupported` with no provider. With `Prefer: respond-async` (v1.40) the read runs in the background: after the same quick refusals the route answers 202 with a run id, and `GET /api/ai-runs/{id}` serves this body as the run's `result`. A second request while a read with the same `mode`, `persist` and `replace` is queued or running answers with that run. With `persist=true` the document's `summaryState` is PENDING while the run is queued or running (unless a summary is already stored) and becomes UNAVAILABLE when the run fails. `mode=text` over posted text calls no model and is answered synchronously either way (no `Preference-Applied`).",
parameters: [
{ name: "id", in: "path", required: true, schema: { type: "string" } },
{
@@ -1031,6 +1045,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
description:
"With `persist=true`, explicitly replace an existing stored summary.",
},
preferRespondAsyncParameter,
],
requestBody: {
required: false,
@@ -1051,20 +1066,13 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
content: {
"application/json": {
schema: dataEnvelope(
z
.object({
summary: z.string().optional(),
text: z.string().optional(),
persistence: z
.enum(["stored", "withheld", "failed"])
.optional(),
})
.meta({ id: "DocumentSummaryResponse" }),
documentSummaryResponse,
"DocumentSummaryEnvelope",
),
},
},
},
...aiRunAccepted,
...aiExtractionRefusals("documentAi"),
...stdResponses,
},