webSearch / webExtract — portas sobre fetch

Duas ferramentas — buscar na web e extrair uma página — construídas como um kernel de despacho fino sobre uma porta WebBackend injetada, com uma costura opcional Compressor para sumarização LLM que economiza tokens. O kernel não resolve nada sozinho: valida o pedido, chama o backend injetado, re-valida o resultado não confiável com Zod, e devolve um Result. O backend de produção é uma impl fetch sem nenhuma dependência. É um CLONE do web_tools.py do Hermes (1378 LOC).

01 · Duas ferramentas, um kernel de despacho

Imagine um balcão de recepção. Quem chega faz um pedido ("busque isto", "leia aquela página"); a recepcionista não sai correndo atrás da informação — ela confere se o pedido faz sentido, repassa para o fornecedor certo, confere de novo o que voltou, e só então entrega. O kernel webSearch/webExtract é exatamente esse balcão: ele despacha, não resolve.

A moeda do subsistema: Result, nunca exceção

Tudo que pode falhar aqui devolve um Result<T, Error> de @alembic/contracts — uma união discriminada de dois formatos. Nada é lançado através da borda. Quem consome decide pelo campo .ok:

02 · As duas portas injetadas

A fonte (o web_tools.py) se constrói ao redor de duas costuras: um registro de provedores (Exa / Firecrawl / Parallel / Tavily) e um passo opcional de compressão por LLM. No CLONE, cada costura vira uma porta injetada. Este módulo não importa nenhum SDK e nenhum backend concreto — só os tipos:

// packages/hermes/src/web/types.ts:120-140
export interface WebBackend {
  search(query: WebSearchQuery): Promise<Result<readonly WebSearchResult[], Error>>;
  extract(url: string): Promise<Result<WebExtractResult, Error>>;
}
export type Compressor = (
  text: string, instruction: string,
) => Promise<Result<string, Error>>;        // opcional; ausente ⇒ conteúdo bruto

Repare na assimetria que o tipo já carrega: search devolve ok([]) para "sem resultados" mas err para "provedor caiu" — a diferença vive no tipo, exatamente como o data.web vazio da fonte. O Compressor espelha a costura ReviewProposer do loop de aprendizado: "uma chamada de modelo em prod, um fake em testes".

As duas portas, lado a lado

As duas costuras existem por motivos diferentes — uma para obrigatório e intercambiável, outra para opcional e caro:

Anatomia do que volta: WebSearchResult, campo por campo

O que o backend devolve é validado contra o webSearchResultSchema. São três campos, e cada um carrega uma regra — repare que só o url tem validação estrutural (não basta ser string, tem que ser uma URL):

O que mudou da fonte: a linha aparada

A fonte Python carrega {title, url, description, position} por linha. O CLONE apara: descarta o position e renomeia description para o idiomático snippet. Menos campos, nomes do motor:

03 · Defesa em profundidade: mapear, depois re-validar

Pense em duas catracas antes de a informação entrar no sistema. A primeira (o backend) é tolerante: nunca trava, transforma o que vier em algo de formato conhecido. A segunda (o kernel) é rígida: confere o contrato e barra qualquer linha estruturalmente inválida. O fluxo tem essas duas fronteiras — o backend fetch mapeia o JSON não confiável defensivamente, e depois o kernel re-valida cada linha com Zod:

// packages/hermes/src/web/web.ts:69-90 — webSearch
const parsedQuery = webSearchQuerySchema.safeParse(query);
if (!parsedQuery.success) return err(new Error(`Invalid web search query: …`));
const found = await deps.backend.search(clampQuery(parsedQuery.data)); // clamp [1,100]
if (!found.ok) return found;
const validated: WebSearchResult[] = [];
for (const raw of found.value) {
  const parsed = webSearchResultSchema.safeParse(raw);   // linha de backend não confiável
  if (!parsed.success) return err(new Error(`Invalid web search result: …`)); // 1 ruim ⇒ falha tudo
  validated.push(parsed.data);
}
return ok(validated);

04 · Siga uma chamada de webSearch, passo a passo

Você viu o código e o fluxograma. Agora percorra uma execução real, devagar, do pedido ao Result — depois um caso é seu. Recuperar o procedimento (não só ver o resultado) é o que fixa de verdade.

05 · O clamp [1, 100] — proteção na borda

Quanto um chamador pode pedir? A fonte limita com min(max(limit, 1), 100); o CLONE faz igual, e antes de o backend ver o número. Pedir 9999 não é erro — é silenciosamente limitado a 100:

// packages/hermes/src/web/web.ts:134-139 — clampQuery
const clampQuery = (query) => {
  if (query.maxResults === undefined) return query;   // ausente ⇒ passa direto
  const clamped = Math.min(Math.max(query.maxResults, MIN_RESULTS), MAX_RESULTS); // MIN=1, MAX=100
  return { ...query, maxResults: clamped };
};

Arraste o slider: veja qualquer pedido cair na faixa [1, 100]. Abaixo de 1 sobe para 1; acima de 100 desce para 100; ausente passa direto. A barra mostra o valor que o backend realmente recebe:

O teste "clamps maxResults into [1, 100]" envia 9999 e 1 e afirma que o backend vê exatamente [100, 1] — a prova viva desta borda.

06 · Vazio ≠ erro: a distinção que protege você

Aqui mora uma decisão de design que parece pequena e é enorme. "Não achei nada" e "não consegui buscar" são coisas diferentes, e o tipo as mantém separadas: uma busca vazia é ok([]) (sucesso!), uma queda do provedor é err. Confundi-las esconderia uma queda real atrás de um inofensivo "sem resultados".

07 · Compressão opcional — limitada por um piso

Para webExtract, um Compressor injetado pode encolher páginas grandes para poupar tokens. Mas comprimir custa uma chamada de modelo — então só vale a pena acima de um piso de tamanho. A regra é dupla: pula se não há compressor ou se o conteúdo está abaixo do piso (padrão 5000):

// packages/hermes/src/web/web.ts:118-132 — maybeCompress
const minLength = deps.compressMinLength ?? DEFAULT_COMPRESS_MIN_LENGTH;  // 5000
if (compressor === undefined || result.content.length < minLength) {
  return ok(result);                            // sem compressor / pequeno demais ⇒ bruto
}
const compressed = await compressor(result.content, instruction);
if (!compressed.ok) return compressed;          // falha do compressor ⇒ err (falha fechado)
return ok({ ...result, content: compressed.value });

Três caminhos, decididos por dois testes simples. Siga o fluxograma de cabeça:

08 · O backend fetch — zero dependência, zero socket no teste

A porta WebBackend precisa de uma implementação real para produção. É o createFetchBackend: ele fala uma API JSON genérica sobre o fetch global do Node (Node 18+) — sem node-fetch, sem SDK, sem nenhuma dep nova. É o único módulo aqui que toca a rede. E ainda assim os testes nunca abrem um socket, porque o próprio fetch é um campo de config injetável:

// packages/hermes/src/web/fetch-backend.ts:71-72
export const createFetchBackend = (config: FetchBackendConfig): WebBackend => {
  const doFetch = config.fetch ?? (globalThis.fetch as unknown as FetchLike); // default = global; teste injeta fake

O backend é fino: emite o request, eleva falhas de transporte para err, e mapeia o payload defensivamente. Três falhas de transporte viram err — provadas por três testes com fetch fake:

O mapeamento defensivo, por dentro

Como o backend "nunca lança no lixo"? Lendo cada campo com fallback e coerção. mapSearchRows aceita results ou web, e por linha lê snippet ou description; qualquer forma desconhecida vira '' (via asString) ou [] (via asArray):

O caminho do webExtract — linear, com a costura no fim

O webExtract é um pipeline reto: extrai pela porta, valida na borda, e só então decide sobre a compressão. Cada etapa pode curto-circuitar para err:

09 · Os trade-offs, lado a lado

Toda a lição gira em torno de divisões deliberadas de responsabilidade. Veja-as explícitas: quem mapeia vs quem valida, e o que é o kernel vs o que NÃO é (o que ficou de fora do CLONE de propósito).

E o que não está aqui? O CLONE é o kernel de dados + despacho, não a plataforma inteira. A fonte (1378 LOC) tem muito mais — deliberadamente fora de escopo:

10 · Como isso se encaixa

Este subsistema não vive sozinho — ele é uma das mãos do agente no mundo. Quando o motor precisa de fato fresco (uma busca) ou de ler uma página (extract), é o webSearch/webExtract que atende, sempre pela porta injetada. Veja a peça (destacada) no lugar dela na máquina: o que a alimenta à esquerda, e o que ela alimenta à direita.

11 · Na prática

Rode a suíte que exercita este subsistema — ela injeta um fetch fake, então prova o mapeamento e os caminhos de falha sem tocar a rede:

# roda só o pacote @alembic/hermes — onde vive src/web/ (web.ts, fetch-backend.ts)
pnpm --filter @alembic/hermes test
# …
# ✓ src/web/web.test.ts  > clamps maxResults into [1, 100]       (9999 → 100, 1 → 1)
# ✓ src/web/web.test.ts  > empty search is ok([]) , not err       (vazio ≠ erro)
# ✓ src/web/web.test.ts  > rejects a row whose url is not a URL   (err, fail-closed)
# ✓ src/web/web.test.ts  > skips the compressor below the floor   (3000 < 5000 → bruto)
# ✓ src/web/web.test.ts  > fake fetch maps description → snippet  (sem socket)
# Test Files  1 passed
# Tests      18 passed   ← os 18 caminhos desta lição, todos com fetch FALSO

A contagem (18) é a desta lição na data de escrita; o que importa é que passa sem abrir um socket — o fetch injetável é o que torna isso possível. Para a baseline do monorepo inteiro (CLAUDE.md): pnpm -r typecheck && pnpm -r build && pnpm -w test.

E é assim que você usa a peça em código — a API real, do jeito que o motor a chama (a porta resolve a rede, o kernel re-valida):

// 1) construa o backend de produção (fetch global; nenhuma dep nova)
import { createFetchBackend } from '@alembic/hermes';
import { webSearch, webExtract } from '@alembic/hermes';

const backend = createFetchBackend({ endpoint: 'https://api.example.com' }); // endpoint injetado, nunca hardcoded

// 2) busque — o kernel valida o pedido, clampa p/ [1,100] e re-valida cada linha
const hits = await webSearch({ query: 'alembic harness', maxResults: 50 }, { backend });
if (!hits.ok) return hits;            // err propagado — provedor caiu (≠ busca vazia, que é ok([]))
for (const r of hits.value) console.log(r.title, r.url, r.snippet);

// 3) extraia uma página; passe um compressor opcional p/ encolher acima do piso (5000)
const page = await webExtract('https://example.com/post', { backend });
// page.ok === true ⇒ page.value = { url, title, content }

Assinaturas reais: webSearch(query, { backend }) e webExtract(url, { backend, compressor? }) — ambas devolvem Result. Em teste, injeta-se fetch em createFetchBackend({ endpoint, fetch: fakeFetch }) e nenhum socket abre.

Fixe os conceitos (flashcards)

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

Simples vs técnico — escolha sua camada

A mesma ideia central, em dois níveis. Comece pelo simples; abra o técnico quando quiser a precisão:

Confusões comuns