Files
HealthLog/src/lib/jobs/document-index.ts
T
Marc-André Bombeck d3257a1b6b fix(documents): tell people when the document reader is busy, and attribute its work
A read a person started now runs as interactive work of their account, and
the document jobs as background work of theirs, so the reader's queue can
order and cap them. When the reader is busy or stopped before it answered,
a lab scan, label read or document read fails with aiRuns.readerBusy (503,
nothing read or charged) instead of a misleading unreadable-file error, and
the index and summary jobs throw so the queue runs them again rather than
recording an outcome about the document.
2026-10-25 17:38:25 +01:00

144 lines
5.7 KiB
TypeScript

/**
* Automatic per-document content indexing, enqueued the moment a document is
* stored (`POST /api/documents/inbound`). Fire-and-forget: the upload response
* never blocks on or fails because of indexing.
*
* The job runs the shared AI-first decision tree (`indexDocumentContent`):
* provider (vision) first when one is configured + consented, else local
* text-layer extraction. Owner-scoped; the provider path is consent + budget
* gated; the local path needs neither (no egress). Serial concurrency keeps the
* provider calls + PDF parsing off the request pool.
*
* The queue MUST be registered in the maintenance registrar
* (`src/lib/jobs/reminder/register-maintenance.ts`) so pg-boss provisions it.
*/
import { STATUS_MODEL_CALLS } from "@/lib/ai/ai-budgets";
import { maybeAutoStageLabFacts } from "@/lib/documents/auto-stage-labs";
import { indexDocumentContent } from "@/lib/documents/index-document";
import { withPdfWork } from "@/lib/documents/pdf-isolation";
import type { OcrSchedule } from "@/lib/documents/ocr-plan";
import { ocrReadCallMs } from "@/lib/documents/ocr-read";
import { prisma } from "@/lib/db";
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
import { annotate } from "@/lib/logging/context";
import { caughtAs, logCaught } from "@/lib/logging/signal";
import {
DOCUMENT_INDEX_EXPIRE_SECONDS,
DOCUMENT_INDEX_QUEUE,
} from "./document-index-queue";
export interface DocumentIndexPayload {
userId: string;
documentId: string;
enqueuedAt?: string;
/**
* v1.39.2 (#1038) — set for an upload that asked for `aiRead=defer`: index
* from the local text layer only and stage no lab facts. Absent on every
* job enqueued before the field existed, which keeps their behaviour.
*/
localOnly?: boolean;
}
/**
* Index one document (owner-scoped, provider-first/local-fallback). Never
* throws for an expected outcome — the decision tree returns a tagged result —
* so pg-boss does not retry a document that simply has no indexable text.
*/
export async function runDocumentIndex(
payload: DocumentIndexPayload,
options: { deadlineAt?: number; now?: () => number } = {},
): Promise<void> {
const { userId, documentId } = payload;
if (!userId || !documentId) return;
const localOnly = payload.localOnly === true;
const outcome = await withPdfWork({ owner: userId, lane: "background" }, () =>
indexDocumentContent(userId, documentId, { localOnly }),
);
annotate({
action: { name: "documents.autoIndex.run" },
meta: outcome.indexed
? { documentId, indexed: true, source: outcome.source }
: { documentId, indexed: false, reason: outcome.reason },
});
// Once the document is indexed, auto-stage lab facts for a lab-looking
// document (both modules on + the auto-AI-read consent gate). Facts land
// PENDING for the existing human review; nothing is committed. Fully gated +
// idempotent inside; a failure here must never fail the index job, so it is
// swallowed to a no-op (the manual extract button remains the fallback).
// A deferred import stages nothing: lab staging is an AI read, and the
// person asked for those to wait.
if (outcome.indexed && !localOnly) {
const schedule =
options.deadlineAt === undefined
? undefined
: await stagingSchedule(userId, options.deadlineAt, options.now);
await withPdfWork({ owner: userId, lane: "background" }, () =>
maybeAutoStageLabFacts(userId, documentId, { schedule }),
).catch(caughtAs("documents.auto_index.lab_staging_failed"));
}
}
/**
* The lab staging's reads, planned against the job's deadline. One call of a
* read may take the person's timeout twice (the call and the one repeat a
* thinking model gets), so that is the unit the deadline is divided by.
* There is no run row to move: the deadline is the job's own, fixed.
*/
export async function stagingSchedule(
userId: string,
deadlineAt: number,
now: () => number = Date.now,
): Promise<OcrSchedule> {
const owner = await prisma.user.findUnique({
where: { id: userId },
select: { aiResponseTimeoutSeconds: true },
});
const perCallMs =
ocrReadCallMs(owner?.aiResponseTimeoutSeconds ?? null) * STATUS_MODEL_CALLS;
return {
maxModelCalls: () => Math.floor((deadlineAt - now()) / perCallMs),
arm: async () => {},
};
}
/**
* Enqueue a per-document index job. Coalesced by `singletonKey` per document so
* a duplicate/idempotent re-upload cannot pile up parallel runs. Fire-and-
* forget — a missing boss (worker not up) is a no-op, and a `boss.send` failure
* (a transient DB hiccup) is swallowed to a no-op too, so enqueue can NEVER fail
* an already-stored upload. Indexing is a background nicety; the stored document
* is the contract. A dropped enqueue is recoverable via the corpus backfill.
*/
export async function enqueueDocumentIndex(
userId: string,
documentId: string,
options: { localOnly?: boolean } = {},
): Promise<{ enqueued: boolean }> {
const boss = getGlobalBoss();
if (!boss) return { enqueued: false };
const payload: DocumentIndexPayload = {
userId,
documentId,
enqueuedAt: new Date().toISOString(),
...(options.localOnly ? { localOnly: true } : {}),
};
try {
const jobId = await boss.send(DOCUMENT_INDEX_QUEUE, payload, {
retryLimit: 2,
retryDelay: 30,
retryBackoff: true,
singletonKey: `document-index|${documentId}`,
expireInSeconds: DOCUMENT_INDEX_EXPIRE_SECONDS,
});
return { enqueued: Boolean(jobId) };
} catch (err) {
annotate({
action: { name: "documents.autoIndex.enqueueFailed" },
meta: { documentId, reason: err instanceof Error ? err.name : "unknown" },
});
logCaught("documents.auto_index.enqueue_failed", err);
return { enqueued: false };
}
}