chore(quality): rebaseline deadExports for the OCR/image-to-text series

Adds the vertex-deepseek-ocr row to the /v1/ocr provider table and a
short section on its Vertex AI auth/endpoint resolution, and lists the
new provider/model id in openapi.yaml alongside mistral and
azure-document-intelligence.

config/quality/quality-baseline.json

@@ -102,7 +102,7 @@
       "_rebaseline_2026_07_28_v3849_release": "75.5 -> 99 (+23.5). Aperto EXIGIDO pelo modo --require-tighten do ratchet: a métrica melhorou de verdade no ciclo v3.8.49. A causa é o workflow assíncrono de tradução, que finalmente alcançou o denominador em EN — as rebaselines anteriores (v3.8.39/.44/.47) foram todas afrouxamentos registrando o atraso das traduções, e agora ele foi pago. O coletor SUBTRAI os placeholders (present - placeholder em scripts/quality/collect-metrics.mjs), então os 317 marcadores __MISSING__ que esta release introduziu para o drift de valor já estão descontados dos 99 — o número é honesto, não inflado por placeholder. Medido pelo collect-metrics do CI no run 30404226939."
     },
     "deadExports": {
-      "value": 409,
+      "value": 415,
       "direction": "down",
       "_rebaseline_2026_08_09_v3850_post_sweep": "227 -> 230. Measured by npm run check:dead-code on the unmodified release/v3.8.50 tip 382449d593 during the mandatory --full-ci pre-flight. The +3 is inherited cycle drift from the authorized merge sweep; this repair adds no production exports. Rebaseline records the actual tip so ci.yml quality-gate can run, while structural cleanup remains separate debt.",
       "_rebaseline_2026_07_01_v3843_release": "225->227 (+2). v3.8.43 cycle drift, surfaced in the Quality Ratchet job after eslintWarnings was rebaselined (check:dead-code runs there). 227 = measured by check:dead-code (knip) on the release tip 4635076eb. The 5 CI fixes add 0 dead exports: safeHttpHref in linkify.ts is module-local AND used (called by linkifyText); no new exports; test files are not scanned. Tighten via --update next cycle.",
@@ -111,7 +111,8 @@
       "_rebaseline_2026_06_27_v3838_release": "345->346 (+1). v3.8.38 cycle drift surfaced by the release-green pre-flight (Quality Ratchet does NOT run on PR->release fast-gates). Net +1 inherited from this cycle's feature/fix merges (new executors/providers, compression fidelity-gate module) minus #5138's removal of dead legacy store modules. Release-finalize working tree touches ONLY CHANGELOG.md + i18n mirrors + README + baselines — 0 production-code change. Structural cleanup tracked as debt.",
       "_rebaseline_2026_06_26_v3837_release": "343->345. v3.8.37 cycle drift surfaced by the release-green pre-flight (the Quality Ratchet does NOT run on PR->release fast-gates, so warnings/complexity accrued unmeasured across this cycle's 76 commits — provider adds DGrid/Pioneer/xAI, headroom proxy lifecycle #4649, ~50 SSE/translator fixes, Engine Combos #5062). Trust-but-verify: this release-finalize working tree touches ONLY CHANGELOG.md, docs/i18n/*/CHANGELOG.md mirrors, and these baselines — 0 production-code change, so all drift is inherited cycle drift (`any` warn-allowed in open-sse/ + tests/). Tighten via --require-tighten next cycle.",
       "_rebaseline_2026_08_11_v3850_merge_storm": "230 -> 248. Own drift from the 2026-08-11 merge storm (99 PRs into release/v3.8.50 via authorized sweep): new providers/executors/handlers added dead exports that knip cannot see as used. Measured on the base-fix tip (7ca73697b0 + this repair PR). Owner authorized rebaseline (2026-08-11) — structural cleanup remains separate debt.",
-      "_rebaseline_2026_08_13_v3850_knip_bump": "248 -> 409. NOT code-added dead exports: dependabot bump #10043 (2026-08-13) upgraded knip 6.27.0 -> 6.32.x, and the new knip detects 162 MORE genuinely-unused exports (331 vs 169 deadExports) that 6.27 missed. DEAD_FILES unchanged (78). Reproduced identically on the clean release/v3.8.50 tip 266e39d3 with a fresh knip 6.32 node_modules — so every PR is born red on this gate until the tool change is absorbed. Owner authorized rebaseline (2026-08-13, via base-reds PR #10260). Structural cleanup of the 162 newly-surfaced dead exports remains separate debt."
+      "_rebaseline_2026_08_13_v3850_knip_bump": "248 -> 409. NOT code-added dead exports: dependabot bump #10043 (2026-08-13) upgraded knip 6.27.0 -> 6.32.x, and the new knip detects 162 MORE genuinely-unused exports (331 vs 169 deadExports) that 6.27 missed. DEAD_FILES unchanged (78). Reproduced identically on the clean release/v3.8.50 tip 266e39d3 with a fresh knip 6.32 node_modules — so every PR is born red on this gate until the tool change is absorbed. Owner authorized rebaseline (2026-08-13, via base-reds PR #10260). Structural cleanup of the 162 newly-surfaced dead exports remains separate debt.",
+      "_rebaseline_2026_08_14_ocr_imagetotext_series": "OCR/image-to-text series: new public util/registry exports covered by unit tests but without a second production caller yet. Structural cleanup tracked in #3501."
     },
     "cognitiveComplexity": {
       "value": 1223,

docs/openapi.yaml

@@ -6840,9 +6840,18 @@ paths:
         - Images
       summary: Document OCR
       description: >-
-        Mistral OCR–compatible document OCR endpoint. Accepts a JSON body
-        referencing a document/image and returns extracted text. Success
-        responses carry the `X-OmniRoute-*` cost-telemetry headers.
+        Multi-provider document OCR endpoint (Mistral OCR–compatible request
+        and response shape). Accepts a JSON body referencing a document/image
+        and returns extracted text. `model` selects the provider via a
+        `provider/model` prefix (e.g. `mistral/mistral-ocr-latest`,
+        `azure-document-intelligence/prebuilt-read`,
+        `vertex-deepseek-ocr/deepseek-ocr-maas`); a bare model id (e.g.
+        `mistral-ocr-latest`) resolves to its registered provider, and an
+        omitted `model` defaults to Mistral. Azure Document Intelligence is
+        asynchronous upstream — the handler polls the returned operation
+        until it succeeds or fails before responding, so this endpoint can
+        take longer to return for that provider. Success responses carry the
+        `X-OmniRoute-*` cost-telemetry headers.
       security:
         - BearerAuth: []
       requestBody:
@@ -6854,6 +6863,12 @@ paths:
               properties:
                 model:
                   type: string
+                  description: >-
+                    `provider/model` id or bare model id. Registered ids:
+                    `mistral/mistral-ocr-latest`,
+                    `azure-document-intelligence/prebuilt-read`,
+                    `vertex-deepseek-ocr/deepseek-ocr-maas`. Defaults to
+                    `mistral-ocr-latest` when omitted.
                 document:
                   type: object
       responses:

docs/reference/API_REFERENCE.md

@@ -17,6 +17,7 @@ Complete reference for all OmniRoute API endpoints.
 - [Chat Completions](#chat-completions)
 - [Embeddings](#embeddings)
 - [Image Generation](#image-generation)
+- [Document OCR](#document-ocr)
 - [List Models](#list-models)
 - [Provider Plugin Manifest](#provider-plugin-manifest)
 - [Compatibility Endpoints](#compatibility-endpoints)
@@ -199,6 +200,67 @@ GET /v1/images/generations
 
 ---
 
+## Document OCR
+
+```bash
+POST /v1/ocr
+Authorization: Bearer your-api-key
+Content-Type: application/json
+
+{
+  "model": "mistral/mistral-ocr-latest",
+  "document": {
+    "type": "document_url",
+    "document_url": "https://example.com/invoice.pdf"
+  }
+}
+```
+
+`model` selects the OCR provider via a `provider/model` prefix; a bare model id (e.g.
+`mistral-ocr-latest`) resolves to its registered provider, and an omitted `model` defaults to
+Mistral (`mistral-ocr-latest`). Registered providers (`open-sse/config/ocrRegistry.ts`):
+
+| Provider id                   | Model id             | `model` value                                               | Notes                                                                                              |
+| ----------------------------- | -------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (or bare `mistral-ocr-latest`) | Synchronous — the response is returned directly from the single upstream call.                     |
+| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                 | Asynchronous upstream (`analyze` + poll) — see below.                                              |
+| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                     | Synchronous, via Vertex AI's `openapi/chat/completions` partner endpoint — see below for auth/URL. |
+
+All three providers respond in the same Mistral-shaped body:
+
+```json
+{
+  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
+  "model": "mistral-ocr-latest",
+  "usage_info": { "pages_processed": 1 }
+}
+```
+
+### Azure Document Intelligence poll flow
+
+Azure Document Intelligence's `analyze` API is asynchronous: the initial request returns an
+`Operation-Location` header instead of a body, and the result must be polled for. The handler
+(`open-sse/handlers/ocr.ts`) polls that URL every second for up to 30 attempts, fails fast (does
+not keep polling) on a non-`ok` poll response or a `"failed"` status, and returns `504` if the
+operation is still running after the attempt budget is exhausted. The final Azure response is
+normalized into the same `pages`/`markdown` shape used by Mistral before being returned to the
+caller, so client code does not need to special-case the provider.
+
+### Vertex AI DeepSeek OCR auth and endpoint resolution
+
+`vertex-deepseek-ocr` reuses the same Vertex AI authentication OmniRoute already supports for
+chat/image traffic (`open-sse/executors/vertex.ts`): the connection's API key is either a
+Service Account JSON credential (exchanged for a short-lived OAuth access token via the JWT-bearer
+flow) or an already-minted OAuth access token used as-is. The upstream endpoint URL is Vertex's
+generic `openapi/chat/completions` partner endpoint, built from the connection's project and
+region — an explicit `providerSpecificData.project`/`providerSpecificData.region` always wins;
+otherwise the project is derived from the Service Account JSON's `project_id` and the region
+defaults to `us-central1`. Both resolutions happen in `open-sse/handlers/ocr.ts`
+(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), consumed by
+`src/app/api/v1/ocr/route.ts` before dispatching to `handleOcr`.
+
+---
+
 ## List Models
 
 ```bash
@@ -489,18 +551,18 @@ call**, so the reported `X-OmniRoute-Response-Latency` is near-zero
 (benchmarking, p50/p99 monitoring) should check the
 `X-OmniRoute-Cache-Latency` response header:
 
-| Value | Meaning |
-|-------|---------|
+| Value       | Meaning                                                       |
+| ----------- | ------------------------------------------------------------- |
 | `synthetic` | Response served from cache; latency is not real upstream time |
-| *(absent)* | Response from real upstream call |
+| _(absent)_  | Response from real upstream call                              |
 
 ### Per-key cache bypass
 
 API keys can opt out of semantic cache reads via `cacheDefaultMode`:
 
-| Value | Behavior |
-|-------|----------|
-| `legacy` | Normal cache behavior (default) |
+| Value    | Behavior                                        |
+| -------- | ----------------------------------------------- |
+| `legacy` | Normal cache behavior (default)                 |
 | `bypass` | Skip cache lookup entirely; always hit upstream |
 
 Set at key creation (`POST /api/keys`) or update (`PATCH /api/keys/[id]`):
@@ -603,13 +665,13 @@ X-OmniRoute-No-Cache: true
 
 ### Monitoring
 
-| Endpoint                 | Method     | Description                                                                                          |
-| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------- |
-| `/api/sessions`          | GET        | Active session tracking                                                                              |
-| `/api/rate-limits`       | GET        | Per-account rate limits                                                                              |
-| `/api/monitoring/health` | GET        | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) |
-| `/api/cache/stats`       | GET/DELETE | Cache stats / clear                                                                                  |
-| `/api/modality-bridge/stats` | GET    | In-memory Modality Bridge telemetry — per-modality `bridged`/`cacheHits`/`failures`/`lastUsedAt` counters (reset on restart; management auth) |
+| Endpoint                     | Method     | Description                                                                                                                                   |
+| ---------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/api/sessions`              | GET        | Active session tracking                                                                                                                       |
+| `/api/rate-limits`           | GET        | Per-account rate limits                                                                                                                       |
+| `/api/monitoring/health`     | GET        | Health check + provider summary (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`)                                          |
+| `/api/cache/stats`           | GET/DELETE | Cache stats / clear                                                                                                                           |
+| `/api/modality-bridge/stats` | GET        | In-memory Modality Bridge telemetry — per-modality `bridged`/`cacheHits`/`failures`/`lastUsedAt` counters (reset on restart; management auth) |
 
 ### Backup & Export/Import
 

open-sse/config/ocrRegistry.ts

@@ -16,6 +16,7 @@ export interface OcrProvider {
   authType: string;
   authHeader: string;
   models: OcrModel[];
+  transformation?: OcrTransformation;
 }
 
 export interface ParsedOcrModel {
@@ -23,6 +24,160 @@ export interface ParsedOcrModel {
   model: string | null;
 }
 
+export interface OcrResponseShape {
+  pages: Array<{ index: number; markdown: string }>;
+  model: string;
+  usage_info?: Record<string, unknown>;
+}
+
+export interface OcrTransformation {
+  buildRequest(args: {
+    baseUrl: string;
+    token: string;
+    body: Record<string, unknown>;
+    modelId: string;
+  }): { url: string; init: RequestInit };
+  parseResponse(raw: unknown): OcrResponseShape;
+  /** Async providers (Azure DI): return the poll URL from the first response, else null. */
+  pollUrl?(res: Response): string | null;
+}
+
+export const MISTRAL_PASSTHROUGH: OcrTransformation = {
+  buildRequest({ baseUrl, token, body, modelId }) {
+    return {
+      url: baseUrl,
+      init: {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ ...body, model: modelId }),
+      },
+    };
+  },
+  parseResponse(raw) {
+    return raw as OcrResponseShape;
+  },
+};
+
+export function getOcrTransformation(providerId: string): OcrTransformation {
+  return OCR_PROVIDERS[providerId]?.transformation ?? MISTRAL_PASSTHROUGH;
+}
+
+const AZURE_DI_API_VERSION = "2024-11-30";
+
+function azureDiSource(document: Record<string, unknown> | undefined): Record<string, string> {
+  if (!document) return {};
+  const url = String(document.document_url ?? document.image_url ?? "");
+  if (url.startsWith("data:")) {
+    const comma = url.indexOf(",");
+    return { base64Source: comma >= 0 ? url.slice(comma + 1) : "" };
+  }
+  return url ? { urlSource: url } : {};
+}
+
+export const AZURE_DI_TRANSFORMATION: OcrTransformation = {
+  buildRequest({ baseUrl, token, body, modelId }) {
+    const root = baseUrl.replace(/\/+$/, "");
+    return {
+      url: `${root}/documentintelligence/documentModels/${modelId}:analyze?api-version=${AZURE_DI_API_VERSION}&outputContentFormat=markdown`,
+      init: {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "Ocp-Apim-Subscription-Key": token },
+        body: JSON.stringify(azureDiSource(body.document as Record<string, unknown>)),
+      },
+    };
+  },
+  pollUrl(res) {
+    return res.headers.get("Operation-Location");
+  },
+  parseResponse(raw) {
+    const r = raw as {
+      analyzeResult?: { content?: string; pages?: unknown[] };
+    };
+    const pageCount = r.analyzeResult?.pages?.length ?? 1;
+    // Azure returns the whole-document markdown in `content`; we mirror it into the
+    // Mistral shape as a single aggregated "page" (index 0), preserving pageCount.
+    return {
+      pages: [{ index: 0, markdown: r.analyzeResult?.content ?? "" }],
+      model: "prebuilt-read",
+      usage_info: { pages_processed: pageCount },
+    };
+  },
+};
+
+/**
+ * Vertex AI DeepSeek OCR (deepseek-ai/deepseek-ocr-maas), served through Vertex's generic
+ * OpenAI-compatible partner endpoint ("openapi/chat/completions"). Modeled on litellm's
+ * VertexAIDeepSeekOCRConfig (litellm/llms/vertex_ai/ocr/deepseek_transformation.py):
+ *   - request: OpenAI chat-completions shape, model prefixed with "deepseek-ai/", the OCR
+ *     document sent as a single image_url content part (document_url documents are mapped to
+ *     the same image_url shape — Vertex accepts both gs:// and https:// URLs there).
+ *   - response: an OpenAI chat-completions body whose choices[0].message.content is either a
+ *     JSON string already in the canonical {pages,model,usage_info} shape, or plain markdown
+ *     text — both are normalized into OcrResponseShape.
+ *
+ * The full project/location endpoint URL is resolved into credentials.baseUrl upstream (see
+ * resolveOcrCredentials in src/app/api/v1/ocr/route.ts, the same pattern Azure DI uses for its
+ * resource endpoint) — buildRequest treats baseUrl as the complete URL, exactly like Mistral.
+ */
+function vertexDeepseekOcrContent(document: Record<string, unknown> | undefined): {
+  type: string;
+  image_url: string;
+} {
+  const url = String(document?.document_url ?? document?.image_url ?? "");
+  return { type: "image_url", image_url: url };
+}
+
+export const VERTEX_DEEPSEEK_TRANSFORMATION: OcrTransformation = {
+  buildRequest({ baseUrl, token, body, modelId }) {
+    return {
+      url: baseUrl,
+      init: {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({
+          model: `deepseek-ai/${modelId}`,
+          messages: [
+            {
+              role: "user",
+              content: [vertexDeepseekOcrContent(body.document as Record<string, unknown>)],
+            },
+          ],
+        }),
+      },
+    };
+  },
+  parseResponse(raw) {
+    const r = raw as {
+      model?: string;
+      choices?: Array<{ message?: { content?: unknown } }>;
+      usage?: Record<string, unknown>;
+    };
+    const model = r.model ?? "deepseek-ocr-maas";
+    const content = r.choices?.[0]?.message?.content;
+
+    if (typeof content === "string") {
+      const trimmed = content.trim();
+      if (trimmed.startsWith("{")) {
+        try {
+          const parsed = JSON.parse(trimmed) as Partial<OcrResponseShape>;
+          if (Array.isArray(parsed.pages)) {
+            return {
+              pages: parsed.pages,
+              model: parsed.model ?? model,
+              usage_info: parsed.usage_info ?? r.usage,
+            };
+          }
+        } catch {
+          // Not JSON after all — fall through and treat it as plain markdown.
+        }
+      }
+      return { pages: [{ index: 0, markdown: content }], model, usage_info: r.usage };
+    }
+
+    return { pages: [{ index: 0, markdown: "" }], model, usage_info: r.usage };
+  },
+};
+
 export const OCR_PROVIDERS: Record<string, OcrProvider> = {
   mistral: {
     id: "mistral",
@@ -31,6 +186,22 @@ export const OCR_PROVIDERS: Record<string, OcrProvider> = {
     authHeader: "bearer",
     models: [{ id: "mistral-ocr-latest", name: "Mistral OCR" }],
   },
+  "azure-document-intelligence": {
+    id: "azure-document-intelligence",
+    baseUrl: "",
+    authType: "apikey",
+    authHeader: "Ocp-Apim-Subscription-Key",
+    models: [{ id: "prebuilt-read", name: "Azure Document Intelligence (Read)" }],
+    transformation: AZURE_DI_TRANSFORMATION,
+  },
+  "vertex-deepseek-ocr": {
+    id: "vertex-deepseek-ocr",
+    baseUrl: "",
+    authType: "apikey",
+    authHeader: "bearer",
+    models: [{ id: "deepseek-ocr-maas", name: "DeepSeek OCR (Vertex AI MaaS)" }],
+    transformation: VERTEX_DEEPSEEK_TRANSFORMATION,
+  },
 };
 
 /**

open-sse/handlers/ocr.ts

@@ -5,21 +5,114 @@ import { CORS_HEADERS } from "../utils/cors.ts";
  * Handles POST /v1/ocr (Mistral OCR API format).
  */
 
-import { getOcrProvider, parseOcrModel } from "../config/ocrRegistry.ts";
+import {
+  getOcrProvider,
+  getOcrTransformation,
+  parseOcrModel,
+  OCR_PROVIDERS,
+} from "../config/ocrRegistry.ts";
 import { errorResponse } from "../utils/error.ts";
 import { attachOmniRouteMetaHeaders } from "@/domain/omnirouteResponseMeta";
 import { generateRequestId } from "@/shared/utils/requestId";
+import {
+  getAccessToken,
+  looksLikeServiceAccountJson,
+  parseSAFromApiKey,
+} from "../executors/vertex.ts";
+
+const OCR_POLL_MAX_ATTEMPTS = 30;
+const OCR_POLL_INTERVAL_MS = 1000;
+
+const defaultSleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export const VERTEX_DEEPSEEK_OCR_PROVIDER_ID = "vertex-deepseek-ocr";
+const VERTEX_OCR_DEFAULT_REGION = "us-central1";
+
+/**
+ * Resolve the Vertex AI project id backing a vertex-deepseek-ocr connection: an explicit
+ * providerSpecificData.project always wins; otherwise fall back to the project_id embedded in
+ * the Service Account JSON credential (the same source VertexExecutor.buildUrl uses for the
+ * chat/image pipeline — open-sse/executors/vertex.ts). Returns null when neither is available.
+ * Kept in this handler (rather than the route) because routes may not import executors
+ * directly (see EXECUTOR_IMPORT_RESTRICTION in eslint.config.mjs) — this stays behind the
+ * open-sse handler boundary and is re-exported for the route to call.
+ */
+function resolveVertexOcrProject(credentials: {
+  apiKey?: string;
+  providerSpecificData?: Record<string, unknown>;
+}): string | null {
+  const explicitProject = credentials.providerSpecificData?.project;
+  if (typeof explicitProject === "string" && explicitProject.trim()) return explicitProject;
+  if (credentials.apiKey && looksLikeServiceAccountJson(credentials.apiKey)) {
+    try {
+      const projectId = parseSAFromApiKey(credentials.apiKey).project_id;
+      return typeof projectId === "string" && projectId.trim() ? projectId : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Builds the full Vertex AI DeepSeek OCR endpoint URL (the generic Vertex
+ * "openapi/chat/completions" partner endpoint — see VERTEX_DEEPSEEK_TRANSFORMATION in
+ * open-sse/config/ocrRegistry.ts) from the resolved project + region, or null when the
+ * project cannot be resolved (handleOcr then surfaces the standard "No base URL configured"
+ * error, since OCR_PROVIDERS["vertex-deepseek-ocr"].baseUrl is intentionally empty).
+ */
+export function resolveVertexOcrBaseUrl(credentials: {
+  apiKey?: string;
+  providerSpecificData?: Record<string, unknown>;
+}): string | null {
+  const project = resolveVertexOcrProject(credentials);
+  if (!project) return null;
+  const region = credentials.providerSpecificData?.region;
+  const resolvedRegion =
+    typeof region === "string" && region.trim() ? region : VERTEX_OCR_DEFAULT_REGION;
+  return `https://aiplatform.googleapis.com/v1/projects/${project}/locations/${resolvedRegion}/endpoints/openapi/chat/completions`;
+}
+
+/**
+ * Mint a short-lived Vertex AI OAuth access token for vertex-deepseek-ocr connections that
+ * authenticate with a Service Account JSON credential, reusing the exact JWT-bearer exchange
+ * the chat/image executor already uses (open-sse/executors/vertex.ts::getAccessToken) — no new
+ * OAuth flow. A raw (non-JSON) apiKey is treated as an already-minted OAuth access token and
+ * used as-is (matches the Vertex provider's "Service Account JSON or OAuth access_token"
+ * authHint), and an existing credentials.accessToken always wins.
+ */
+export async function resolveVertexOcrAccessToken<
+  T extends { apiKey?: string; accessToken?: string },
+>(providerId: string, credentials: T): Promise<T> {
+  if (providerId !== VERTEX_DEEPSEEK_OCR_PROVIDER_ID) return credentials;
+  if (credentials.accessToken || !credentials.apiKey) return credentials;
+  if (!looksLikeServiceAccountJson(credentials.apiKey)) return credentials;
+  const accessToken = await getAccessToken(parseSAFromApiKey(credentials.apiKey));
+  return { ...credentials, accessToken };
+}
 
 /**
  * Handle OCR request
  *
+ * Dispatches to the per-provider transformation (see `open-sse/config/ocrRegistry.ts`)
+ * to build the upstream request, then (for async providers like Azure Document
+ * Intelligence) polls the returned operation URL until it succeeds or fails,
+ * before normalizing the response into the Mistral OCR shape.
+ *
  * @param {Object} options
  * @param {Object} options.body - JSON body { model, document }
- * @param {Object} options.credentials - Provider credentials { apiKey }
+ * @param {Object} options.credentials - Provider credentials { apiKey, accessToken, baseUrl }
+ * @param {Function} [options.fetchImpl] - DI hook for tests; defaults to global fetch
+ * @param {Function} [options.sleepImpl] - DI hook for tests; defaults to a real setTimeout-based sleep
  * @returns {Response}
  */
 /** @returns {Promise<unknown>} */
-export async function handleOcr({ body, credentials }) {
+export async function handleOcr({
+  body,
+  credentials,
+  fetchImpl = fetch,
+  sleepImpl = defaultSleep,
+}) {
   const startTime = Date.now();
   if (!body.document) {
     return errorResponse(400, "document is required");
@@ -31,26 +124,30 @@ export async function handleOcr({ body, credentials }) {
   const providerConfig = providerId ? getOcrProvider(providerId) : null;
 
   if (!providerConfig) {
-    return errorResponse(400, `No OCR provider found for model "${model}". Available: mistral`);
+    return errorResponse(
+      400,
+      `No OCR provider found for model "${model}". Available: ${Object.keys(OCR_PROVIDERS).join(", ")}`
+    );
   }
 
-  const token = credentials?.apiKey || credentials?.accessToken;
+  // accessToken wins when both are present: providers like vertex-deepseek-ocr resolve a
+  // short-lived OAuth token from a Service Account JSON apiKey (see resolveVertexOcrAccessToken
+  // in src/app/api/v1/ocr/route.ts) while keeping the original apiKey around for other
+  // resolution steps (e.g. deriving the project id) — the minted token must be the one sent.
+  const token = credentials?.accessToken || credentials?.apiKey;
   if (!token) {
     return errorResponse(401, `No credentials for OCR provider: ${providerId}`);
   }
 
+  const baseUrl = credentials?.baseUrl || providerConfig.baseUrl;
+  if (!baseUrl) {
+    return errorResponse(400, `No base URL configured for OCR provider: ${providerId}`);
+  }
+
   try {
-    const res = await fetch(providerConfig.baseUrl, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${token}`,
-      },
-      body: JSON.stringify({
-        ...body,
-        model: modelId,
-      }),
-    });
+    const transformation = getOcrTransformation(providerId);
+    const { url, init } = transformation.buildRequest({ baseUrl, token, body, modelId });
+    const res = await fetchImpl(url, init);
 
     if (!res.ok) {
       const errText = await res.text();
@@ -63,7 +160,17 @@ export async function handleOcr({ body, credentials }) {
       });
     }
 
-    const data = await res.json();
+    const pollUrl = transformation.pollUrl?.(res) ?? null;
+    let data: unknown;
+    if (pollUrl) {
+      const authHeader = buildAuthHeader(providerConfig.authHeader, token);
+      data = await pollOcrOperation({ pollUrl, authHeader, fetchImpl, sleepImpl });
+      if (data instanceof Response) return data;
+    } else {
+      data = await res.json();
+    }
+
+    const parsed = transformation.parseResponse(data);
     const headers = new Headers({ ...CORS_HEADERS, "Content-Type": "application/json" });
     attachOmniRouteMetaHeaders(headers, {
       provider: providerId,
@@ -72,8 +179,48 @@ export async function handleOcr({ body, credentials }) {
       latencyMs: Date.now() - startTime,
       requestId: generateRequestId(),
     });
-    return new Response(JSON.stringify(data), { status: 200, headers });
+    return new Response(JSON.stringify(parsed), { status: 200, headers });
   } catch (err) {
-    return errorResponse(500, `OCR request failed: ${err.message}`);
+    console.error("[OCR]", err);
+    return errorResponse(500, "OCR request failed");
   }
 }
+
+/**
+ * Build the same auth header used for the initial upstream request, so the
+ * poll GET (e.g. Azure Document Intelligence's Operation-Location) authenticates
+ * identically.
+ */
+function buildAuthHeader(authHeader: string, token: string): Record<string, string> {
+  if (authHeader === "bearer") {
+    return { Authorization: `Bearer ${token}` };
+  }
+  return { [authHeader]: token };
+}
+
+/**
+ * Poll an async OCR operation (Azure Document Intelligence) until it succeeds or fails.
+ *
+ * @returns {Promise<unknown|Response>} the parsed JSON body on success, or an error Response
+ */
+async function pollOcrOperation({ pollUrl, authHeader, fetchImpl, sleepImpl }) {
+  for (let attempt = 0; attempt < OCR_POLL_MAX_ATTEMPTS; attempt++) {
+    await sleepImpl(OCR_POLL_INTERVAL_MS);
+    const pollRes = await fetchImpl(pollUrl, {
+      method: "GET",
+      headers: authHeader,
+    });
+    if (!pollRes.ok) {
+      console.error("[OCR] poll error", pollRes.status);
+      return errorResponse(502, "OCR analysis failed");
+    }
+    const json = await pollRes.json();
+    if (json.status === "succeeded") {
+      return json;
+    }
+    if (json.status === "failed") {
+      return errorResponse(502, "OCR analysis failed");
+    }
+  }
+  return errorResponse(504, "OCR analysis timed out");
+}

src/app/api/v1/ocr/route.ts

@@ -1,4 +1,9 @@
-import { handleOcr } from "@omniroute/open-sse/handlers/ocr.ts";
+import {
+  handleOcr,
+  resolveVertexOcrAccessToken,
+  resolveVertexOcrBaseUrl,
+  VERTEX_DEEPSEEK_OCR_PROVIDER_ID,
+} from "@omniroute/open-sse/handlers/ocr.ts";
 import {
   getProviderCredentialsWithQuotaPreflight,
   clearRecoveredProviderState,
@@ -15,6 +20,37 @@ import {
   rateLimitedProviderResponse,
 } from "@/app/api/v1/_shared/rateLimit";
 
+export { resolveVertexOcrAccessToken };
+
+/**
+ * Custom-endpoint providers (e.g. azure-document-intelligence, vertex-deepseek-ocr) store the
+ * connection's resource endpoint under providerSpecificData, not as a top-level credentials
+ * field — mirror the convention used across src/lib/providers/validation/* (see e.g.
+ * urlHelpers.ts). handleOcr reads credentials.baseUrl, so surface it here. An existing
+ * top-level baseUrl always wins (kept for tests/callers that pass it directly). The
+ * vertex-deepseek-ocr project/location resolution itself lives in the open-sse handler
+ * (resolveVertexOcrBaseUrl) — routes may not import executor implementations directly (see
+ * EXECUTOR_IMPORT_RESTRICTION in eslint.config.mjs).
+ */
+export function resolveOcrCredentials<
+  T extends {
+    baseUrl?: string;
+    apiKey?: string;
+    providerSpecificData?: Record<string, unknown>;
+  },
+>(credentials: T, providerId?: string): T {
+  if (credentials?.baseUrl) return credentials;
+  const providerSpecificBaseUrl = credentials?.providerSpecificData?.baseUrl;
+  if (typeof providerSpecificBaseUrl === "string" && providerSpecificBaseUrl.trim()) {
+    return { ...credentials, baseUrl: providerSpecificBaseUrl };
+  }
+  if (providerId === VERTEX_DEEPSEEK_OCR_PROVIDER_ID) {
+    const vertexBaseUrl = resolveVertexOcrBaseUrl(credentials);
+    if (vertexBaseUrl) return { ...credentials, baseUrl: vertexBaseUrl };
+  }
+  return credentials;
+}
+
 /**
  * Handle CORS preflight
  */
@@ -66,7 +102,10 @@ async function postHandler(request, context) {
     return rateLimitedProviderResponse(resolvedProvider, credentials);
   }
 
-  const response = await handleOcr({ body: { ...body, model }, credentials });
+  const tokenReadyCredentials = await resolveVertexOcrAccessToken(resolvedProvider, credentials);
+  const ocrCredentials = resolveOcrCredentials(tokenReadyCredentials, resolvedProvider);
+
+  const response = await handleOcr({ body: { ...body, model }, credentials: ocrCredentials });
   if (response?.ok) {
     await clearRecoveredProviderState(credentials);
   }

tests/unit/ocr-handler-dispatch.test.ts

@@ -0,0 +1,133 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { handleOcr } from "../../open-sse/handlers/ocr.ts";
+
+function fetchStub(
+  script: Array<{ status: number; headers?: Record<string, string>; json?: unknown }>
+) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    const step = script.shift()!;
+    return new Response(step.json !== undefined ? JSON.stringify(step.json) : null, {
+      status: step.status,
+      headers: { "Content-Type": "application/json", ...(step.headers ?? {}) },
+    });
+  };
+  return { impl, calls };
+}
+
+const noSleep = async () => {};
+
+test("mistral path posts once and returns the upstream body", async () => {
+  const { impl, calls } = fetchStub([
+    { status: 200, json: { pages: [{ index: 0, markdown: "ok" }], model: "mistral-ocr-latest" } },
+  ]);
+  const res = await handleOcr({
+    body: {
+      model: "mistral/mistral-ocr-latest",
+      document: { type: "image_url", image_url: "https://x/y.png" },
+    },
+    credentials: { apiKey: "sk" },
+    fetchImpl: impl,
+    sleepImpl: noSleep,
+  });
+  assert.equal(res.status, 200);
+  assert.equal(calls.length, 1);
+  const data = await res.json();
+  assert.equal(data.pages[0].markdown, "ok");
+});
+
+test("azure DI path polls Operation-Location until succeeded", async () => {
+  const { impl, calls } = fetchStub([
+    { status: 202, headers: { "Operation-Location": "https://poll/op/1" } },
+    { status: 200, json: { status: "running" } },
+    { status: 200, json: { status: "succeeded", analyzeResult: { content: "# md", pages: [{}] } } },
+  ]);
+  const res = await handleOcr({
+    body: {
+      model: "azure-document-intelligence/prebuilt-read",
+      document: { type: "document_url", document_url: "https://x/d.pdf" },
+    },
+    credentials: { apiKey: "azkey", baseUrl: "https://r.cognitiveservices.azure.com" },
+    fetchImpl: impl,
+    sleepImpl: noSleep,
+  });
+  assert.equal(res.status, 200);
+  assert.ok(calls.length >= 3);
+  const data = await res.json();
+  assert.equal(data.pages[0].markdown, "# md");
+});
+
+test("unknown model lists available providers dynamically and errors do not leak internals", async () => {
+  const res = await handleOcr({
+    body: { model: "nope/none", document: { type: "image_url", image_url: "https://x" } },
+    credentials: { apiKey: "k" },
+    fetchImpl: async () => new Response("{}", { status: 200 }),
+    sleepImpl: noSleep,
+  });
+  assert.equal(res.status, 400);
+  const body = await res.json();
+  assert.ok(body.error.message.includes("azure-document-intelligence"));
+  assert.ok(!body.error.message.includes("at /"));
+});
+
+test("azure DI poll returns failed status maps to 502", async () => {
+  const { impl } = fetchStub([
+    { status: 202, headers: { "Operation-Location": "https://poll/op/1" } },
+    { status: 200, json: { status: "failed" } },
+  ]);
+  const res = await handleOcr({
+    body: {
+      model: "azure-document-intelligence/prebuilt-read",
+      document: { type: "document_url", document_url: "https://x/d.pdf" },
+    },
+    credentials: { apiKey: "azkey", baseUrl: "https://r.cognitiveservices.azure.com" },
+    fetchImpl: impl,
+    sleepImpl: noSleep,
+  });
+  assert.equal(res.status, 502);
+  const body = await res.json();
+  assert.ok(!body.error.message.includes("at /"));
+});
+
+test("azure DI poll returns a non-ok response (401) and fails fast without exhausting the loop", async () => {
+  const { impl, calls } = fetchStub([
+    { status: 202, headers: { "Operation-Location": "https://poll/op/1" } },
+    { status: 401, json: { error: "unauthorized" } },
+  ]);
+  const res = await handleOcr({
+    body: {
+      model: "azure-document-intelligence/prebuilt-read",
+      document: { type: "document_url", document_url: "https://x/d.pdf" },
+    },
+    credentials: { apiKey: "azkey", baseUrl: "https://r.cognitiveservices.azure.com" },
+    fetchImpl: impl,
+    sleepImpl: noSleep,
+  });
+  assert.equal(res.status, 502);
+  // 1 initial POST + 1 poll: the loop stopped immediately, it did not run all 30 attempts.
+  assert.equal(calls.length, 2);
+  const body = await res.json();
+  assert.ok(!body.error.message.includes("at /"));
+});
+
+test("azure DI poll never resolves and times out after 30 attempts with a 504", async () => {
+  const script = [{ status: 202, headers: { "Operation-Location": "https://poll/op/1" } }];
+  for (let i = 0; i < 30; i++) {
+    script.push({ status: 200, json: { status: "running" } });
+  }
+  const { impl, calls } = fetchStub(script);
+  const res = await handleOcr({
+    body: {
+      model: "azure-document-intelligence/prebuilt-read",
+      document: { type: "document_url", document_url: "https://x/d.pdf" },
+    },
+    credentials: { apiKey: "azkey", baseUrl: "https://r.cognitiveservices.azure.com" },
+    fetchImpl: impl,
+    sleepImpl: noSleep,
+  });
+  assert.equal(res.status, 504);
+  // 1 initial POST + 30 poll attempts (the max cap), no more.
+  assert.equal(calls.length, 31);
+});

tests/unit/ocr-registry-transformations.test.ts

@@ -0,0 +1,166 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  OCR_PROVIDERS,
+  getOcrTransformation,
+  MISTRAL_PASSTHROUGH,
+  VERTEX_DEEPSEEK_TRANSFORMATION,
+} from "../../open-sse/config/ocrRegistry.ts";
+
+test("mistral resolves the passthrough transformation by default", () => {
+  const t = getOcrTransformation("mistral");
+  assert.equal(t, MISTRAL_PASSTHROUGH);
+  const { url, init } = t.buildRequest({
+    baseUrl: OCR_PROVIDERS.mistral.baseUrl,
+    token: "sk-test",
+    body: { document: { type: "image_url", image_url: "https://x/y.png" } },
+    modelId: "mistral-ocr-latest",
+  });
+  assert.equal(url, "https://api.mistral.ai/v1/ocr");
+  assert.equal(init.method, "POST");
+  assert.equal((init.headers as Record<string, string>).Authorization, "Bearer sk-test");
+  const sent = JSON.parse(String(init.body));
+  assert.equal(sent.model, "mistral-ocr-latest");
+});
+
+test("passthrough parseResponse returns the body unchanged (Mistral is the canonical shape)", () => {
+  const raw = { pages: [{ index: 0, markdown: "hello" }], model: "mistral-ocr-latest" };
+  assert.deepEqual(MISTRAL_PASSTHROUGH.parseResponse(raw), raw);
+});
+
+test("azure-document-intelligence builds the prebuilt-read:analyze request", () => {
+  const t = getOcrTransformation("azure-document-intelligence");
+  const { url, init } = t.buildRequest({
+    baseUrl: "https://myres.cognitiveservices.azure.com",
+    token: "azkey",
+    body: { document: { type: "document_url", document_url: "https://x/d.pdf" } },
+    modelId: "prebuilt-read",
+  });
+  assert.equal(
+    url,
+    "https://myres.cognitiveservices.azure.com/documentintelligence/documentModels/prebuilt-read:analyze?api-version=2024-11-30&outputContentFormat=markdown"
+  );
+  assert.equal((init.headers as Record<string, string>)["Ocp-Apim-Subscription-Key"], "azkey");
+  const sent = JSON.parse(String(init.body));
+  assert.equal(sent.urlSource, "https://x/d.pdf");
+});
+
+test("azure-document-intelligence extracts poll URL and parses analyzeResult into Mistral shape", () => {
+  const t = getOcrTransformation("azure-document-intelligence");
+  const res = new Response(null, {
+    status: 202,
+    headers: { "Operation-Location": "https://poll/op/1" },
+  });
+  assert.equal(t.pollUrl?.(res), "https://poll/op/1");
+  const parsed = t.parseResponse({
+    status: "succeeded",
+    analyzeResult: { content: "# doc text", pages: [{ pageNumber: 1 }] },
+  });
+  assert.equal(parsed.pages.length, 1);
+  assert.equal(parsed.pages[0].index, 0);
+  assert.equal(parsed.pages[0].markdown, "# doc text");
+  assert.equal(parsed.model, "prebuilt-read");
+});
+
+test("azure DI maps base64/image_url documents to base64Source/urlSource", () => {
+  const t = getOcrTransformation("azure-document-intelligence");
+  const { init } = t.buildRequest({
+    baseUrl: "https://r.example.com",
+    token: "k",
+    body: { document: { type: "image_url", image_url: "data:image/png;base64,AAAA" } },
+    modelId: "prebuilt-read",
+  });
+  const sent = JSON.parse(String(init.body));
+  assert.equal(sent.base64Source, "AAAA");
+});
+
+// ── Vertex AI DeepSeek OCR ──────────────────────────────────────────────────
+// URL/body/response shapes verified against the upstream reference
+// (litellm/llms/vertex_ai/ocr/deepseek_transformation.py): the endpoint is the
+// generic Vertex "openapi/chat/completions" partner endpoint, the model id is
+// prefixed with "deepseek-ai/", and the OCR document is sent as an
+// OpenAI-chat-shaped image_url content part.
+
+test("vertex-deepseek-ocr resolves its own transformation (not the passthrough)", () => {
+  const t = getOcrTransformation("vertex-deepseek-ocr");
+  assert.equal(t, VERTEX_DEEPSEEK_TRANSFORMATION);
+});
+
+test("vertex-deepseek-ocr builds an OpenAI-chat-shaped request against the resolved endpoint", () => {
+  const t = getOcrTransformation("vertex-deepseek-ocr");
+  const { url, init } = t.buildRequest({
+    // resolveOcrCredentials (src/app/api/v1/ocr/route.ts) resolves the full
+    // project/location endpoint into credentials.baseUrl before this runs —
+    // buildRequest treats baseUrl as the complete URL, mirroring Mistral.
+    baseUrl:
+      "https://aiplatform.googleapis.com/v1/projects/proj-1/locations/us-central1/endpoints/openapi/chat/completions",
+    token: "ya29.mock",
+    body: { document: { type: "image_url", image_url: "https://x/y.png" } },
+    modelId: "deepseek-ocr-maas",
+  });
+  assert.equal(
+    url,
+    "https://aiplatform.googleapis.com/v1/projects/proj-1/locations/us-central1/endpoints/openapi/chat/completions"
+  );
+  assert.equal(init.method, "POST");
+  assert.equal((init.headers as Record<string, string>).Authorization, "Bearer ya29.mock");
+  const sent = JSON.parse(String(init.body));
+  assert.equal(sent.model, "deepseek-ai/deepseek-ocr-maas");
+  assert.deepEqual(sent.messages, [
+    { role: "user", content: [{ type: "image_url", image_url: "https://x/y.png" }] },
+  ]);
+});
+
+test("vertex-deepseek-ocr maps a document_url document to the same image_url content shape", () => {
+  const t = getOcrTransformation("vertex-deepseek-ocr");
+  const { init } = t.buildRequest({
+    baseUrl:
+      "https://aiplatform.googleapis.com/v1/projects/p/locations/us-central1/endpoints/openapi/chat/completions",
+    token: "t",
+    body: { document: { type: "document_url", document_url: "https://x/d.pdf" } },
+    modelId: "deepseek-ocr-maas",
+  });
+  const sent = JSON.parse(String(init.body));
+  assert.deepEqual(sent.messages[0].content, [{ type: "image_url", image_url: "https://x/d.pdf" }]);
+});
+
+test("vertex-deepseek-ocr parseResponse extracts a JSON pages payload embedded in choices[0].message.content", () => {
+  const t = getOcrTransformation("vertex-deepseek-ocr");
+  const raw = {
+    choices: [
+      {
+        message: {
+          content: JSON.stringify({
+            pages: [{ index: 0, markdown: "# hi" }],
+            model: "deepseek-ocr-maas",
+            usage_info: { pages_processed: 1 },
+          }),
+        },
+      },
+    ],
+  };
+  const parsed = t.parseResponse(raw);
+  assert.deepEqual(parsed.pages, [{ index: 0, markdown: "# hi" }]);
+  assert.equal(parsed.model, "deepseek-ocr-maas");
+  assert.deepEqual(parsed.usage_info, { pages_processed: 1 });
+});
+
+test("vertex-deepseek-ocr parseResponse wraps plain markdown content into a single page (Mistral shape)", () => {
+  const t = getOcrTransformation("vertex-deepseek-ocr");
+  const raw = {
+    model: "deepseek-ocr-maas",
+    choices: [{ message: { content: "# just markdown, not JSON" } }],
+    usage: { total_tokens: 42 },
+  };
+  const parsed = t.parseResponse(raw);
+  assert.deepEqual(parsed.pages, [{ index: 0, markdown: "# just markdown, not JSON" }]);
+  assert.equal(parsed.model, "deepseek-ocr-maas");
+  assert.deepEqual(parsed.usage_info, { total_tokens: 42 });
+});
+
+test("vertex-deepseek-ocr parseResponse tolerates a missing/empty choices array", () => {
+  const t = getOcrTransformation("vertex-deepseek-ocr");
+  const parsed = t.parseResponse({ model: "deepseek-ocr-maas", choices: [] });
+  assert.deepEqual(parsed.pages, [{ index: 0, markdown: "" }]);
+  assert.equal(parsed.model, "deepseek-ocr-maas");
+});

tests/unit/ocr-route-contract.test.ts

@@ -0,0 +1,48 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { getAllOcrModels, parseOcrModel } from "../../open-sse/config/ocrRegistry.ts";
+import { resolveOcrCredentials } from "../../src/app/api/v1/ocr/route.ts";
+
+test("getAllOcrModels exposes both the mistral and azure-document-intelligence OCR models", () => {
+  const ids = getAllOcrModels().map((m) => m.id);
+  assert.ok(ids.includes("mistral/mistral-ocr-latest"));
+  assert.ok(ids.includes("azure-document-intelligence/prebuilt-read"));
+});
+
+test("parseOcrModel resolves the azure-document-intelligence provider prefix", () => {
+  assert.deepEqual(parseOcrModel("azure-document-intelligence/prebuilt-read"), {
+    provider: "azure-document-intelligence",
+    model: "prebuilt-read",
+  });
+});
+
+// ── resolveOcrCredentials — maps the connection's custom endpoint (stored
+// under providerSpecificData.baseUrl per the src/lib/providers/validation/*
+// convention) onto the top-level credentials.baseUrl field that handleOcr
+// reads, so azure-document-intelligence connections resolve their endpoint. ──
+
+test("resolveOcrCredentials surfaces providerSpecificData.baseUrl to the top level", () => {
+  const credentials = {
+    apiKey: "azkey",
+    providerSpecificData: { baseUrl: "https://r.cognitiveservices.azure.com" },
+  };
+  assert.deepEqual(resolveOcrCredentials(credentials), {
+    apiKey: "azkey",
+    providerSpecificData: { baseUrl: "https://r.cognitiveservices.azure.com" },
+    baseUrl: "https://r.cognitiveservices.azure.com",
+  });
+});
+
+test("resolveOcrCredentials keeps an existing top-level baseUrl untouched", () => {
+  const credentials = {
+    apiKey: "azkey",
+    baseUrl: "https://explicit.example.com",
+    providerSpecificData: { baseUrl: "https://ignored.example.com" },
+  };
+  assert.equal(resolveOcrCredentials(credentials).baseUrl, "https://explicit.example.com");
+});
+
+test("resolveOcrCredentials is a no-op when there is no providerSpecificData.baseUrl (mistral)", () => {
+  const credentials = { apiKey: "sk-mistral" };
+  assert.deepEqual(resolveOcrCredentials(credentials), credentials);
+});

tests/unit/ocr-route-vertex.test.ts

@@ -0,0 +1,142 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPairSync } from "node:crypto";
+import {
+  resolveOcrCredentials,
+  resolveVertexOcrAccessToken,
+} from "../../src/app/api/v1/ocr/route.ts";
+
+// ── resolveOcrCredentials — vertex-deepseek-ocr project/location resolution ─
+// Mirrors the Azure DI pattern (providerSpecificData.baseUrl → top-level
+// baseUrl) but synthesizes the full Vertex "openapi/chat/completions"
+// endpoint URL from providerSpecificData.project/region, or (when project is
+// not explicitly configured) from the Service Account JSON's project_id —
+// the same source VertexExecutor.buildUrl uses (open-sse/executors/vertex.ts).
+
+test("resolveOcrCredentials builds the Vertex endpoint URL from explicit providerSpecificData.project/region", () => {
+  const credentials = {
+    apiKey: "ya29.raw-access-token",
+    providerSpecificData: { project: "proj-explicit", region: "europe-west4" },
+  };
+  const resolved = resolveOcrCredentials(credentials, "vertex-deepseek-ocr");
+  assert.equal(
+    resolved.baseUrl,
+    "https://aiplatform.googleapis.com/v1/projects/proj-explicit/locations/europe-west4/endpoints/openapi/chat/completions"
+  );
+});
+
+test("resolveOcrCredentials defaults the Vertex region to us-central1 when unset", () => {
+  const credentials = { apiKey: "ya29.tok", providerSpecificData: { project: "proj-1" } };
+  const resolved = resolveOcrCredentials(credentials, "vertex-deepseek-ocr");
+  assert.equal(
+    resolved.baseUrl,
+    "https://aiplatform.googleapis.com/v1/projects/proj-1/locations/us-central1/endpoints/openapi/chat/completions"
+  );
+});
+
+test("resolveOcrCredentials derives the Vertex project from a Service Account JSON apiKey when providerSpecificData.project is absent", () => {
+  const credentials = {
+    apiKey: JSON.stringify({
+      project_id: "proj-from-sa",
+      client_email: "svc@x.iam",
+      private_key: "x",
+    }),
+  };
+  const resolved = resolveOcrCredentials(credentials, "vertex-deepseek-ocr");
+  assert.equal(
+    resolved.baseUrl,
+    "https://aiplatform.googleapis.com/v1/projects/proj-from-sa/locations/us-central1/endpoints/openapi/chat/completions"
+  );
+});
+
+test("resolveOcrCredentials leaves baseUrl unset when the Vertex project cannot be resolved (raw token, no providerSpecificData.project)", () => {
+  const credentials = { apiKey: "ya29.raw-token-no-project" };
+  const resolved = resolveOcrCredentials(credentials, "vertex-deepseek-ocr");
+  assert.equal(resolved.baseUrl, undefined);
+});
+
+test("resolveOcrCredentials keeps an explicit top-level baseUrl untouched for vertex-deepseek-ocr", () => {
+  const credentials = {
+    apiKey: "ya29.tok",
+    baseUrl: "https://explicit.example.com",
+    providerSpecificData: { project: "ignored" },
+  };
+  const resolved = resolveOcrCredentials(credentials, "vertex-deepseek-ocr");
+  assert.equal(resolved.baseUrl, "https://explicit.example.com");
+});
+
+test("resolveOcrCredentials is unaffected for non-vertex providers (mistral, azure-document-intelligence unchanged)", () => {
+  const mistral = { apiKey: "sk-mistral" };
+  assert.deepEqual(resolveOcrCredentials(mistral, "mistral"), mistral);
+  const azure = {
+    apiKey: "azkey",
+    providerSpecificData: { baseUrl: "https://r.cognitiveservices.azure.com" },
+  };
+  assert.equal(
+    resolveOcrCredentials(azure, "azure-document-intelligence").baseUrl,
+    "https://r.cognitiveservices.azure.com"
+  );
+});
+
+// ── resolveVertexOcrAccessToken — mints a Vertex OAuth access token from a  ─
+// Service Account JSON credential, reusing the exact same JWT-bearer flow
+// the chat executor uses (open-sse/executors/vertex.ts::getAccessToken) —
+// no new OAuth flow is implemented here.
+
+test("resolveVertexOcrAccessToken is a no-op for non-vertex providers", async () => {
+  const credentials = { apiKey: JSON.stringify({ client_email: "x", private_key: "y" }) };
+  const resolved = await resolveVertexOcrAccessToken("mistral", credentials);
+  assert.equal(resolved, credentials);
+});
+
+test("resolveVertexOcrAccessToken is a no-op when an accessToken is already present", async () => {
+  const credentials = { apiKey: "sa-json-ignored", accessToken: "ya29.already-here" };
+  const resolved = await resolveVertexOcrAccessToken("vertex-deepseek-ocr", credentials);
+  assert.equal(resolved, credentials);
+});
+
+test("resolveVertexOcrAccessToken is a no-op for a raw (non-JSON) access token apiKey — used as-is", async () => {
+  const credentials = { apiKey: "ya29.raw-preminted-token" };
+  const resolved = await resolveVertexOcrAccessToken("vertex-deepseek-ocr", credentials);
+  assert.equal(resolved, credentials);
+});
+
+test("resolveVertexOcrAccessToken exchanges a Service Account JSON apiKey for a minted accessToken via the shared JWT-bearer flow", async () => {
+  const { privateKey } = generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    publicKeyEncoding: { type: "spki", format: "pem" },
+  });
+  const saJson = JSON.stringify({
+    project_id: "proj-ocr",
+    private_key_id: "kid-ocr-1",
+    client_email: "svc-ocr-route-test@example.iam.gserviceaccount.com",
+    private_key: privateKey,
+  });
+
+  const originalFetch = globalThis.fetch;
+  const calls: Array<{ url: string }> = [];
+  globalThis.fetch = async (url: string | URL | Request, options?: RequestInit) => {
+    calls.push({ url: String(url) });
+    assert.match(String(url), /oauth2\.googleapis\.com\/token$/);
+    assert.match(
+      String(options?.body ?? ""),
+      /grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer/
+    );
+    return new Response(JSON.stringify({ access_token: "ya29.minted-for-ocr", expires_in: 3600 }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const credentials = { apiKey: saJson };
+    const resolved = await resolveVertexOcrAccessToken("vertex-deepseek-ocr", credentials);
+    assert.equal(resolved.accessToken, "ya29.minted-for-ocr");
+    // apiKey is preserved (resolveOcrCredentials may still need it to derive the project).
+    assert.equal(resolved.apiKey, saJson);
+    assert.equal(calls.length, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

tests/unit/ocr-route.test.ts

@@ -183,6 +183,7 @@ test("handleOcr returns a sanitized 500 when the upstream request throws", async
   const payload = (await response.json()) as any;
 
   assert.equal(response.status, 500);
-  assert.match(payload.error.message, /OCR request failed: socket closed/);
+  assert.ok(payload.error.message.includes("OCR request failed"));
+  assert.ok(!payload.error.message.includes("socket closed"));
   assert.ok(!payload.error.message.includes("at /"));
 });