/** * src/adapters/document-intelligence-adapter.ts * ================================================ * Tenant-agnostic Azure AI Document Intelligence client. * * Generalized from v0-datahub/lib/invoice-inbox/doc-intelligence.ts, which * hardcoded the `prebuilt-invoice` model and a fixed invoice-shaped return * type (amount_gross, vendor, vat, ...). Here `modelId` is a CALLER-SUPPLIED * parameter — "prebuilt-invoice", "prebuilt-receipt", "prebuilt-layout", * "prebuilt-read", or any custom-trained model id — and the adapter returns * a generic field map instead of assuming any particular document shape. * * Evidence discipline (correctness-critical, not a style choice): a field is * only ever populated with the value + confidence Document Intelligence * actually reported. If DI did not return a value, the field comes back as * { value: null, confidence: , found: false }. * Nothing here ever defaults, guesses, or backfills a value. */ export interface DocumentIntelligenceConfig { endpoint: string; apiKey: string; /** Default: "2024-11-30" — the API version the production invoice pipeline used. */ apiVersion?: string; /** Delay between result-polling attempts, ms. Default 2000. (Tests override to run fast.) */ pollIntervalMs?: number; /** Delay before retrying after a 429, ms. Default 6000. (Tests override to run fast.) */ rateLimitRetryMs?: number; /** Max result-polling attempts before timing out. Default 40. */ maxPollAttempts?: number; /** Max analyze-request attempts (each 429 counts as one). Default 4. */ maxAnalyzeAttempts?: number; } export interface ExtractedField { value: string | number | boolean | null; confidence: number | null; found: boolean; } export interface DocumentIntelligenceResult { modelId: string; apiVersion: string; /** Full extracted text, when the API returns one (present across prebuilt models). */ content: string | null; /** Top-level structured fields (documents[0].fields), normalized. Empty for pure layout/read. */ fields: Record; /** Array-of-object fields (e.g. invoice/receipt line items), each item pre-normalized. */ arrayFields: Record>>; /** documents[0].confidence, when the model reports a whole-document confidence. */ documentConfidence: number | null; pageCount: number | null; } function sleep(ms: number): Promise { return new Promise((resolve) => setTimeout(resolve, ms)); } /** Normalize one Document Intelligence field object into an evidence-based ExtractedField. */ function normalizeField(raw: unknown): ExtractedField { const f = raw as Record | null | undefined; if (!f) return { value: null, confidence: null, found: false }; let value: string | number | boolean | null = null; switch (f.type) { case "string": value = (f.valueString as string | undefined) ?? (f.content as string | undefined) ?? null; break; case "number": value = (f.valueNumber as number | undefined) ?? null; break; case "integer": value = (f.valueInteger as number | undefined) ?? null; break; case "date": value = (f.valueDate as string | undefined) ?? null; break; case "time": value = (f.valueTime as string | undefined) ?? null; break; case "phoneNumber": value = (f.valuePhoneNumber as string | undefined) ?? null; break; case "countryRegion": value = (f.valueCountryRegion as string | undefined) ?? null; break; case "selectionMark": value = (f.valueSelectionMark as string | undefined) ?? null; break; case "currency": { const cur = f.valueCurrency as Record | undefined; value = typeof cur?.amount === "number" ? (cur.amount as number) : null; break; } case "boolean": value = typeof f.valueBoolean === "boolean" ? (f.valueBoolean as boolean) : null; break; default: value = (f.valueString as string | undefined) ?? (f.content as string | undefined) ?? null; } const found = value !== null && value !== undefined && value !== ""; const confidence = typeof f.confidence === "number" ? (f.confidence as number) : null; return { value: found ? value : null, confidence, found }; } function normalizeObjectFields(obj: Record | null | undefined): Record { const out: Record = {}; for (const [key, raw] of Object.entries(obj ?? {})) { out[key] = normalizeField(raw); } return out; } export class DocumentIntelligenceAdapter { constructor(private config: DocumentIntelligenceConfig) {} static isConfigured(config: Partial): boolean { return !!(config.endpoint && config.apiKey); } /** * Analyze a document buffer with the given model. Throws on any failure — * callers must never interpret a caught error as "no fields found". A * genuinely empty field is represented by { found: false } *inside a * successful result*; a failed call must propagate as an error, not a * fabricated empty success. */ async analyzeDocument(buf: Buffer, modelId: string): Promise { const apiVersion = this.config.apiVersion || "2024-11-30"; const base = this.config.endpoint.replace(/\/$/, ""); const analyzeUrl = `${base}/documentintelligence/documentModels/${encodeURIComponent(modelId)}:analyze?api-version=${apiVersion}`; const maxAnalyzeAttempts = this.config.maxAnalyzeAttempts ?? 4; const rateLimitRetryMs = this.config.rateLimitRetryMs ?? 6000; const pollIntervalMs = this.config.pollIntervalMs ?? 2000; const maxPollAttempts = this.config.maxPollAttempts ?? 40; let operationLocation = ""; for (let attempt = 0; attempt < maxAnalyzeAttempts; attempt++) { const res = await fetch(analyzeUrl, { method: "POST", headers: { "Ocp-Apim-Subscription-Key": this.config.apiKey, "Content-Type": "application/json" }, body: JSON.stringify({ base64Source: buf.toString("base64") }), }); if (res.status === 429) { await sleep(rateLimitRetryMs); continue; } if (res.status !== 202) { const text = await res.text().catch(() => ""); throw new Error(`Document Intelligence analyze request failed: ${res.status} ${text.slice(0, 300)}`); } operationLocation = res.headers.get("operation-location") || ""; break; } if (!operationLocation) { throw new Error( "Document Intelligence analyze did not return an operation-location (rate-limited after retries, or misconfigured)", ); } let payload: Record | null = null; for (let i = 0; i < maxPollAttempts; i++) { await sleep(pollIntervalMs); const pollRes = await fetch(operationLocation, { headers: { "Ocp-Apim-Subscription-Key": this.config.apiKey } }); if (!pollRes.ok) { const text = await pollRes.text().catch(() => ""); throw new Error(`Document Intelligence poll request failed: ${pollRes.status} ${text.slice(0, 300)}`); } const json = (await pollRes.json()) as Record; if (json.status === "succeeded") { payload = json; break; } if (json.status === "failed") { throw new Error(`Document Intelligence analyze failed: ${JSON.stringify(json.error ?? json).slice(0, 500)}`); } } if (!payload) { throw new Error("Document Intelligence analyze timed out waiting for a result"); } const analyzeResult = (payload.analyzeResult as Record) ?? {}; const documents = analyzeResult.documents as Array> | undefined; const doc = documents?.[0]; const rawFields = (doc?.fields as Record) ?? {}; const fields: Record = {}; const arrayFields: Record>> = {}; for (const [key, raw] of Object.entries(rawFields)) { const f = raw as Record; if (f?.type === "array" && Array.isArray(f.valueArray)) { arrayFields[key] = (f.valueArray as Array>).map((item) => normalizeObjectFields(item?.valueObject as Record | undefined), ); } else { fields[key] = normalizeField(f); } } const pages = analyzeResult.pages as unknown[] | undefined; return { modelId, apiVersion, content: typeof analyzeResult.content === "string" ? (analyzeResult.content as string) : null, fields, arrayFields, documentConfidence: typeof doc?.confidence === "number" ? (doc.confidence as number) : null, pageCount: Array.isArray(pages) ? pages.length : null, }; } }