mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 15:23:29 +00:00
"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.
231 lines
8.2 KiB
TypeScript
231 lines
8.2 KiB
TypeScript
"use client";
|
|
|
|
/**
|
|
* v1.27.22 (Document vault P2) — client hooks for the review-first AI layer on
|
|
* a stored document: the shared capability probe, filing-metadata suggestions,
|
|
* and the session-only summary / extracted text.
|
|
*
|
|
* Every affordance is gated on `usage.assistAvailable` at the call site; these
|
|
* hooks only RUN the call once the surface has decided to offer it. The
|
|
* transport (VISION vs local-OCR TEXT) comes from `document-ai-transport`.
|
|
*
|
|
* NOTHING here writes a document row. Suggestions are drafts the detail sheet
|
|
* prefills; the summary is transient. The only mutation is the caller applying
|
|
* a reviewed draft through the existing edit-on-commit machinery.
|
|
*/
|
|
import { useCallback } from "react";
|
|
|
|
import { useMutation, useQuery } from "@tanstack/react-query";
|
|
|
|
import { useAiProviderState } from "@/hooks/use-ai-capability";
|
|
import { apiGet, ApiError } from "@/lib/api/api-fetch";
|
|
import { useTranslations } from "@/lib/i18n/context";
|
|
import { queryKeys } from "@/lib/query-keys";
|
|
import type {
|
|
DocumentAiCapabilityDto,
|
|
DocumentSuggestionDto,
|
|
DocumentSummaryMode,
|
|
} from "@/lib/validations/inbound-documents";
|
|
|
|
import {
|
|
DocumentAssistClientError,
|
|
runDocumentAi,
|
|
type DocumentAiMode,
|
|
type DocumentAiTarget,
|
|
} from "./document-ai-transport";
|
|
|
|
/** The describe result: raw text, or a summary plus its storage outcome. */
|
|
export type DocumentDescribeResult =
|
|
| {
|
|
summary: string;
|
|
persistence?: "stored" | "withheld" | "failed";
|
|
}
|
|
| { text: string };
|
|
|
|
/**
|
|
* The document-scoped AI capability probe (`/api/documents/inbound/capability`).
|
|
* Resolved over the DOCUMENT provider order (local-first, codex last), so the
|
|
* transport `mode` + PDF support match what the document routes do, and it
|
|
* carries the vendor-blind `egress` class the detail sheet uses to warn before a
|
|
* read leaves the machine. Availability of the affordance itself is still gated
|
|
* on `usage.assistAvailable`.
|
|
*/
|
|
export function useDocumentAiCapability(enabled: boolean) {
|
|
return useQuery<DocumentAiCapabilityDto>({
|
|
queryKey: queryKeys.inboundDocumentAiCapability(),
|
|
queryFn: () =>
|
|
apiGet<DocumentAiCapabilityDto>("/api/documents/inbound/capability"),
|
|
enabled,
|
|
staleTime: 60_000,
|
|
});
|
|
}
|
|
|
|
/** The per-user "read documents automatically with AI" opt-in. */
|
|
export interface DocumentsAutoAiReadPref {
|
|
documentsAutoAiRead: boolean;
|
|
}
|
|
|
|
/**
|
|
* Read the per-user auto-AI-read flag (`GET /api/auth/me/documents-auto-ai-read`).
|
|
* Shares the cache key with the AI-settings toggle, so a flip there and this
|
|
* read stay in lockstep. When ON, reading happens automatically on upload and
|
|
* the detail sheet drops the manual per-document AI action row.
|
|
*/
|
|
export function useDocumentsAutoAiRead(enabled: boolean) {
|
|
return useQuery<DocumentsAutoAiReadPref>({
|
|
queryKey: queryKeys.documentsAutoAiRead(),
|
|
queryFn: () =>
|
|
apiGet<DocumentsAutoAiReadPref>("/api/auth/me/documents-auto-ai-read"),
|
|
enabled,
|
|
staleTime: 60_000,
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Suggest filing metadata for a stored document. Returns DRAFTS only — the
|
|
* detail sheet prefills its edit fields and the user saves; this call writes
|
|
* nothing.
|
|
*/
|
|
export function useSuggestDetails() {
|
|
const { responseTimeoutMs } = useAiProviderState();
|
|
return useMutation<
|
|
DocumentSuggestionDto,
|
|
Error,
|
|
{ mode: DocumentAiMode; target: DocumentAiTarget }
|
|
>({
|
|
mutationFn: async ({ mode, target }) => {
|
|
const data = await runDocumentAi<{ suggestions: DocumentSuggestionDto }>({
|
|
path: `/api/documents/inbound/${target.documentId}/suggest`,
|
|
mode,
|
|
target,
|
|
responseTimeoutMs,
|
|
modelCalls: 1,
|
|
});
|
|
return data.suggestions;
|
|
},
|
|
});
|
|
}
|
|
|
|
/**
|
|
* On-demand summary or extracted text. Both stay transient unless the document
|
|
* summary block explicitly requests persistence or replacement.
|
|
*/
|
|
export function useDocumentSummary() {
|
|
const { responseTimeoutMs } = useAiProviderState();
|
|
return useMutation<
|
|
DocumentDescribeResult,
|
|
Error,
|
|
{
|
|
mode: DocumentAiMode;
|
|
target: DocumentAiTarget;
|
|
output: DocumentSummaryMode;
|
|
persist?: boolean;
|
|
replace?: boolean;
|
|
}
|
|
>({
|
|
mutationFn: ({ mode, target, output, persist = false, replace = false }) =>
|
|
runDocumentAi<DocumentDescribeResult>({
|
|
path: `/api/documents/inbound/${target.documentId}/summary?mode=${output}${persist ? "&persist=true" : ""}${replace ? "&replace=true" : ""}`,
|
|
mode,
|
|
target,
|
|
responseTimeoutMs,
|
|
modelCalls: 1,
|
|
}),
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Map an AI error to a translation key. Server errors carry a stable
|
|
* `meta.errorCode`; client-side precondition failures carry a `reason`. The
|
|
* default is the calm "try again" message — never a raw provider string.
|
|
*/
|
|
/**
|
|
* The actual wait, in whole minutes, behind a document-AI 429. The routes
|
|
* mirror the bucket's reset instant into the error meta (`retryAt`, ISO 8601);
|
|
* the window is an hour, so a fixed "try again in a few minutes" understated
|
|
* the wait for most of it. Null when the error is not a document-AI rate-limit
|
|
* response or carries no usable instant — the caller falls back to the generic
|
|
* copy. Floored at one minute: a reset seconds away still reads as "about
|
|
* 1 minute", never "0 minutes".
|
|
*/
|
|
export function documentAiRetryMinutes(err: unknown): number | null {
|
|
if (!(err instanceof ApiError)) return null;
|
|
if (err.meta?.errorCode !== "documents.inbound.rateLimited") return null;
|
|
const raw = err.meta?.retryAt;
|
|
if (typeof raw !== "string") return null;
|
|
const at = Date.parse(raw);
|
|
if (!Number.isFinite(at)) return null;
|
|
return Math.max(1, Math.ceil((at - Date.now()) / 60_000));
|
|
}
|
|
|
|
/**
|
|
* Resolve a document-AI error to the user-facing sentence. Rate-limited
|
|
* responses derive their copy from the ACTUAL reset instant ("try again in
|
|
* about N minutes"); everything else maps through `documentAiErrorKey`. The
|
|
* result is final text — callers render or toast it as-is.
|
|
*/
|
|
export function useDocumentAiErrorText(): (err: unknown) => string {
|
|
const { t, tCount } = useTranslations();
|
|
return useCallback(
|
|
(err: unknown) => {
|
|
const minutes = documentAiRetryMinutes(err);
|
|
if (minutes !== null) {
|
|
return tCount("documents.assist.errorRateLimitedWait", minutes);
|
|
}
|
|
return t(documentAiErrorKey(err));
|
|
},
|
|
[t, tCount],
|
|
);
|
|
}
|
|
|
|
export function documentAiErrorKey(err: unknown): string {
|
|
if (err instanceof DocumentAssistClientError) {
|
|
switch (err.reason) {
|
|
case "textImageOnly":
|
|
return "documents.assist.errorTextImageOnly";
|
|
case "ocr":
|
|
return "documents.assist.errorOcr";
|
|
default:
|
|
return "documents.assist.errorGeneric";
|
|
}
|
|
}
|
|
if (err instanceof ApiError) {
|
|
const code =
|
|
typeof err.meta?.errorCode === "string" ? err.meta.errorCode : "";
|
|
switch (code) {
|
|
case "documents.inbound.rateLimited":
|
|
return "documents.assist.errorRateLimited";
|
|
case "documents.inbound.budgetExceeded":
|
|
return "documents.assist.errorBudget";
|
|
case "documents.inbound.pdfNeedsAnthropic":
|
|
return "documents.assist.errorPdfNeedsVision";
|
|
case "documents.inbound.fileType":
|
|
return "documents.assist.errorFileType";
|
|
case "documents.inbound.localOcrDisabled":
|
|
return "documents.assist.errorLocalOcrDisabled";
|
|
case "documents.inbound.providerUnsupported":
|
|
return "documents.assist.errorProvider";
|
|
case "documents.inbound.notIndexed":
|
|
return "documents.assist.errorNotIndexed";
|
|
case "aiRuns.workerUnavailable":
|
|
return "aiRuns.errorWorkerUnavailable";
|
|
case "aiRuns.timedOut":
|
|
return "aiRuns.errorTimedOut";
|
|
case "consent.ai.required":
|
|
return "documents.assist.errorConsent";
|
|
case "ai.provider.none":
|
|
return "documents.assist.errorProvider";
|
|
case "ai.record.notPermitted":
|
|
case "module.disabled":
|
|
return "documents.assist.errorUnavailable";
|
|
default:
|
|
// The operator switched reading off (`assistant.disabled.documentAi`,
|
|
// or the master `assistant.disabled.enabled`).
|
|
return code.startsWith("assistant.disabled.")
|
|
? "documents.assist.errorUnavailable"
|
|
: "documents.assist.errorGeneric";
|
|
}
|
|
}
|
|
return "documents.assist.errorGeneric";
|
|
}
|