@alembic/vision: a LLM local que LÊ a imagem

O cabeçalho de packages/vision/src/types.ts:2–8 traça a fronteira: "Unlike @alembic/ocr (which transcribes the text VISIBLE in an image), a vision request maps an image to a natural-language DESCRIPTION produced by a local multimodal LLM (VLM)" — diagramas, screenshots de UI, gráficos, arquitetura e design, não só glifos. É "uma LLM multimodal local que LÊ a imagem" (a diretriz do founder, citada no mesmo cabeçalho), no estilo ports-and-injection da casa: o módulo importa zero Python, zero modelo, zero SDK.

O contrato é mínimo e Zod-fechado: um VisionRequest é { imagePath, prompt?, maxTokens? } (types.ts:30–37); um VisionResult é { imagePath, description, model? } — e a description PODE ser vazia, porque uma imagem em branco é um parse válido (types.ts:48–55). O imagePath ecoado no resultado torna qualquer lote re-juntável à origem.

Pense como… a diferença entre um datilógrafo e um crítico de arte diante do mesmo quadro: o datilógrafo (OCR) copia a plaquinha da moldura; o crítico (vision) descreve a cena, o estilo e a intenção. Onde a analogia quebra: este crítico roda a temperatura 0 — a MESMA imagem produz SEMPRE a mesma crítica, de propósito, para o motor poder cachear.

describeImages (packages/vision/src/vision.ts:74–103) é despacho puro: valida CADA request na borda (vision.ts:80–82 — um request inválido derruba a chamada inteira), fatia em chunks de DEFAULT_CHUNK_SIZE = 8 imagens (vision.ts:24), roda no máximo DEFAULT_CONCURRENCY = 2 lotes em voo (vision.ts:26 — a máquina continua responsiva), e então trata a resposta do backend como NÃO-CONFIÁVEL: cada resultado é re-validado com visionResultSchema.safeParse (vision.ts:97–99). Um err de qualquer lote colapsa a chamada toda (vision.ts:95) — nunca um sucesso parcial fingindo ser completo.

const chunks = chunk(validated, deps.chunkSize ?? DEFAULT_CHUNK_SIZE);
const chunkOutcomes = await mapWithConcurrency(
  chunks, deps.concurrency ?? DEFAULT_CONCURRENCY,
  (batch) => deps.backend(batch),
);
for (const outcome of chunkOutcomes) {
  if (!outcome.ok) return outcome;              // fail-closed: 1 lote ruim = tudo err
  for (const result of outcome.value) {
    const parsed = visionResultSchema.safeParse(result);  // saída NÃO-confiável
    if (!parsed.success) return err(new Error(`invalid vision result: …`));
    out.push(parsed.data);
  }
}

Offline (o default, $0): createOfflineVisionBackend devolve VLM(${req.imagePath}) — uma descrição canned derivada só do path (offline-backend.ts:39). O próprio arquivo avisa: "The text is NOT real recognition — it is a reproducible placeholder" (offline-backend.ts:9–10). Mesmo input ⇒ mesmo output; imagens distintas ⇒ descrições distintas; zero Python, zero rede, zero Date.now(). É o que mantém CI e runs herméticos honestos.

MLX (--online): createMlxVisionBackend é um wrapper de subprocess sobre o python/vision_describe.py empacotado no próprio pacote (mlx-backend.ts:62–63), com modelo default mlx-community/Qwen3-VL-30B-A3B-Instruct-4bit — o comentário no código registra o porquê: "MoE, 3B active — benchmarked fastest + most accurate on M5 Max" (mlx-backend.ts:47, constante em :56). O helper roda o VLM a temperatura 0, então input idêntico ⇒ descrição idêntica (mlx-backend.ts:10–11) — determinismo que permite cachear descrições em disco.

alembic vision-index <family-root> (apps/cli/src/commands.ts:918–1025) constrói o índice de entendimento visual de uma família wiki: enumera os packages, colhe as imagens de cada media_manifest.json (commands.ts:894–900), descreve SÓ as ainda-não-indexadas e appenda { sourcePath, image, description, model } em <data-dir>/vision-index/<family>.jsonl (commands.ts:941). O doc do comando é explícito: "append-only, dedupe-by-image — a re-run appends 0. NEVER writes into the corpus" (commands.ts:922–925) — a única escrita do comando é no indexPath (commands.ts:991–999); o corpus é tratado como só-leitura.

O gate de QA de vídeo do marketing (packages/marketing-factory/src/validate.ts) precisa de visão para varrer frames por visuais proibidos — mas o pacote é dependency-light DE PROPÓSITO. A solução é um port: FrameDescriber (validate.ts:50–52), cujo default é o honesto noopFrameDescriber que devolve '' (validate.ts:179–181) — sem injeção, NENHUM forbidden-visual é detectável, e o gate não finge que olhou.

Os dentes reais moram na CLI, que já depende de @alembic/vision: createFrameDescriber (apps/cli/src/marketing-seams.ts:47–56) embrulha describeImages num describer de frame único. Dentro do gate, scanFrames descreve cada frame amostrado e testa desc.includes(normalize(forbidden)) — cada hit vira um VisualFlag (validate.ts:462–470), e flags viram falha: visual: N forbidden-visual flag(s) (validate.ts:583). A varredura só roda quando alguém a pediu: checkFrames = noBakedText || forbiddenVisuals.length > 0 (validate.ts:518) — o gate serve QUALQUER tipo de vídeo.