transcribe / analyzeImage — portas de mídia

Duas ferramentas — fala-em-texto e compreensão de imagem — construídas no exato mesmo padrão de portas que você já viu seis vezes. Cada uma é um kernel de despacho minúsculo: validar o pedido (Zod), chamar o backend injetado, re-validar o resultado não confiável (Zod), retornar um Result. Esta é a prova de encerramento de que a disciplina escala: uma capacidade nova é uma porta + um kernel + uma costura fetch fina — nada mais.

01 · Duas ferramentas, uma única forma

Imagine um balcão de atendimento: você entrega um pedido, um funcionário terceirizado (que você pode trocar) faz o trabalho lá fora, e o balcão confere o que voltou antes de te devolver. O cliente do balcão nunca fala direto com o terceirizado. As duas ferramentas de mídia são exatamente isso — e a "pessoa terceirizada" é uma porta injetada: uma única função que retorna um Result. O módulo não importa nenhum SDK.

// packages/hermes/src/media/types.ts:133-148
export type TranscriptionBackend = (
  req: TranscriptionRequest,
) => Promise<Result<TranscriptionResult, Error>>;

export type VisionBackend = (
  req: VisionRequest,
) => Promise<Result<VisionResult, Error>>;

A simetria é a lição

As duas ferramentas não são "parecidas" — são a mesma forma, diferindo só nos schemas. Veja lado a lado: troque os nomes dos tipos e um kernel vira o outro.

Há, porém, uma assimetria que vale isolar — e ela está só no estágio 1. O pedido de transcribe é um XOR ("exatamente uma" de duas fontes); o de analyzeImage é o oposto, um AND: precisa de imageUrl (URL válida) e prompt (não-vazio), os dois obrigatórios. Mesma forma de kernel, portões de entrada de polaridades opostas.

02 · O kernel de transcribe, linha a linha

Aqui está o balcão inteiro, sem pular nada. São quatro movimentos e três pontos onde o caminho pode virar um err — e em nenhum deles a função lança uma exceção. Repare que a falha do backend é repassada como está (return transcribed), preservando o erro original.

// packages/hermes/src/media/media.ts:51-68 — transcribe
const parsedReq = transcriptionRequestSchema.safeParse(req);
if (!parsedReq.success) {
  return err(new Error(`Invalid transcription request: ${parsedReq.error.message}`));
}

const transcribed = await deps.backend(parsedReq.data);
if (!transcribed.ok) return transcribed;          // falha do backend ⇒ err (repassado)

const parsed = transcriptionResultSchema.safeParse(transcribed.value);
if (!parsed.success) {
  return err(new Error(`Invalid transcription result: ${parsed.error.message}`)); // saída não confiável
}
return ok(parsed.data);

analyzeImage (media.ts:76-93) é byte-a-byte a mesma forma — valida imageUrl + prompt, chama o backend, valida {analysis}, retorna Result. A simetria não é coincidência: é o padrão da Lição 05 aplicado mais uma vez.

03 · Validação cruzada: exatamente uma fonte de áudio

O pedido de transcrição modela uma fonte de áudio portável — uma URL que o backend busca, ou base64 inline — e impõe "exatamente uma" com uma refinação Zod. Pense num formulário com duas caixas: a regra não é "preencha pelo menos uma", é "preencha exatamente uma". Isso é um XOR (ou-exclusivo).

// packages/hermes/src/media/types.ts:62-74 — transcriptionRequestSchema
z.object({
  audioUrl: z.string().url('audioUrl must be a valid URL').optional(),
  audioBase64: z.string().min(1, 'audioBase64 cannot be empty').optional(),
  mimeType: z.string().min(1).optional(),
}).refine(
  (req) => (req.audioUrl === undefined) !== (req.audioBase64 === undefined),
  { message: 'exactly one of audioUrl or audioBase64 is required' },
);

O truque é o !== sobre dois testes === undefined: comparar dois booleanos com "diferente" é precisamente um XOR — verdadeiro só quando exatamente um dos lados é verdadeiro. Veja as quatro entradas possíveis:

04 · O colapso do envelope

A fonte Python retorna dicts planos: {success, transcript, provider, error} para STT e {success, analysis} para vision. O port não copia esses campos cegamente — ele colapsa o envelope. success/error viram o ok/err do Result; o núcleo de sucesso é aparado e renomeado para o idioma do motor.

05 · Trace um pedido na mão (passo a passo → agora você)

Você viu o kernel e o XOR. Agora execute-os na cabeça, devagar, para um pedido concreto — depois um caso é seu. Recuperar o procedimento (não só ver o resultado) é o que fixa.

06 · Os backends fetch — mapeamento defensivo, fallbacks de campo

Como o backend web (Lição 11), os backends de mídia são impls fetch finas sobre o fetch global (Node 18+, sem node-fetch, sem SDK, sem nova dependência). O fetch é um campo de config injetável, então os testes usam um fake e nunca abrem socket. Como o kernel re-valida tudo, o mapeador pode ser tolerante:

// packages/hermes/src/media/fetch-backends.ts:163-178 — mapeamento defensivo
const mapTranscriptionRow = (payload) => {
  const provider = readField(payload, 'provider');
  return {
    text: asString(readField(payload, 'text') ?? readField(payload, 'transcript')), // fallback
    ...(typeof provider === 'string' && provider.length > 0 ? { provider } : {}),
  };
};
const mapVisionRow = (payload) => ({
  analysis: asString(readField(payload, 'analysis') ?? readField(payload, 'content')), // fallback
});

O transporte em si — postJson — é o ponto onde falhas viram err. Três modos de falha, um destino:

Os três modos de falha têm testes dedicados: não-2xx → err (207–216), throw de rede → err (218–227), JSON não parseável → err (229–246). Nenhum abre socket; todos injetam um fetch fake.

07 · Por que o ML local é IGNORADO — uma decisão deliberada da matriz

A fonte suporta seis caminhos de transcrição: cinco provedores cloud (Groq, OpenAI Whisper, Mistral Voxtral, xAI Grok STT, ElevenLabs Scribe) e um caminho local faster-whisper (ML Python, baixa ~150 MB de modelo, território de GPU). A matriz de fusão não trata os seis igual. Diante de cada capacidade do Hermes, ela escolhe uma disposição — e aqui o veredito do docs/hermes-complete-map.md é "ADAPT cloud, IGNORE/sidecar local".

08 · As 20 provas — o que cada teste fixa

A confiança neste kernel não é fé: são 20 casos em três blocos describe, todos offline (fake backend ou fake fetch), todos sem socket. Veja como eles se distribuem — e repare que cada modo de falha do desenho tem um teste correspondente.

09 · Como isso se encaixa

Estas duas ferramentas não vivem sozinhas — elas são dois dos sentidos do agente no mundo: ouvidos (transcribe) e olhos (analyzeImage). Quando o motor precisa virar uma fala em texto ou descrever uma imagem, são elas que atendem, sempre pela porta injetada. Veja a peça (destacada) no lugar dela na máquina: o que a alimenta à esquerda, o que ela alimenta à direita — e, embaixo, o caminho que a matriz deliberadamente deixou de fora.

10 · Na prática

Leia texto dentro de uma imagem — offline, determinístico, sem rede (o gêmeo de OCR do balcão desta lição):

# @alembic/ocr · offline $0 por padrão; --online precisa de docs/ocr-setup.md
alembic ocr ./fixtures/recibo.png
# ocr: ./fixtures/recibo.png
# <texto reconhecido, determinístico offline>
#
# --online liga o backend SGLang (ALEMBIC_OCR_BASEURL, ex. http://127.0.0.1:10000);
# sem essa env ele FALHA FECHADO com mensagem acionável — nenhuma rede é tentada.

Descreva as imagens de uma família do wiki — append-only, deduplicado por imagem, e nunca escrevendo no corpus (a disciplina de proveniência da Lição 26):

# @alembic/vision · descreve cada imagem do pacote → <data-dir>/vision-index/<family>.jsonl
alembic vision-index ~/Documents/Resources/Bookmarks
# vision-index: Bookmarks (~/Documents/Resources/Bookmarks)
#   packages: 128, images: 412, described: 412, rows written: 397, backend: offline
#   index: ~/.alembic/vision-index/Bookmarks.jsonl
#
# offline = determinístico ($0). --online usa o MLX-VLM local (docs/vision-setup.md).
# Descrições vazias (falha por-imagem) NÃO são gravadas → retentáveis no próximo run.

Transcrição → notas estruturadas. O notes consome uma transcrição já em texto e extrai título, decisões e action items — o passo rio abaixo do transcribe desta lição:

# @alembic/hermes meeting-notes · offline; a data padrão vem do relógio do CLI
alembic notes ./fixtures/reuniao.txt
# notes: Sync de produto (2026-06-27)
#   summary: Offline deterministic meeting-notes placeholder (no model called).
#   participants: (none)
#   decisions: 0 | action items: 0
#
# offline é um placeholder determinístico (nenhum modelo chamado); --online preenche de verdade.

As três saídas acima são o formato real impresso por apps/cli/src/commands.ts (runOcr, runVisionIndex, runNotes); os números/textos são ilustrativos. Para a baseline do monorepo (CLAUDE.md): pnpm -r typecheck && pnpm -r build && pnpm -w test.

E para isolar exatamente este kernel — transcribe/analyzeImage de @alembic/hermes — rode a suíte do pacote. Os 20 casos da seção 08 injetam um backend (ou fetch) fake e nunca abrem socket:

# roda só o pacote @alembic/hermes — onde vive src/media/ (media.ts, fetch-backends.ts)
pnpm --filter @alembic/hermes test
# …
# ✓ src/media/media.test.ts  > transcribe ok por URL e por base64       (fake backend)
# ✓ src/media/media.test.ts  > nenhuma/ambas fonte → err, backend não chamado (XOR na fronteira)
# ✓ src/media/media.test.ts  > analyzeImage rejeita prompt vazio        (AND na fronteira)
# ✓ src/media/media.test.ts  > non-2xx / throw de rede / JSON inválido → err (fetch FALSO)
# ✓ src/media/media.test.ts  > campo numérico coagido a '' antes do Zod (defesa em profundidade)
# Test Files  1 passed
# Tests      20 passed   ← as 20 provas desta lição, todas sem rede

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.