/** * v1.18.9 — resolve whether a user's configured AI provider can read images, * and (for the extract route) pick the first vision-capable provider instance. * * Capability is a function of (providerType, model). The user's `aiModel` * applies to a per-user provider entry; the operator's `adminAiModel` applies * to the `admin-openai` fallback entry. We resolve the chain instances via * `resolveProviderChain` (so credentials + Codex-token refresh are handled in * one place) and pair each surviving entry with the model that drives its * vision allowlist. */ import { aiEgressRefusal } from "@/lib/ai/capabilities/egress"; import { getAiCapability } from "@/lib/ai/capabilities/gate"; import { AiUnavailableError, type NoProviderRefusal, } from "@/lib/ai/capabilities/refusal"; import { PICK_DECIDED_REASONS } from "@/lib/ai/capabilities/types"; import type { ProviderChainResolved } from "@/lib/ai/provider-runner"; import { resolveProviderChain } from "@/lib/ai/provider"; import { chainEntryReadsImages } from "@/lib/ai/codex-slug-chain"; import { RASTERIZATION_AVAILABLE } from "@/lib/documents/rasterize-pdf"; import { prisma } from "@/lib/db"; import { annotate } from "@/lib/logging/context"; import { supportsPdfForProvider, type VisionProviderType, } from "@/lib/ai/vision-capability"; import type { OcrCapabilityDto } from "@/lib/validations/labs-ocr"; interface ModelContext { /** The user's selected model (per-user provider entries). */ userModel: string | null; /** The operator's admin-key model (the `admin-openai` chain entry). */ adminModel: string | null; } /** Whether a chain entry's model can read an image. */ function entryReadsImages( providerType: ProviderChainResolved["providerType"], userId: string, ctx: ModelContext, ): boolean { // Codex picks its model at request time from the sign-in's working slug // and the models its account is offered, NOT from the user's `aiModel`. // Each Codex path asks its own sign-in: the person's connection, or the // operator-shared central one (`admin-codex`). const model = providerType === "admin-openai" ? ctx.adminModel : ctx.userModel; return chainEntryReadsImages(providerType, userId, model); } /** * A transform applied to the resolved provider chain before the vision/text * pick is made. Identity by default (labs behaviour unchanged); the document * class passes a reorder that demotes external/train-by-default providers below * local (see `@/lib/documents/provider-order`). */ export type ChainReorder = ( chain: ProviderChainResolved[], ) => ProviderChainResolved[]; export interface ResolveProviderOptions { /** Reorder the resolved chain before picking. Defaults to identity. */ reorder?: ChainReorder; } /** A vision-capable provider pick: its instance, logical tag, and model. */ export interface VisionProviderPick { /** The full resolved chain (for `assertConsentForChain`). */ chain: ProviderChainResolved[]; /** The first vision-capable entry, or null when none can read images. */ pick: { entry: ProviderChainResolved; providerType: VisionProviderType; pdfSupported: boolean; } | null; /** Whether the user opted into local (in-browser) OCR for text-only providers. */ localOcrEnabled: boolean; } /** * Resolve the user's provider chain and find the first entry that can read * images. Returns the whole chain (the consent gate needs it) plus the chosen * vision entry (or null). The chain is the one every model call resolves, so a * user served only by the operator's admin key is covered through its * `admin-openai` entry. */ export async function resolveVisionProvider( userId: string, options?: ResolveProviderOptions, ): Promise { const userRow = await prisma.user.findUnique({ where: { id: userId }, select: { aiModel: true, labsLocalOcrEnabled: true }, }); const settings = await prisma.appSettings.findUnique({ where: { id: "singleton" }, select: { adminAiModel: true }, }); const localOcrEnabled = userRow?.labsLocalOcrEnabled ?? false; // The OCR path always uses the main configured provider chain — the user's // model drives the vision allowlist. const ctx: ModelContext = { userModel: userRow?.aiModel ?? null, adminModel: settings?.adminAiModel ?? null, }; const resolvedChain = await resolveProviderChain(userId); // Apply the caller's reorder (document class demotes external providers below // local) before picking; labs passes no reorder → identity. const chain = options?.reorder ? options.reorder(resolvedChain) : resolvedChain; for (const entry of chain) { const providerType = entry.providerType as VisionProviderType; if (entryReadsImages(entry.providerType, userId, ctx)) { return { chain, localOcrEnabled, pick: { entry, providerType, pdfSupported: supportsPdfForProvider(providerType), }, }; } } return { chain, localOcrEnabled, pick: null }; } /** * Resolve the provider chain for a TEXT-mode (local-OCR) extract. There is no * vision requirement here — ANY configured provider can structure OCR'd text — * so this returns the whole chain plus the first entry to drive the structuring * call. Returns `null` when nothing is configured. */ export async function resolveTextProvider( userId: string, options?: ResolveProviderOptions, ): Promise<{ chain: ProviderChainResolved[]; pick: { entry: ProviderChainResolved; providerType: string } | null; }> { // The text-mode structuring pass needs no vision — any configured provider in // the main chain can structure the OCR'd text. const resolvedChain = await resolveProviderChain(userId); const chain = options?.reorder ? options.reorder(resolvedChain) : resolvedChain; const entry = chain[0]; return { chain, pick: entry ? { entry, providerType: entry.providerType } : null, }; } /** * How a lab scan refuses with no provider that can serve it. The code predates * the capability envelope and a client already branches on it. */ export const LABS_OCR_NO_PROVIDER: NoProviderRefusal = { errorCode: "labs.ocr.providerUnsupported", status: 422, }; /** * The labs scan's wire. Resolve the provider for one scan mode and ask the * `labsOcr` capability again about exactly that provider, immediately before * the report is sent: the operator's switch, the labs module, the sharing * grant, and a document-class consent receipt for any pick that leaves the * machine (a lab report is a document). Throws the refusal for `apiHandler` * to render; a missing provider keeps its `labs.ocr.providerUnsupported` code. * * Vision mode picks the first vision-capable entry in chain order; text mode * (the person's in-browser OCR) takes the chain head, which is why the pick, * not the published capability, answers the consent question. */ export async function requireLabsOcrProvider( userId: string, mode: "vision", ): Promise>; export async function requireLabsOcrProvider( userId: string, mode: "text", ): Promise<{ entry: ProviderChainResolved; providerType: string }>; export async function requireLabsOcrProvider( userId: string, mode: "vision" | "text", ) { const { chain, pick } = mode === "vision" ? await resolveVisionProvider(userId) : await resolveTextProvider(userId); if (!pick) { annotate({ action: { name: "labs.ocr.providerUnsupported" }, meta: { chainLength: chain.length, ...(mode === "text" ? { mode } : {}), }, }); throw new AiUnavailableError( "labsOcr", "no_provider", null, LABS_OCR_NO_PROVIDER, ); } const refusal = await aiEgressRefusal("labsOcr", userId, [pick.providerType]); if (refusal) throw refusal; return pick; } /** * The cheap capability DTO for the probe endpoint: whether scanning is * available + why not + whether PDFs are accepted. Built from the same * resolution the extract route uses, so the UI never shows an entry the * extract route would 422. * * `ai` is the `labsOcr` capability for the request's record. A scan the * operator, the labs module or the sharing grant close is not offered * (`available: false`, no mode). A missing consent receipt keeps the scan * offered: the scan is where the person is asked for the receipt. */ export async function resolveOcrCapability( userId: string, ): Promise { const [{ chain, pick, localOcrEnabled }, ai] = await Promise.all([ resolveVisionProvider(userId), getAiCapability("labsOcr"), ]); if (ai.reason !== null && !PICK_DECIDED_REASONS.has(ai.reason)) { return { available: false, mode: null, reason: null, pdfSupported: false, ai, }; } // Prefer the native vision path whenever it is available — it is more // accurate and the client does not download the OCR WASM. PDFs are readable // whenever the picked provider natively supports them (Anthropic) OR the // server-side rasterizer is available (every other vision provider reads a // PDF via rasterized page images), so the scan-a-PDF affordance shows for a // codex / OAuth provider too. The extract route keeps the native-block vs // raster decision on `pick.pdfSupported` itself. if (pick) { return { available: true, mode: "vision", reason: null, pdfSupported: pick.pdfSupported || RASTERIZATION_AVAILABLE, ai, }; } // No vision pick. Nothing configured at all → no-provider, regardless of the // toggle (there is no provider to structure the OCR text). if (chain.length === 0) { return { available: false, mode: null, reason: "no-provider", pdfSupported: false, ai, }; } // A provider IS configured but it can't read images. Local OCR is the // text-only fallback: in-browser OCR → text → the configured provider. It is // available only when the user opted in. if (localOcrEnabled) { // Text mode is image-only (tesseract.js can't read PDFs). return { available: true, mode: "text", reason: null, pdfSupported: false, ai, }; } // A text-only provider is configured but the user has not enabled local OCR — // surface the actionable reason so the UI can point at the toggle. return { available: false, mode: null, reason: "enable-local-ocr", pdfSupported: false, ai, }; }