@alembic/ocr: o texto visível, determinístico por padrão

packages/ocr/src/types.ts espelha o types.ts de @alembic/embeddings "1:1" (auto-descrição em types.ts:12–16): um schema Zod de request, um de resultado, e um port de chamada única cuja saída não-confiável é re-validada na borda. O request aceita imagePath OU imageBase64 — e o .refine do schema impõe o XOR: "provide exactly one of imagePath or imageBase64" (types.ts:40–52). Um request ambíguo ou vazio morre ANTES de tocar qualquer backend.

O resultado é { text, blocks?, lang?, pages? } (types.ts:90–99): text pode ser vazio — "a blank page is a valid parse" (types.ts:91) — e blocks é OPCIONAL porque o Unlimited-OCR emite Markdown, não caixas por palavra (types.ts:58–62); quando presentes, cada bloco exige texto não-vazio e bbox de exatamente 4 números finitos não-negativos (types.ts:63–78). Sucesso/falha NÃO são campos: colapsam no Result, "so a failure never masquerades as empty text" (types.ts:88–89).

Pense como… a recepção de um cartório: ou você entrega o documento físico (path) ou uma cópia autenticada (base64) — nunca os dois, nunca nenhum. O atendente confere a entrada ANTES de carimbar e confere o carimbo ANTES de devolver. Onde quebra: aqui até a página em branco recebe protocolo (text: '' é válido) — o que não existe é protocolo falso para falha.

createOfflineOcrBackend (packages/ocr/src/offline-backend.ts) devolve OCR(${source}) — um placeholder estável derivado só da fonte da imagem (offline-backend.ts:41), com blocks ecoando o texto e pages: 1 (offline-backend.ts:42–47). Para inline base64, a "fonte" vira um fingerprint hex de 32 bits calculado por um fold polinomial puro (offline-backend.ts:75–81) — imagens distintas ⇒ labels distintos, sem ecoar o blob gigante e sem crypto.

Na CLI, esse é o caminho de alembic ocr <imagePath> sem flags (apps/cli/src/commands.ts:4692–4693): recognition de verdade NÃO acontece — o que você ganha é wiring, cache e plumbing testáveis a custo zero, "the engine's --offline path" (offline-backend.ts:3–5). O texto do arquivo é direto: "The text is NOT a real recognition" (offline-backend.ts:12).

createSglangOcrBackend (packages/ocr/src/sglang-backend.ts) é um fetch fino sobre o endpoint OpenAI-compatível /v1/chat/completions do servidor SGLang do Unlimited-OCR. O diferencial é a disciplina de reverse-engineering: o cabeçalho do arquivo CITA o contrato exato, linha a linha, do infer.py original — payload com temperature: 0, skip_special_tokens: false, stream: true, images_config.image_mode: "gundam" e o prompt "document parsing." (sglang-backend.ts:14–31; o body montado em :204–225).

E é offline-first até quando é o backend online: sem baseUrl configurada, devolve um err tipado SEM NENHUMA tentativa de rede (sglang-backend.ts:133–141). Com ela, todo fracasso de transporte vira err — throw de rede, status non-2xx (:244–246), body não-JSON (:301–308). A resposta é parseada nos DOIS formatos que o servidor pode falar: SSE streamado (concatena os deltas data: até data: [DONE], pulando chunks malformados exatamente como o infer.py faz — :278–291) ou JSON único (choices[0].message.content — :294–298).

if (args.online) {
  const baseUrl = process.env.ALEMBIC_OCR_BASEURL;
  if (baseUrl === undefined || baseUrl.length === 0) {
    return err(new Error(
      'ocr --online needs the Unlimited-OCR SGLang server (set ALEMBIC_OCR_BASEURL, ' +
      'e.g. http://127.0.0.1:10000; see docs/ocr-setup.md). No base URL set, so no ' +
      'network attempt was made. Omit --online for the deterministic offline backend.'));
  }
  backend = createSglangOcrBackend({ baseUrl, apiKey: process.env.ALEMBIC_OCR_TOKEN });
} else {
  backend = createOfflineOcrBackend(/* lang opcional */);
}

No gate de QA de vídeo, a pergunta "tem texto QUEIMADO nos frames?" é respondida por OCR — via o mesmo padrão de port da lição 21: FrameOcr (packages/marketing-factory/src/validate.ts:45–47), default noopFrameOcr que devolve '' (validate.ts:174–176). A CLI injeta os dentes reais com createFrameOcr sobre @alembic/ocr (apps/cli/src/marketing-seams.ts:34–41).

O fluxo: extractFrames amostra o mp4 com ffmpeg (validate.ts:399) na taxa frameRate default de 1 frame/segundo (validate.ts:110–111); scanFrames roda o OCR em cada frame e coleta TextArtifact { frame, text } para todo texto não-vazio (validate.ts:443–460). A varredura é OPT-IN — checkFrames = noBakedText || forbiddenVisuals.length > 0 (validate.ts:518) — e noBakedText default false, porque "many ad types legitimately use on-screen text/kinetic typography" (validate.ts:105–109): com a trava ligada, artefatos derrubam o gate (failures: 'text-artifact: N frame(s)…', validate.ts:579–580); desligada, são só informativos no relatório. O veredito final é pass = failures.length === 0 (validate.ts:593).