mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 23:33:29 +00:00
feat(documents): read documents and lab scans in the background
"Read with AI" and the lab scan used to run their model calls inside the
request. At the default response time a read of three calls outlasted the
100 s a proxy in front of the server commonly allows, and the person saw a
cut connection for a read the server was still doing.
Both now run as a background run (`DocumentAiRun`, migration 0366):
- `POST /api/documents/inbound/{id}/index` with `Prefer: respond-async`
answers 202 with a run id once every quick refusal has passed. Without
the header it answers exactly as before, which the iPhone app relies on.
A second request while a read of the same document is queued or running
attaches to that run.
- `POST /api/labs/ocr/extract` always answers 202. Only the web client
calls it.
- `GET /api/ai-runs/{id}` serves the run: the same body the synchronous
route answers with, or the failure code and status it would have given.
Scoped to the caller; another account's run is a 404.
The worker (`document-ai-run`, a long queue with a one-hour expiry, one
job per run under `lockedPass`) claims the run, asks the capability again
for the record and re-checks the wire for the provider it picks, sets the
run's deadline from the person's AI response time and refuses a read that
cannot fit the job's expiry. Sync route and worker run one body per kind,
so the two paths cannot drift. Budget is reserved at enqueue and settled
once by whoever ends the run.
Input and result are sealed with labelled AES-256-GCM, registered for key
rotation; the input is dropped when the run ends. A five-minute reaper
fails a run no worker took within fifteen minutes (and hands its
reservation back), fails a run past its deadline, and deletes a finished
run after an hour. Runs are outside backups and inside the data wipe.
The web client polls through the query-key factory and says, calmly, that
the read continues in the background, and when no worker has picked it up.
This commit is contained in:
1 parent
556bd6d6cd
commit
0acf3da575
49 files changed
+4533
-870
No files matched your search
@@ -0,0 +1,82 @@
|
||||
/**
|
||||
* The HTTP edges of a background run: which requests asked for it, and the
|
||||
* 202 they get.
|
||||
*/
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { AiUnavailableError } from "@/lib/ai/capabilities/refusal";
|
||||
import {
|
||||
acceptedRunResponse,
|
||||
outcomeResponse,
|
||||
prefersRespondAsync,
|
||||
refusalAsFailure,
|
||||
workerUnavailableResponse,
|
||||
} from "@/lib/documents/ai-runs/http";
|
||||
|
||||
const req = (prefer?: string) =>
|
||||
new Request("http://localhost/x", {
|
||||
method: "POST",
|
||||
headers: prefer === undefined ? {} : { Prefer: prefer },
|
||||
});
|
||||
|
||||
describe("prefersRespondAsync", () => {
|
||||
it("reads RFC 7240 preferences, case-insensitively and among others", () => {
|
||||
expect(prefersRespondAsync(req("respond-async"))).toBe(true);
|
||||
expect(prefersRespondAsync(req("Respond-Async"))).toBe(true);
|
||||
expect(prefersRespondAsync(req("return=minimal, respond-async"))).toBe(
|
||||
true,
|
||||
);
|
||||
expect(prefersRespondAsync(req("respond-async; wait=10"))).toBe(true);
|
||||
});
|
||||
|
||||
it("keeps the synchronous path for every other request", () => {
|
||||
expect(prefersRespondAsync(req())).toBe(false);
|
||||
expect(prefersRespondAsync(req("return=minimal"))).toBe(false);
|
||||
expect(prefersRespondAsync(req("respond-asynchronously"))).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("acceptedRunResponse", () => {
|
||||
it("answers 202 with the run, the poll address and the applied preference", async () => {
|
||||
const res = acceptedRunResponse("run1");
|
||||
expect(res.status).toBe(202);
|
||||
expect(res.headers.get("Preference-Applied")).toBe("respond-async");
|
||||
expect(res.headers.get("Location")).toBe("/api/ai-runs/run1");
|
||||
expect(await res.json()).toEqual({
|
||||
data: { runId: "run1", status: "QUEUED", pollAfterMs: 1500 },
|
||||
error: null,
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
describe("outcomes", () => {
|
||||
it("renders a failure as the route's own envelope", async () => {
|
||||
const res = outcomeResponse({
|
||||
ok: false,
|
||||
status: 422,
|
||||
message: "Couldn't read the stored document.",
|
||||
errorCode: "documents.inbound.extractFailed",
|
||||
});
|
||||
expect(res.status).toBe(422);
|
||||
expect((await res.json()).meta).toEqual({
|
||||
errorCode: "documents.inbound.extractFailed",
|
||||
});
|
||||
});
|
||||
|
||||
it("keeps a capability refusal's status and code", () => {
|
||||
expect(
|
||||
refusalAsFailure(new AiUnavailableError("labsOcr", "consent_required")),
|
||||
).toEqual({
|
||||
status: 403,
|
||||
message: "AI consent is required for this feature",
|
||||
errorCode: "consent.ai.required",
|
||||
});
|
||||
expect(refusalAsFailure(new Error("x"))).toBeNull();
|
||||
});
|
||||
|
||||
it("names the missing worker", async () => {
|
||||
const res = workerUnavailableResponse();
|
||||
expect(res.status).toBe(503);
|
||||
expect((await res.json()).meta.errorCode).toBe("aiRuns.workerUnavailable");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,219 @@
|
||||
/**
|
||||
* The run service's reads and the reaper's decisions, with Prisma stubbed.
|
||||
* The integration file (`tests/integration/document-ai-runs.test.ts`) proves
|
||||
* the same against Postgres; this one pins the arithmetic and the branches.
|
||||
*/
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const findFirst = vi.fn();
|
||||
const findMany = vi.fn();
|
||||
const updateMany = vi.fn();
|
||||
const deleteMany = vi.fn();
|
||||
vi.mock("@/lib/db", () => ({
|
||||
prisma: {
|
||||
documentAiRun: {
|
||||
findFirst: (...a: unknown[]) => findFirst(...a),
|
||||
findMany: (...a: unknown[]) => findMany(...a),
|
||||
updateMany: (...a: unknown[]) => updateMany(...a),
|
||||
deleteMany: (...a: unknown[]) => deleteMany(...a),
|
||||
},
|
||||
},
|
||||
}));
|
||||
const reconcileSpend = vi.fn();
|
||||
vi.mock("@/lib/ai/coach/budget", () => ({
|
||||
reconcileSpend: (...a: unknown[]) => reconcileSpend(...a),
|
||||
}));
|
||||
|
||||
import { _resetCryptoCacheForTests, encryptBytes } from "@/lib/crypto";
|
||||
import { DOCUMENT_AI_RUN_RESULT_AAD } from "@/lib/crypto/encrypted-columns";
|
||||
import { readAiRunForUser, reapAiRuns } from "@/lib/documents/ai-runs/store";
|
||||
|
||||
const NOW = new Date("2027-01-15T10:00:00.000Z");
|
||||
const at = (msAgo: number) => new Date(NOW.getTime() - msAgo);
|
||||
|
||||
function row(overrides: Record<string, unknown>) {
|
||||
return {
|
||||
id: "r1",
|
||||
kind: "LABS_OCR_EXTRACT",
|
||||
documentId: null,
|
||||
status: "QUEUED",
|
||||
resultEncrypted: null,
|
||||
errorCode: null,
|
||||
errorStatus: null,
|
||||
errorMessage: null,
|
||||
createdAt: at(10_000),
|
||||
startedAt: null,
|
||||
finishedAt: null,
|
||||
expiresAt: new Date(NOW.getTime() + 60_000),
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
vi.stubEnv("ENCRYPTION_KEYS", "");
|
||||
vi.stubEnv("ENCRYPTION_ACTIVE_KEY_ID", "");
|
||||
vi.stubEnv("ENCRYPTION_KEY", "ab".repeat(32));
|
||||
_resetCryptoCacheForTests();
|
||||
vi.clearAllMocks();
|
||||
updateMany.mockResolvedValue({ count: 1 });
|
||||
deleteMany.mockResolvedValue({ count: 0 });
|
||||
});
|
||||
|
||||
describe("readAiRunForUser", () => {
|
||||
it("scopes the read to the caller", async () => {
|
||||
findFirst.mockResolvedValue(null);
|
||||
expect(await readAiRunForUser("u1", "r1", NOW)).toBeNull();
|
||||
expect(findFirst).toHaveBeenCalledWith(
|
||||
expect.objectContaining({ where: { id: "r1", userId: "u1" } }),
|
||||
);
|
||||
});
|
||||
|
||||
it("reports the queue wait and a poll interval that backs off", async () => {
|
||||
findFirst.mockResolvedValue(row({ createdAt: at(10_000) }));
|
||||
const early = await readAiRunForUser("u1", "r1", NOW);
|
||||
expect(early).toMatchObject({ status: "QUEUED", queuedForMs: 10_000 });
|
||||
expect(early?.retryAfterMs).toBe(1500 + 500);
|
||||
|
||||
findFirst.mockResolvedValue(row({ createdAt: at(10 * 60_000) }));
|
||||
const late = await readAiRunForUser("u1", "r1", NOW);
|
||||
expect(late?.retryAfterMs).toBe(5000);
|
||||
});
|
||||
|
||||
it("opens a result and stops the poll", async () => {
|
||||
const sealed = encryptBytes(
|
||||
Buffer.from(JSON.stringify({ rows: [], reportDate: null })),
|
||||
DOCUMENT_AI_RUN_RESULT_AAD,
|
||||
);
|
||||
findFirst.mockResolvedValue(
|
||||
row({
|
||||
status: "SUCCEEDED",
|
||||
resultEncrypted: new Uint8Array(sealed),
|
||||
finishedAt: at(1000),
|
||||
}),
|
||||
);
|
||||
expect(await readAiRunForUser("u1", "r1", NOW)).toMatchObject({
|
||||
status: "SUCCEEDED",
|
||||
result: { rows: [], reportDate: null },
|
||||
error: null,
|
||||
retryAfterMs: null,
|
||||
queuedForMs: null,
|
||||
});
|
||||
});
|
||||
|
||||
it("reports a result that no longer opens as a failure, never an empty success", async () => {
|
||||
findFirst.mockResolvedValue(
|
||||
row({
|
||||
status: "SUCCEEDED",
|
||||
resultEncrypted: new Uint8Array([1, 2, 3]),
|
||||
}),
|
||||
);
|
||||
expect(await readAiRunForUser("u1", "r1", NOW)).toMatchObject({
|
||||
status: "FAILED",
|
||||
result: null,
|
||||
error: { code: "aiRuns.failed", status: 500 },
|
||||
});
|
||||
});
|
||||
|
||||
it("hands back the route's own failure", async () => {
|
||||
findFirst.mockResolvedValue(
|
||||
row({
|
||||
status: "FAILED",
|
||||
errorCode: "labs.ocr.extractFailed",
|
||||
errorStatus: 422,
|
||||
errorMessage: "Couldn't read the report. Try a clearer photo.",
|
||||
}),
|
||||
);
|
||||
expect((await readAiRunForUser("u1", "r1", NOW))?.error).toEqual({
|
||||
code: "labs.ocr.extractFailed",
|
||||
status: 422,
|
||||
message: "Couldn't read the report. Try a clearer photo.",
|
||||
});
|
||||
});
|
||||
|
||||
it("treats a finished run past its retention as gone", async () => {
|
||||
findFirst.mockResolvedValue(row({ status: "FAILED", expiresAt: at(1) }));
|
||||
expect(await readAiRunForUser("u1", "r1", NOW)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("reapAiRuns", () => {
|
||||
it("fails a waiting run as worker-unavailable and refunds it, a running one as timed out", async () => {
|
||||
findMany.mockResolvedValue([
|
||||
{
|
||||
id: "q1",
|
||||
userId: "u1",
|
||||
status: "QUEUED",
|
||||
paramsJson: {
|
||||
mode: "vision",
|
||||
budget: { reserved: 8000, owner: "user", dateKey: "2027-01-15" },
|
||||
},
|
||||
},
|
||||
{
|
||||
id: "x1",
|
||||
userId: "u2",
|
||||
status: "RUNNING",
|
||||
paramsJson: { mode: "text" },
|
||||
},
|
||||
]);
|
||||
deleteMany.mockResolvedValue({ count: 4 });
|
||||
|
||||
expect(await reapAiRuns(NOW)).toEqual({
|
||||
workerUnavailable: 1,
|
||||
timedOut: 1,
|
||||
deleted: 4,
|
||||
});
|
||||
expect(updateMany).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
where: { id: "q1", status: "QUEUED" },
|
||||
data: expect.objectContaining({
|
||||
status: "FAILED",
|
||||
errorCode: "aiRuns.workerUnavailable",
|
||||
inputEncrypted: null,
|
||||
}),
|
||||
}),
|
||||
);
|
||||
expect(updateMany).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
where: { id: "x1", status: "RUNNING" },
|
||||
data: expect.objectContaining({ errorCode: "aiRuns.timedOut" }),
|
||||
}),
|
||||
);
|
||||
// Only the run nobody claimed is refunded; a running one's reservation
|
||||
// belongs to the worker that claimed it.
|
||||
expect(reconcileSpend).toHaveBeenCalledOnce();
|
||||
expect(reconcileSpend).toHaveBeenCalledWith(
|
||||
"u1",
|
||||
8000,
|
||||
0,
|
||||
"2027-01-15",
|
||||
0,
|
||||
{
|
||||
servedBy: null,
|
||||
reservedOwner: "user",
|
||||
},
|
||||
);
|
||||
expect(deleteMany).toHaveBeenCalledWith({
|
||||
where: {
|
||||
status: { in: ["SUCCEEDED", "FAILED"] },
|
||||
expiresAt: { lte: NOW },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it("does not refund a run another party ended first", async () => {
|
||||
findMany.mockResolvedValue([
|
||||
{
|
||||
id: "q1",
|
||||
userId: "u1",
|
||||
status: "QUEUED",
|
||||
paramsJson: {
|
||||
mode: "vision",
|
||||
budget: { reserved: 8000, owner: "user", dateKey: "2027-01-15" },
|
||||
},
|
||||
},
|
||||
]);
|
||||
updateMany.mockResolvedValue({ count: 0 });
|
||||
expect((await reapAiRuns(NOW)).workerUnavailable).toBe(0);
|
||||
expect(reconcileSpend).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,75 @@
|
||||
/**
|
||||
* The HTTP side of a background run: reading `Prefer: respond-async`, the 202
|
||||
* a route answers with, and turning a run body's outcome back into the
|
||||
* response the synchronous route has always given.
|
||||
*/
|
||||
import { apiError, apiSuccess } from "@/lib/api-response";
|
||||
import { AiUnavailableError } from "@/lib/ai/capabilities/refusal";
|
||||
|
||||
import type { AiRunFailure } from "./store";
|
||||
import {
|
||||
AI_RUN_ERROR_CODES,
|
||||
AI_RUN_POLL_AFTER_MS,
|
||||
type AiRunAccepted,
|
||||
type AiRunOutcome,
|
||||
} from "./types";
|
||||
|
||||
/**
|
||||
* Whether the request asked for the background path (RFC 7240). Without the
|
||||
* header the four document routes answer exactly as they always have, which
|
||||
* is what a client that has not adopted runs relies on.
|
||||
*/
|
||||
export function prefersRespondAsync(request: Request): boolean {
|
||||
const header = request.headers.get("prefer");
|
||||
if (!header) return false;
|
||||
return header
|
||||
.split(",")
|
||||
.some(
|
||||
(preference) =>
|
||||
preference.split(";")[0]?.trim().toLowerCase() === "respond-async",
|
||||
);
|
||||
}
|
||||
|
||||
/** The 202 for a queued run, with the poll address and the applied preference. */
|
||||
export function acceptedRunResponse(runId: string): Response {
|
||||
const body: AiRunAccepted = {
|
||||
runId,
|
||||
status: "QUEUED",
|
||||
pollAfterMs: AI_RUN_POLL_AFTER_MS,
|
||||
};
|
||||
const response = apiSuccess(body, 202);
|
||||
response.headers.set("Preference-Applied", "respond-async");
|
||||
response.headers.set("Location", `/api/ai-runs/${runId}`);
|
||||
return response;
|
||||
}
|
||||
|
||||
/** The answer when the run could not be handed to the background worker. */
|
||||
export function workerUnavailableResponse(): Response {
|
||||
return apiError(
|
||||
"The background worker is not available. Try again in a moment.",
|
||||
503,
|
||||
{ errorCode: AI_RUN_ERROR_CODES.workerUnavailable },
|
||||
);
|
||||
}
|
||||
|
||||
/** A run body's outcome as the synchronous route's response. */
|
||||
export function outcomeResponse<T>(outcome: AiRunOutcome<T>): Response {
|
||||
return outcome.ok
|
||||
? apiSuccess(outcome.data)
|
||||
: apiError(outcome.message, outcome.status, {
|
||||
errorCode: outcome.errorCode,
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* A capability refusal thrown inside a run, as the failure the route would
|
||||
* have rendered for it. Null for anything else.
|
||||
*/
|
||||
export function refusalAsFailure(error: unknown): AiRunFailure | null {
|
||||
if (!(error instanceof AiUnavailableError)) return null;
|
||||
return {
|
||||
status: error.status,
|
||||
message: error.message,
|
||||
errorCode: error.meta.errorCode,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,256 @@
|
||||
/**
|
||||
* "Read with AI" for one stored document: the body both the synchronous index
|
||||
* route and the background run execute, so the two paths cannot drift.
|
||||
*
|
||||
* Vision mode decrypts the stored original, makes one provider transcription
|
||||
* call against a reservation the caller already took, and indexes the text.
|
||||
* Text mode indexes text the browser read on the device (no provider call).
|
||||
* Both then record the attempt, lift an import's hold on automatic reading,
|
||||
* and continue into the same lab staging the automatic index worker runs.
|
||||
*
|
||||
* Every failure comes back as the outcome the route has always answered with
|
||||
* (status, message, `documents.inbound.*` code); the caller renders it as a
|
||||
* response or stores it on the run.
|
||||
*/
|
||||
import { AI_BUDGETS } from "@/lib/ai/ai-budgets";
|
||||
import type { ProviderChainType } from "@/lib/ai/provider-chain";
|
||||
import { auditLog } from "@/lib/auth/audit";
|
||||
import { prisma } from "@/lib/db";
|
||||
import {
|
||||
prepareVisionInput,
|
||||
refundDocumentAiSlot,
|
||||
type LoadedDocument,
|
||||
} from "@/lib/documents/ai-route-support";
|
||||
import { maybeAutoStageLabFacts } from "@/lib/documents/auto-stage-labs";
|
||||
import { upsertContentIndex } from "@/lib/documents/content-index";
|
||||
import {
|
||||
DocumentDescribeError,
|
||||
transcribeDocument,
|
||||
} from "@/lib/documents/describe";
|
||||
import { recordIndexAttempt } from "@/lib/documents/index-document";
|
||||
import type { requireDocumentVisionProvider } from "@/lib/documents/provider-order";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
|
||||
import { settleAiRunBudget } from "./store";
|
||||
import type {
|
||||
AiRunBudget,
|
||||
AiRunOutcome,
|
||||
DocumentIndexRunResult,
|
||||
} from "./types";
|
||||
|
||||
export type DocumentVisionPick = Awaited<
|
||||
ReturnType<typeof requireDocumentVisionProvider>
|
||||
>;
|
||||
|
||||
/**
|
||||
* The most sequential model calls one read makes: the transcription, then the
|
||||
* lab staging read with its one corrective retry.
|
||||
*/
|
||||
export const DOCUMENT_INDEX_MODEL_CALLS = 3;
|
||||
|
||||
/** The tokens a vision read reserves before it is dispatched. */
|
||||
export const DOCUMENT_INDEX_RESERVE_TOKENS =
|
||||
AI_BUDGETS.documentTranscribe.maxTokens;
|
||||
|
||||
/** Who asked: a request (with its client address) or a background run. */
|
||||
export interface IndexOrigin {
|
||||
ipAddress: string | null;
|
||||
worker: boolean;
|
||||
}
|
||||
|
||||
export type DocumentIndexInput =
|
||||
| { mode: "text"; text: string }
|
||||
| { mode: "vision"; pick: DocumentVisionPick; budget: AiRunBudget };
|
||||
|
||||
/** A failure in the shape the route would answer with (`errorCode` literal, so the catalogue guard reads it). */
|
||||
const failure = (f: {
|
||||
status: number;
|
||||
message: string;
|
||||
errorCode: string;
|
||||
}): AiRunOutcome<never> => ({ ok: false, ...f });
|
||||
|
||||
async function finishIndex(
|
||||
userId: string,
|
||||
documentId: string,
|
||||
source: "vision" | "text-ocr",
|
||||
tokenCount: number,
|
||||
origin: IndexOrigin,
|
||||
): Promise<AiRunOutcome<DocumentIndexRunResult>> {
|
||||
// Refs #776 — the manual read is the second writer of the attempt record
|
||||
// (the auto job + backfill share `indexLoadedDocument`): a success clears
|
||||
// any stored failure reason so the detail view stops explaining a problem
|
||||
// that no longer exists.
|
||||
await recordIndexAttempt(userId, documentId, {
|
||||
indexed: true,
|
||||
source,
|
||||
tokenCount,
|
||||
});
|
||||
// Read with AI is the person reading the document on purpose, so an
|
||||
// import's hold on automatic AI reading (`aiRead=defer`) ends here, before
|
||||
// the lab staging below that would otherwise refuse it.
|
||||
await prisma.inboundDocument.updateMany({
|
||||
where: { id: documentId, userId, aiReadDeferred: true },
|
||||
data: { aiReadDeferred: false },
|
||||
});
|
||||
await auditLog("documents.inbound.index", {
|
||||
userId,
|
||||
// A background run has no request left to attribute the action from.
|
||||
...(origin.worker ? { actorUserId: userId } : {}),
|
||||
ipAddress: origin.ipAddress,
|
||||
details: { documentId, source, tokens: tokenCount },
|
||||
});
|
||||
annotate({
|
||||
action: { name: "documents.contentIndex.upsert" },
|
||||
meta: { documentId, source, tokens: tokenCount },
|
||||
});
|
||||
// A manual read continues into the SAME lab staging the automatic index
|
||||
// worker performs, so a skipped or failed auto run is recoverable per
|
||||
// document without a re-upload. Every guard lives inside the helper (both
|
||||
// modules on, still STORED with no facts, provider + consent, looks like a
|
||||
// lab report) — a non-lab document is a tagged no-op, and a staging failure
|
||||
// never fails the index that just succeeded.
|
||||
const staging = await maybeAutoStageLabFacts(userId, documentId).catch(
|
||||
() => null,
|
||||
);
|
||||
const labFactsStaged = staging?.staged === true ? staging.facts : 0;
|
||||
return {
|
||||
ok: true,
|
||||
data: { documentId, indexed: true, tokenCount, labFactsStaged },
|
||||
};
|
||||
}
|
||||
|
||||
/** Index one owned document. The caller has authorised and charged the read. */
|
||||
export async function executeDocumentIndex(args: {
|
||||
userId: string;
|
||||
document: LoadedDocument;
|
||||
input: DocumentIndexInput;
|
||||
origin: IndexOrigin;
|
||||
}): Promise<AiRunOutcome<DocumentIndexRunResult>> {
|
||||
const { userId, document, input, origin } = args;
|
||||
|
||||
if (input.mode === "text") {
|
||||
const { tokenCount } = await upsertContentIndex({
|
||||
userId,
|
||||
documentId: document.id,
|
||||
text: input.text,
|
||||
source: "text-ocr",
|
||||
providerType: null,
|
||||
});
|
||||
return finishIndex(userId, document.id, "text-ocr", tokenCount, origin);
|
||||
}
|
||||
|
||||
const { pick, budget } = input;
|
||||
const servedBy = pick.entry.providerType as ProviderChainType;
|
||||
|
||||
const vision = await prepareVisionInput(document, pick.pdfSupported);
|
||||
if (!vision.ok) {
|
||||
// Preparation failed before any provider dispatch — the reservation and
|
||||
// the slot go back. Refs #776 — each failure is also recorded on the row
|
||||
// so the detail view can explain the missing index after the toast is
|
||||
// gone.
|
||||
await settleAiRunBudget(userId, budget, 0, null);
|
||||
await refundDocumentAiSlot(userId);
|
||||
if (vision.reason === "pdfNeedsAnthropic") {
|
||||
await recordIndexAttempt(userId, document.id, {
|
||||
indexed: false,
|
||||
reason: "pdf-needs-anthropic",
|
||||
});
|
||||
return failure({
|
||||
status: 422,
|
||||
message:
|
||||
"PDF scanning needs a Claude vision provider; use local OCR instead.",
|
||||
errorCode: "documents.inbound.pdfNeedsAnthropic",
|
||||
});
|
||||
}
|
||||
if (vision.reason === "rasterFailed") {
|
||||
await recordIndexAttempt(userId, document.id, {
|
||||
indexed: false,
|
||||
reason: "raster-failed",
|
||||
});
|
||||
return failure({
|
||||
status: 422,
|
||||
message: "The PDF pages couldn't be rendered for scanning.",
|
||||
errorCode: "documents.inbound.extractFailed",
|
||||
});
|
||||
}
|
||||
if (vision.reason === "fileType") {
|
||||
await recordIndexAttempt(userId, document.id, {
|
||||
indexed: false,
|
||||
reason: "local-unsupported",
|
||||
});
|
||||
return failure({
|
||||
status: 422,
|
||||
message: "This document can't be scanned. Use local OCR (text mode).",
|
||||
errorCode: "documents.inbound.fileType",
|
||||
});
|
||||
}
|
||||
await recordIndexAttempt(userId, document.id, {
|
||||
indexed: false,
|
||||
reason: "decrypt-error",
|
||||
});
|
||||
return failure({
|
||||
status: 422,
|
||||
message: "Couldn't read the stored document.",
|
||||
errorCode: "documents.inbound.extractFailed",
|
||||
});
|
||||
}
|
||||
|
||||
let text: string;
|
||||
try {
|
||||
({ text } = await transcribeDocument({
|
||||
provider: pick.entry.instance,
|
||||
providerType: pick.providerType,
|
||||
images: vision.images,
|
||||
documents: vision.documents,
|
||||
}));
|
||||
} catch (err) {
|
||||
await settleAiRunBudget(userId, budget, 0, null);
|
||||
await recordIndexAttempt(userId, document.id, {
|
||||
indexed: false,
|
||||
reason: "provider-error",
|
||||
});
|
||||
if (err instanceof DocumentDescribeError) {
|
||||
return failure({
|
||||
status: 422,
|
||||
message: "Couldn't read the document. Try a clearer copy.",
|
||||
errorCode: "documents.inbound.extractFailed",
|
||||
});
|
||||
}
|
||||
annotate({
|
||||
action: { name: "documents.contentIndex.failed" },
|
||||
meta: { reason: "provider_error", mode: "vision" },
|
||||
});
|
||||
return failure({
|
||||
status: 502,
|
||||
message: "Couldn't read the document. Try a clearer copy.",
|
||||
errorCode: "documents.inbound.extractFailed",
|
||||
});
|
||||
}
|
||||
await settleAiRunBudget(userId, budget, budget.reserved, servedBy);
|
||||
|
||||
// Refs #776 — the empty-transcription guard, same contract as the auto
|
||||
// path (`tryProviderIndex`): a provider answer with no text must never
|
||||
// become a "successful" empty index. The spend stays charged (the
|
||||
// provider was called); the honest answer is an error plus the recorded
|
||||
// reason.
|
||||
if (text.trim().length === 0) {
|
||||
await recordIndexAttempt(userId, document.id, {
|
||||
indexed: false,
|
||||
reason: "empty-transcription",
|
||||
});
|
||||
return failure({
|
||||
status: 422,
|
||||
message:
|
||||
"The provider returned no text for this document. Try a clearer copy.",
|
||||
errorCode: "documents.inbound.extractFailed",
|
||||
});
|
||||
}
|
||||
const { tokenCount } = await upsertContentIndex({
|
||||
userId,
|
||||
documentId: document.id,
|
||||
text,
|
||||
source: "vision",
|
||||
providerType: pick.providerType,
|
||||
});
|
||||
return finishIndex(userId, document.id, "vision", tokenCount, origin);
|
||||
}
|
||||
@@ -0,0 +1,86 @@
|
||||
/**
|
||||
* Start a background run from a route that has already authorised and
|
||||
* charged it: create the row, hand it to the worker, answer 202. When the
|
||||
* worker cannot be reached the run is failed on the spot, the reservation and
|
||||
* the rate slot go back, and the answer is 503, so nobody polls a run that
|
||||
* nothing will ever pick up.
|
||||
*/
|
||||
import type { Buffer } from "node:buffer";
|
||||
|
||||
import { prisma } from "@/lib/db";
|
||||
import { enqueueDocumentAiRun } from "@/lib/jobs/document-ai-run";
|
||||
import { annotate } from "@/lib/logging/context";
|
||||
|
||||
import { acceptedRunResponse, workerUnavailableResponse } from "./http";
|
||||
import { createAiRun, failAiRun, settleAiRunBudget } from "./store";
|
||||
import {
|
||||
AI_RUN_ERROR_CODES,
|
||||
type AiRunParams,
|
||||
type DocumentAiRunKindValue,
|
||||
} from "./types";
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*/
|
||||
export async function findLiveDocumentRun(
|
||||
userId: string,
|
||||
documentId: string,
|
||||
kind: DocumentAiRunKindValue,
|
||||
): Promise<string | null> {
|
||||
const row = await prisma.documentAiRun.findFirst({
|
||||
where: {
|
||||
userId,
|
||||
documentId,
|
||||
kind,
|
||||
status: { in: ["QUEUED", "RUNNING"] },
|
||||
expiresAt: { gt: new Date() },
|
||||
},
|
||||
select: { id: true },
|
||||
orderBy: { createdAt: "desc" },
|
||||
});
|
||||
return row?.id ?? null;
|
||||
}
|
||||
|
||||
export async function startAiRun(args: {
|
||||
userId: string;
|
||||
kind: DocumentAiRunKindValue;
|
||||
documentId?: string | null;
|
||||
params: AiRunParams;
|
||||
input?: Buffer | null;
|
||||
/** Hand the route's rate slot back when the run cannot start. */
|
||||
refundSlot: () => Promise<void>;
|
||||
}): Promise<Response> {
|
||||
const runId = await createAiRun({
|
||||
userId: args.userId,
|
||||
kind: args.kind,
|
||||
documentId: args.documentId ?? null,
|
||||
params: args.params,
|
||||
input: args.input ?? null,
|
||||
});
|
||||
const enqueued = await enqueueDocumentAiRun(runId, args.userId);
|
||||
if (!enqueued) {
|
||||
await failAiRun(
|
||||
runId,
|
||||
{
|
||||
status: 503,
|
||||
errorCode: AI_RUN_ERROR_CODES.workerUnavailable,
|
||||
message: "The background worker is not available.",
|
||||
},
|
||||
"QUEUED",
|
||||
);
|
||||
await settleAiRunBudget(args.userId, args.params.budget, 0, null);
|
||||
await args.refundSlot();
|
||||
annotate({
|
||||
action: { name: "ai_runs.worker_unavailable" },
|
||||
meta: { kind: args.kind },
|
||||
});
|
||||
return workerUnavailableResponse();
|
||||
}
|
||||
annotate({
|
||||
action: { name: "ai_runs.queued" },
|
||||
meta: { kind: args.kind, mode: args.params.mode },
|
||||
});
|
||||
return acceptedRunResponse(runId);
|
||||
}
|
||||
@@ -0,0 +1,358 @@
|
||||
/**
|
||||
* The `DocumentAiRun` row: create, claim, finish, fail, read, reap.
|
||||
*
|
||||
* Every state change is a conditional `updateMany` on the state it leaves, so
|
||||
* the worker, the reaper and a second delivery of the same job can never both
|
||||
* move one run: whoever matched the row did it, the rest see a count of zero.
|
||||
* The budget reservation taken at enqueue is settled exactly once, by the
|
||||
* party that ends the run (the worker after its provider call, or the reaper
|
||||
* for a run no worker ever picked up).
|
||||
*/
|
||||
import { Buffer } from "node:buffer";
|
||||
|
||||
import { Prisma } from "@/generated/prisma/client";
|
||||
import { reconcileSpend } from "@/lib/ai/coach/budget";
|
||||
import type { ProviderChainType } from "@/lib/ai/provider-chain";
|
||||
import { decryptBytes, encryptBytes } from "@/lib/crypto";
|
||||
import {
|
||||
DOCUMENT_AI_RUN_INPUT_AAD,
|
||||
DOCUMENT_AI_RUN_RESULT_AAD,
|
||||
} from "@/lib/crypto/encrypted-columns";
|
||||
import { prisma } from "@/lib/db";
|
||||
|
||||
import {
|
||||
AI_RUN_ERROR_CODES,
|
||||
AI_RUN_POLL_AFTER_MS,
|
||||
AI_RUN_QUEUE_WAIT_MS,
|
||||
AI_RUN_RETENTION_MS,
|
||||
type AiRunBudget,
|
||||
type AiRunDto,
|
||||
type AiRunParams,
|
||||
type AiRunResult,
|
||||
type DocumentAiRunKindValue,
|
||||
} from "./types";
|
||||
|
||||
/** The longest a client is told to wait between polls. */
|
||||
const MAX_POLL_INTERVAL_MS = 5000;
|
||||
|
||||
export interface CreateAiRunArgs {
|
||||
userId: string;
|
||||
kind: DocumentAiRunKindValue;
|
||||
documentId?: string | null;
|
||||
params: AiRunParams;
|
||||
/** The input only the run can read later: an upload, or browser-read text. */
|
||||
input?: Buffer | null;
|
||||
now?: Date;
|
||||
}
|
||||
|
||||
/** Insert a queued run. The caller enqueues the job right after. */
|
||||
export async function createAiRun(args: CreateAiRunArgs): Promise<string> {
|
||||
const now = args.now ?? new Date();
|
||||
const row = await prisma.documentAiRun.create({
|
||||
data: {
|
||||
userId: args.userId,
|
||||
kind: args.kind,
|
||||
documentId: args.documentId ?? null,
|
||||
status: "QUEUED",
|
||||
paramsJson: args.params as unknown as Prisma.InputJsonValue,
|
||||
inputEncrypted: args.input
|
||||
? new Uint8Array(encryptBytes(args.input, DOCUMENT_AI_RUN_INPUT_AAD))
|
||||
: null,
|
||||
createdAt: now,
|
||||
expiresAt: new Date(now.getTime() + AI_RUN_QUEUE_WAIT_MS),
|
||||
},
|
||||
select: { id: true },
|
||||
});
|
||||
return row.id;
|
||||
}
|
||||
|
||||
/** A run the worker has claimed, with its input opened. */
|
||||
export interface ClaimedAiRun {
|
||||
id: string;
|
||||
userId: string;
|
||||
kind: DocumentAiRunKindValue;
|
||||
documentId: string | null;
|
||||
params: AiRunParams;
|
||||
input: Buffer | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Move a queued run to RUNNING with the deadline the reaper enforces. Null
|
||||
* when the run is gone or no longer queued (a second delivery, or the reaper
|
||||
* failed it while it waited).
|
||||
*/
|
||||
export async function claimAiRun(
|
||||
id: string,
|
||||
runDeadline: Date,
|
||||
now: Date = new Date(),
|
||||
): Promise<ClaimedAiRun | null> {
|
||||
const moved = await prisma.documentAiRun.updateMany({
|
||||
where: { id, status: "QUEUED" },
|
||||
data: { status: "RUNNING", startedAt: now, expiresAt: runDeadline },
|
||||
});
|
||||
if (moved.count !== 1) return null;
|
||||
const row = await prisma.documentAiRun.findUnique({
|
||||
where: { id },
|
||||
select: {
|
||||
id: true,
|
||||
userId: true,
|
||||
kind: true,
|
||||
documentId: true,
|
||||
paramsJson: true,
|
||||
inputEncrypted: true,
|
||||
},
|
||||
});
|
||||
if (!row) return null;
|
||||
let input: Buffer | null = null;
|
||||
if (row.inputEncrypted) {
|
||||
input = decryptBytes(
|
||||
Buffer.from(row.inputEncrypted),
|
||||
DOCUMENT_AI_RUN_INPUT_AAD,
|
||||
);
|
||||
}
|
||||
return {
|
||||
id: row.id,
|
||||
userId: row.userId,
|
||||
kind: row.kind,
|
||||
documentId: row.documentId,
|
||||
params: row.paramsJson as unknown as AiRunParams,
|
||||
input,
|
||||
};
|
||||
}
|
||||
|
||||
/** Store the result and drop the input. False when the run was already ended. */
|
||||
export async function completeAiRun(
|
||||
id: string,
|
||||
result: AiRunResult,
|
||||
now: Date = new Date(),
|
||||
): Promise<boolean> {
|
||||
const sealed = encryptBytes(
|
||||
Buffer.from(JSON.stringify(result), "utf8"),
|
||||
DOCUMENT_AI_RUN_RESULT_AAD,
|
||||
);
|
||||
const moved = await prisma.documentAiRun.updateMany({
|
||||
where: { id, status: "RUNNING" },
|
||||
data: {
|
||||
status: "SUCCEEDED",
|
||||
resultEncrypted: new Uint8Array(sealed),
|
||||
inputEncrypted: null,
|
||||
finishedAt: now,
|
||||
expiresAt: new Date(now.getTime() + AI_RUN_RETENTION_MS),
|
||||
},
|
||||
});
|
||||
return moved.count === 1;
|
||||
}
|
||||
|
||||
export interface AiRunFailure {
|
||||
status: number;
|
||||
message: string;
|
||||
errorCode: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Fail a run that is still queued or running and drop its input. False when
|
||||
* another party ended it first.
|
||||
*/
|
||||
export async function failAiRun(
|
||||
id: string,
|
||||
failure: AiRunFailure,
|
||||
from: "QUEUED" | "RUNNING" | "ANY" = "ANY",
|
||||
now: Date = new Date(),
|
||||
): Promise<boolean> {
|
||||
const moved = await prisma.documentAiRun.updateMany({
|
||||
where: {
|
||||
id,
|
||||
status: from === "ANY" ? { in: ["QUEUED", "RUNNING"] } : from,
|
||||
},
|
||||
data: {
|
||||
status: "FAILED",
|
||||
errorCode: failure.errorCode,
|
||||
errorStatus: failure.status,
|
||||
errorMessage: failure.message,
|
||||
inputEncrypted: null,
|
||||
finishedAt: now,
|
||||
expiresAt: new Date(now.getTime() + AI_RUN_RETENTION_MS),
|
||||
},
|
||||
});
|
||||
return moved.count === 1;
|
||||
}
|
||||
|
||||
/**
|
||||
* Settle the reservation taken at enqueue. `servedBy` null with `actual` 0
|
||||
* hands it back in full. Best effort: the run's own state matters more than
|
||||
* the meter.
|
||||
*/
|
||||
export async function settleAiRunBudget(
|
||||
userId: string,
|
||||
budget: AiRunBudget | undefined,
|
||||
actual: number,
|
||||
servedBy: ProviderChainType | null,
|
||||
): Promise<void> {
|
||||
if (!budget || budget.reserved <= 0) return;
|
||||
try {
|
||||
await reconcileSpend(userId, budget.reserved, actual, budget.dateKey, 0, {
|
||||
servedBy,
|
||||
reservedOwner: budget.owner,
|
||||
});
|
||||
} catch {
|
||||
// The run's outcome is already decided; a failed refund is not a reason
|
||||
// to change it.
|
||||
}
|
||||
}
|
||||
|
||||
function openResult(sealed: Uint8Array | null): AiRunResult | null {
|
||||
if (!sealed) return null;
|
||||
try {
|
||||
const plain = decryptBytes(Buffer.from(sealed), DOCUMENT_AI_RUN_RESULT_AAD);
|
||||
return JSON.parse(plain.toString("utf8")) as AiRunResult;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* One run as its owner sees it, or null when it does not exist, belongs to
|
||||
* somebody else, or has outlived its retention (the reaper may not have
|
||||
* deleted it yet; it is gone either way).
|
||||
*/
|
||||
export async function readAiRunForUser(
|
||||
userId: string,
|
||||
id: string,
|
||||
now: Date = new Date(),
|
||||
): Promise<AiRunDto | null> {
|
||||
const row = await prisma.documentAiRun.findFirst({
|
||||
where: { id, userId },
|
||||
select: {
|
||||
id: true,
|
||||
kind: true,
|
||||
documentId: true,
|
||||
status: true,
|
||||
resultEncrypted: true,
|
||||
errorCode: true,
|
||||
errorStatus: true,
|
||||
errorMessage: true,
|
||||
createdAt: true,
|
||||
startedAt: true,
|
||||
finishedAt: true,
|
||||
expiresAt: true,
|
||||
},
|
||||
});
|
||||
if (!row) return null;
|
||||
const terminal = row.status === "SUCCEEDED" || row.status === "FAILED";
|
||||
if (terminal && row.expiresAt.getTime() <= now.getTime()) return null;
|
||||
|
||||
const result =
|
||||
row.status === "SUCCEEDED" ? openResult(row.resultEncrypted) : null;
|
||||
// A result that no longer opens (a key rotated away under it) is reported
|
||||
// as a failure rather than as a success with nothing in it.
|
||||
const unreadable = row.status === "SUCCEEDED" && result === null;
|
||||
const age = now.getTime() - row.createdAt.getTime();
|
||||
const sinceStart = row.startedAt
|
||||
? now.getTime() - row.startedAt.getTime()
|
||||
: 0;
|
||||
return {
|
||||
id: row.id,
|
||||
kind: row.kind,
|
||||
documentId: row.documentId,
|
||||
status: unreadable ? "FAILED" : row.status,
|
||||
result,
|
||||
error:
|
||||
row.status === "FAILED" || unreadable
|
||||
? {
|
||||
code: unreadable
|
||||
? AI_RUN_ERROR_CODES.failed
|
||||
: (row.errorCode ?? AI_RUN_ERROR_CODES.failed),
|
||||
message: unreadable
|
||||
? "The result of this run can no longer be read."
|
||||
: (row.errorMessage ?? "The run failed."),
|
||||
status: unreadable ? 500 : (row.errorStatus ?? 500),
|
||||
}
|
||||
: null,
|
||||
createdAt: row.createdAt.toISOString(),
|
||||
startedAt: row.startedAt?.toISOString() ?? null,
|
||||
finishedAt: row.finishedAt?.toISOString() ?? null,
|
||||
queuedForMs: row.status === "QUEUED" ? Math.max(0, age) : null,
|
||||
retryAfterMs: terminal
|
||||
? null
|
||||
: Math.min(
|
||||
MAX_POLL_INTERVAL_MS,
|
||||
// Poll briskly at first, then back off: most reads finish within
|
||||
// seconds, and a slow local model can take minutes.
|
||||
AI_RUN_POLL_AFTER_MS + Math.floor(Math.max(age, sinceStart) / 20),
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
export interface ReapSummary {
|
||||
workerUnavailable: number;
|
||||
timedOut: number;
|
||||
deleted: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* The reaper's one pass, keyed on `expiresAt`, which always holds the next
|
||||
* deadline of a run:
|
||||
*
|
||||
* - QUEUED past it: no worker picked the run up. Failed as
|
||||
* `aiRuns.workerUnavailable`, and its reservation is handed back.
|
||||
* - RUNNING past it: the run outlived every model call it was allowed.
|
||||
* Failed as `aiRuns.timedOut`. The reservation stays with the worker that
|
||||
* claimed it; a worker that died with it leaves it charged, the cautious
|
||||
* direction for a meter.
|
||||
* - SUCCEEDED / FAILED past it: an hour after it finished. Deleted.
|
||||
*/
|
||||
export async function reapAiRuns(
|
||||
now: Date = new Date(),
|
||||
batch = 500,
|
||||
): Promise<ReapSummary> {
|
||||
const summary: ReapSummary = {
|
||||
workerUnavailable: 0,
|
||||
timedOut: 0,
|
||||
deleted: 0,
|
||||
};
|
||||
|
||||
const stuck = await prisma.documentAiRun.findMany({
|
||||
where: { status: { in: ["QUEUED", "RUNNING"] }, expiresAt: { lte: now } },
|
||||
select: { id: true, userId: true, status: true, paramsJson: true },
|
||||
orderBy: { expiresAt: "asc" },
|
||||
take: batch,
|
||||
});
|
||||
for (const run of stuck) {
|
||||
if (run.status === "QUEUED") {
|
||||
const failed = await failAiRun(
|
||||
run.id,
|
||||
{
|
||||
status: 503,
|
||||
errorCode: AI_RUN_ERROR_CODES.workerUnavailable,
|
||||
message:
|
||||
"No background worker picked this up. Ask the server operator to check the worker.",
|
||||
},
|
||||
"QUEUED",
|
||||
now,
|
||||
);
|
||||
if (failed) {
|
||||
summary.workerUnavailable += 1;
|
||||
const params = run.paramsJson as unknown as AiRunParams | null;
|
||||
await settleAiRunBudget(run.userId, params?.budget, 0, null);
|
||||
}
|
||||
} else {
|
||||
const failed = await failAiRun(
|
||||
run.id,
|
||||
{
|
||||
status: 504,
|
||||
errorCode: AI_RUN_ERROR_CODES.timedOut,
|
||||
message: "Reading took longer than the AI response time allows.",
|
||||
},
|
||||
"RUNNING",
|
||||
now,
|
||||
);
|
||||
if (failed) summary.timedOut += 1;
|
||||
}
|
||||
}
|
||||
|
||||
const gone = await prisma.documentAiRun.deleteMany({
|
||||
where: { status: { in: ["SUCCEEDED", "FAILED"] }, expiresAt: { lte: now } },
|
||||
});
|
||||
summary.deleted = gone.count;
|
||||
return summary;
|
||||
}
|
||||
@@ -0,0 +1,109 @@
|
||||
/**
|
||||
* The shapes a background document AI run carries: its kinds and states, the
|
||||
* outcome a run body returns, the error codes only a run can produce, and the
|
||||
* DTO the poll route publishes.
|
||||
*
|
||||
* A run is a ticket. The request that asked for the read answers 202 with the
|
||||
* run id, the worker does the read, and the client polls
|
||||
* `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 { OcrExtractResponseDto } from "@/lib/validations/labs-ocr";
|
||||
|
||||
export const DOCUMENT_AI_RUN_KINDS = [
|
||||
"DOCUMENT_INDEX",
|
||||
"LABS_OCR_EXTRACT",
|
||||
] as const;
|
||||
export type DocumentAiRunKindValue = (typeof DOCUMENT_AI_RUN_KINDS)[number];
|
||||
|
||||
export const DOCUMENT_AI_RUN_STATUSES = [
|
||||
"QUEUED",
|
||||
"RUNNING",
|
||||
"SUCCEEDED",
|
||||
"FAILED",
|
||||
] as const;
|
||||
export type DocumentAiRunStatusValue =
|
||||
(typeof DOCUMENT_AI_RUN_STATUSES)[number];
|
||||
|
||||
/**
|
||||
* The codes only a background run produces. Every other failure a run
|
||||
* reports carries the code its synchronous route answers with, so a client
|
||||
* maps both paths through one table.
|
||||
*/
|
||||
export const AI_RUN_ERROR_CODES = {
|
||||
notFound: "aiRuns.notFound",
|
||||
workerUnavailable: "aiRuns.workerUnavailable",
|
||||
timedOut: "aiRuns.timedOut",
|
||||
failed: "aiRuns.failed",
|
||||
} as const;
|
||||
|
||||
/** How long a queued run waits for a worker before it is failed. */
|
||||
export const AI_RUN_QUEUE_WAIT_MS = 15 * 60 * 1000;
|
||||
|
||||
/** How long a finished run stays readable before the reaper deletes it. */
|
||||
export const AI_RUN_RETENTION_MS = 60 * 60 * 1000;
|
||||
|
||||
/** Room a running run gets on top of its model calls (decrypt, raster, write). */
|
||||
export const AI_RUN_MARGIN_MS = 60 * 1000;
|
||||
|
||||
/** The interval the 202 tells a client to wait before its first poll. */
|
||||
export const AI_RUN_POLL_AFTER_MS = 1500;
|
||||
|
||||
/** The budget reservation taken at enqueue, settled by whoever ends the run. */
|
||||
export interface AiRunBudget {
|
||||
reserved: number;
|
||||
owner: "operator" | "user";
|
||||
dateKey: string;
|
||||
}
|
||||
|
||||
/** What a run needs to know to run. Never health data. */
|
||||
export interface AiRunParams {
|
||||
/** `vision` reads the stored original or the uploaded scan; `text` reads text the browser read. */
|
||||
mode: "vision" | "text";
|
||||
/** The sniffed MIME of an uploaded scan (lab scan, vision mode only). */
|
||||
mime?: "image/jpeg" | "image/png" | "image/webp" | "application/pdf";
|
||||
/** Present when the enqueue reserved budget for a provider call. */
|
||||
budget?: AiRunBudget;
|
||||
}
|
||||
|
||||
/** "Read with AI": the same body the synchronous index route answers with. */
|
||||
export interface DocumentIndexRunResult {
|
||||
documentId: string;
|
||||
indexed: true;
|
||||
tokenCount: number;
|
||||
labFactsStaged: number;
|
||||
}
|
||||
|
||||
export type AiRunResult = DocumentIndexRunResult | OcrExtractResponseDto;
|
||||
|
||||
/**
|
||||
* What one run body produced: the success body, or the failure the
|
||||
* synchronous route would have answered with.
|
||||
*/
|
||||
export type AiRunOutcome<T> =
|
||||
| { ok: true; data: T }
|
||||
| { ok: false; status: number; message: string; errorCode: string };
|
||||
|
||||
/** The poll route's body. */
|
||||
export interface AiRunDto {
|
||||
id: string;
|
||||
kind: DocumentAiRunKindValue;
|
||||
documentId: string | null;
|
||||
status: DocumentAiRunStatusValue;
|
||||
result: AiRunResult | null;
|
||||
error: { code: string; message: string; status: number } | null;
|
||||
createdAt: string;
|
||||
startedAt: string | null;
|
||||
finishedAt: string | null;
|
||||
/** How long the run has waited for a worker, while it is still queued. */
|
||||
queuedForMs: number | null;
|
||||
/** When to ask again, while the run is not terminal. */
|
||||
retryAfterMs: number | null;
|
||||
}
|
||||
|
||||
/** The 202 body. */
|
||||
export interface AiRunAccepted {
|
||||
runId: string;
|
||||
status: "QUEUED";
|
||||
pollAfterMs: number;
|
||||
}
|
||||
Reference in new issue
Block a user