Curso do Produto Alembic · Visual Course

O que é o Alembic

Ao final você sabe dizer, em uma frase, o que o motor faz com um corpus de IA jurídica — e por que ele cospe dois produtos, não um. É a primeira parada da única história que percorre o curso inteiro: do corpus bruto até a funcionária Iris.

Ilustração editorial de um alambique de cobre numa oficina quente: conhecimento bruto (livros, pergaminhos, cristais de dados) entra à esquerda e essência refinada pinga em frascos rotulados à direita. Paleta Warm-Neutral. — O Alembic como alambique: o conhecimento bruto entra, a essência refinada sai em frascos rotulados — LEARNINGS e BUSINESS SIGNALS.

Ao final, você consegue

Explicar o que é o Alembic em uma frase: motor de destilação + harness de agentes.
Nomear as duas saídas do motor e dar um exemplo de cada na história da advocacia.
Desenhar as três camadas e dizer qual comando vive em cada uma.
Explicar a cintura estreita (Result<T,Error>) e por que biblioteca nunca lança exceção.
Justificar por que tudo roda offline ($0) por padrão e o que --online muda.

Suposições tolas

Você é esperto — só é novo no Alembic. Assumimos muito pouco:

Você já abriu um terminal e rodou um comando (não precisa ser dev).
Você entende "uma pasta com arquivos". Só isso.
Você não precisa saber TypeScript, agentes de IA, nem o que é um "schema". Definimos cada termo no primeiro uso.

Leia primeiro

REVIEW.md — a história as-built do Alembic (raiz do repositório)

Esta lição destila o REVIEW.md + o CLAUDE.md (catálogo de comandos) na imagem mental mínima para operar o produto. Tudo aqui é o que está realmente construído — nada aspiracional.

Leia a versão simples, ou abra a camada técnica em qualquer seção.

A grande ideia

O Alembic é duas coisas grudadas: um motor de destilação e um harness de agentes. O motor lê conhecimento bruto e o refina; o harness pega o que foi refinado e orquestra agentes de IA para transformar isso em produto — com porteiras que reprovam trabalho ruim.

Pense no nome ao pé da letra. Um alambique (em inglês, alembic) é o aparelho do alquimista: você joga matéria-prima fervente de um lado e colhe essência destilada do outro. É exatamente o que o produto faz com conhecimento.

Pense como… uma destilaria de cachaça. Entra cana (barulhenta, cheia de bagaço); sai cachaça (clara, rotulada, pronta pra vender). O Alembic faz isso com transcripts, bookmarks e repositórios — entra ruído, sai essência rotulada. Onde a analogia quebra: a destilaria produz um líquido; o Alembic produz dois — e é isso que veremos a seguir.

Por baixo do capô

O Alembic é um monorepo TypeScript (ESM, pnpm workspaces, Turborepo) com 27 pacotes sob packages/* e um app de CLI em apps/cli. O "motor de destilação" é a família @alembic/etl + ingestion + embeddings + vision; o "harness" é @alembic/swarm + harness + mission + coda (os gates). Tudo conversa pela cintura estreita Result<T,Error> de @alembic/contracts (seção 5).

Estado provado: 1364 testes verdes, 18 ADRs registradas, ~103 PRs mergeados (fonte: REVIEW.md).

Esquerda → direita: o corpus bruto entra, o motor destila, e saem DOIS frascos rotulados — LEARNINGS e BUSINESS SIGNALS.

Lembre O Alembic não "resume" conhecimento. Ele destila: separa o que dá pra aprender (LEARNINGS) do que dá pra vender (SIGNALS).

Duas saídas, não uma

É aqui que o Alembic se diferencia de um "resumidor". Da mesma matéria-prima ele tira duas coisas com propósitos diferentes: LEARNINGS (conhecimento que você cita depois) e BUSINESS SIGNALS (oportunidades que viram produto).

Adivinhe antes de revelar

Você joga no funil uma pasta de transcripts e bookmarks sobre IA jurídica. O motor vai cuspir dois frascos. Um deles é "o que aprendemos sobre IA jurídica, com fonte". Qual é o outro?

O outro é um BUSINESS SIGNAL: uma oportunidade acionável — por exemplo, "fábrica de petições personalizadas". Esse signal é a semente da venture que percorre o curso inteiro até virar a campanha da C.D Advocacia e a funcionária Iris.

O mesmo corpus, dois destinos: LEARNINGS volta como conhecimento citável; o SIGNAL segue para o harness virar produto.

LEARNINGS vs BUSINESS SIGNALS

LEARNINGS — viram conhecimento. Citáveis, com proveniência (fonte + data + hash). Alimentam cursos, decisões e o próximo turno de contexto. Resposta à pergunta "o que eu sei agora?".

BUSINESS SIGNALS

Viram produto. São oportunidades pontuadas e priorizadas. Entram no harness para serem forjadas em venture. Resposta à pergunta "o que eu posso construir/vender?".

Dica Quando estiver em dúvida sobre "que saída é essa?", pergunte: isso me ensina algo (LEARNING) ou me dá uma oportunidade de produto (SIGNAL)?

Ilustração: um alambique de cobre enchendo dois frascos — um olivo (conhecimento), um clay (oportunidade). — As duas saídas, ilustradas: o mesmo destilado enche dois frascos distintos.

A história do curso

Para não trocar de exemplo a cada lição, o curso inteiro segue uma única história. Cada lição avança um trecho dela. Guarde este mapa — vamos voltar a ele toda vez.

A única história do curso: do corpus à Iris. A Lição 8 junta tudo numa execução ponta a ponta.

Esse fio condutor é uma escolha pedagógica deliberada: um exemplo concreto repetido fixa melhor que cinco exemplos abstratos. Sempre que aparecer "a C.D" ou "a Iris", é esta história.

As três camadas

O produto se organiza em três camadas que empilham. De baixo pra cima: capabilities atômicas (tijolos pequenos), depois o funil + harness (que combina os tijolos), e no topo as fábricas (produtos completos, como marketing e cursos).

Cada camada usa só a de baixo. Os tijolos da Camada 1 são $0/offline; as fábricas do topo orquestram tudo.

Camada	O que faz	Comando exemplo	Lição
3 · Fábricas	Produtos completos (marketing, cursos, funcionários)	`alembic marketing campaign`	5–7
2 · Funil + Harness	Destila o corpus e orquestra agentes com gates	`alembic distill` · `alembic run`	2, 4
1 · Capabilities	Tijolos atômicos, offline e determinísticos	`alembic embed` · `alembic triage`	3

Fixe os termos

Camada 1

O que é uma "capability atômica"?

clique p/ virar

Um tijolo pequeno e offline ($0, determinístico) que faz UMA coisa — ex.: embed gera vetores; triage classifica um issue. Compõem para cima.

Camada 2

Qual a diferença entre funil e harness?

clique p/ virar

O funil destila o corpus (distill); o harness orquestra agentes para forjar o resultado em produto (run), com gates.

Camada 3

Cite uma "fábrica" do Alembic.

clique p/ virar

A Marketing Factory (alembic marketing), os cursos (alembic course), ou o AI Employee (alembic employee) — a Iris.

Regra

Uma camada pode pular a de baixo?

clique p/ virar

Não. Cada camada compõe apenas a imediatamente inferior. As fábricas usam o harness, que usa as capabilities — nunca o contrário.

Ilustração: oficina isométrica de três andares — ferramentas embaixo, linha de montagem no meio, produtos no topo. — As três camadas, ilustradas: tijolos embaixo, montagem no meio, produtos no topo.

A cintura estreita: Result

Todas as peças do Alembic conversam por um único formato de resposta: Result<T, Error>. Toda função de biblioteca devolve ou um sucesso (com o valor) ou um erro (como valor também) — e nunca lança exceção. Erro é dado, não explosão.

Pense como… uma esteira de aeroporto com etiqueta. Cada mala volta com uma etiqueta verde ("ok, aqui está") ou vermelha ("falhou, eis o motivo"). Ninguém some, nada explode no meio do caminho — você sempre recebe a mala e a etiqueta. A "cintura estreita" é todo mundo ter que passar por essa mesma esteira.

Por baixo do capô

Result<T, E> mora em @alembic/contracts e é a narrow waist: o ponto fino da ampulheta por onde tudo passa. Como erro é valor ({ ok: false, error }) e não exceção, o fluxo é fail-closed — uma falha propaga limpa até o CLI, que a converte em exit code não-zero. Isso é o que permite encadear comandos num plan module determinístico sem um try/catch mascarar uma falha no meio.

Dois caminhos, ambos valores de retorno. Nada lança.

Fail-closed: o erro vira exit code, o pipeline para limpo.

packages/contracts/src — a forma do Result (simplificada)

type Result<T, E = Error> =
  | { ok: true;  value: T }
  | { ok: false; error: E };

// biblioteca NUNCA lança — devolve o erro como valor:
function parseSignal(raw: string): Result<Signal> {
  if (!raw) return { ok: false, error: new Error("corpus vazio") };
  return { ok: true, value: toSignal(raw) };
}

Cuidado Em código de biblioteca, nunca throw. Se você ver um try/catch engolindo erro no meio de um pipeline, é bug — a falha tem que voltar como Result.

Offline por padrão, $0

Todo comando do Alembic roda offline e determinístico por padrão — sem rede, sem custo, mesma entrada dá mesma saída. Para usar um modelo de verdade você opta explicitamente com --online (que pode custar e é "founder-gated" — destravado pelo dono).

Você consegue aprender e testar o produto inteiro sem gastar um centavo nem ter internet. O modo real é uma decisão consciente, nunca o padrão silencioso.

O default offline usa fakes determinísticos (ex.: triage devolve um placeholder estável; embed gera vetores determinísticos de 16 dims). --online faz preflight do gateway cliproxyapi (127.0.0.1:8317) + ALEMBIC_CLIPROXY_TOKEN; ausente → falha fechada, sem gasto. Para gasto pago (Higgsfield/Seedance) a marketing factory exige --approve e --yes juntos.

Offline (padrão)
$0 · sem rede · determinístico · CI hermético · perfeito pra aprender e testar.

--online (opt-in)

Backend real · pode custar · gated · uma porteira explícita, nunca acontece por acidente.

A porteira do --online: sem gateway+token, falha fechada a $0 — gasto exige o caminho "sim" explícito.

Experimente: a conta muda?

Clique nos modos e veja a barra de custo do mesmo comando (alembic embed) em cada um. Valores ilustrativos.

$0 · determinístico

—

O mapa dos 27 pacotes

O monorepo tem 27 pacotes. Não decore — entenda os grupos. Clique num grupo abaixo para ver o que ele faz e qual comando o usa.

—

Tudo se apoia em contracts (a cintura). O apps/cli é a porta única: cada alembic <cmd> chama um destes grupos.

Papo técnico (pode pular) A regra de build: pnpm -r typecheck && pnpm -r build && pnpm -w test tem que ficar verde a cada mudança. Turborepo orquestra; cada pacote tem sua própria suíte.

Um motor, muitas ventures

O Alembic não é um produto só — é a fábrica de produtos de uma holding. O mesmo motor destila vários corpora e gera vários signals; cada signal promissor vira uma venture com o mesmo ciclo de vida.

Um motor, N ventures. A "fábrica de petições" é a nossa história.

O alembic status reporta exatamente estas fases (default tier T4).

Lembrança rápida (lá da seção 2): o que faz um signal "merecer" virar uma dessas ventures? Ele ser acionável e bem pontuado no funil — não só interessante.

Ilustração: uma forja central ligada por tubos a várias oficinas-satélite (as ventures). — A holding, ilustrada: um motor central alimentando muitas ventures.

O loop & os gates

Como o Alembic constrói sem alucinar? Dois mecanismos: um loop que sempre prova na fronteira real, e um pipeline de gates que reprova trabalho ruim antes de seguir.

Cada volta executa UMA unidade e prova na fronteira real antes de decidir.

Cinco porteiras em série. A Proof Gate roda proof[] e reprova fechado.

O roteamento por tier: o trabalho sobe de tier conforme o risco; T4 sempre pausa para aprovação humana.

Determinismo: um plan module (alembic.plan.ts) não pode usar Date.now(), new Date() nem Math.random() — a VM rejeita. Sem isso, o cache + o resume não seriam confiáveis.

Ilustração: uma esteira passando um artefato por cinco arcos de inspeção sequenciais. — Os gates, ilustrados: o trabalho passa por porteiras sequenciais antes de seguir.

Recapitulando em slides

Antes do teste, um resumo em seis slides — uma ideia grande por vez. Use Próximo/Voltar, as setas ← →, ou clique nos pontos.

A grande ideia

Motor de destilação + harness de agentes.

Entra conhecimento bruto; sai essência rotulada. O motor refina; o harness forja em produto.

Duas saídas

Não uma saída — duas.

LEARNINGS (conhecimento citável) e BUSINESS SIGNALS (oportunidade). Ex.: o signal "fábrica de petições".

Três camadas

Tijolos → funil+harness → fábricas.

Cada camada usa só a de baixo. embed embaixo; distill/run no meio; marketing/employee no topo.

A cintura estreita

Erro é valor, não exceção.

Tudo passa por Result<T,Error>. Biblioteca nunca lança — devolve ok ou err. A falha propaga limpa (fail-closed).

Offline por padrão

$0 até você dizer o contrário.

Todo comando roda offline, determinístico, sem rede. --online é a porteira explícita que pode custar — nunca por acidente.

Para levar

Uma história: do corpus à Iris.

corpus jurídico → signal de petições → venture → campanha C.D → a funcionária Iris. Cada lição avança um trecho.

1 / 6 setas ← →

Experimente & fixe

Você não precisa de nada instalado para o primeiro contato: o modo offline é $0. Aqui está o passo a passo do "olá, mundo" do Alembic — e logo abaixo, um teste rápido pra fixar.

Exemplo guiado · $0 offline

Garanta o build verde: pnpm -r build na raiz do repositório.

Gere um vetor offline do nosso signal: alembic embed "fábrica de petições".

Leia a saída real: 1 vector(s) of 16 dims (model text-embedding-3-small) — determinística, sem rede.

Agora você: rode alembic triage "petição com prazo vencido" e confira que sai medium/question · labels: needs-triage, sem chamar modelo nenhum.

Revisão acumulada

Três perguntas. O placar conta abaixo.

1. Quais são as DUAS saídas do motor de destilação?

LEARNINGS + BUSINESS SIGNALS. Um vira conhecimento citável; o outro, oportunidade de produto. "Resumo" e "PDF" são distrações — o motor destila, não formata.

2. Em código de biblioteca, o que uma função faz quando dá erro?

Devolve Result com ok:false. Erro é valor, nunca exceção (fail-closed). "Lançar" é exatamente o que a cintura estreita proíbe; "valor nulo" mascara a falha.

3. O que acontece se você rodar um comando SEM --online?

Roda offline e $0. O modo real é opt-in via --online (gated). Sem a flag, nada de rede nem custo — é o que torna o produto inteiro aprendível de graça.

Acertos: 0/3

As Dez coisas pra carregar desta lição

Alembic = motor de destilação + harness de agentes.
O motor cospe duas saídas: LEARNINGS e BUSINESS SIGNALS.
O curso segue uma história: corpus jurídico → signal de petições → venture → campanha C.D → Iris.
Três camadas: capabilities → funil+harness → fábricas.
Uma camada só usa a de baixo — nunca pula.
Tudo passa pela cintura estreita Result<T,Error>.
Biblioteca nunca lança exceção — erro é valor (fail-closed).
Offline $0 por padrão; --online é uma porteira explícita.
27 pacotes, mas o que importa são os grupos + o apps/cli.
Loop (prova na fronteira) + gates (reprovam o ruim) = construir sem alucinar.

Para ir além

CLAUDE.md — o catálogo canônico de todos os comandos alembic

Cada comando que veremos no curso está descrito ali, com a flag exata. A Lição 2 abre o funil de destilação.

REVIEW.md

a história as-built · 27 pacotes

AGENTS.md

referência rápida de arquitetura

docs/adr/

as decisões (ADR-0001..0018)

Eu sou seu professor neste curso — quando algo aqui não fechar, pergunte. Traga seu próprio corpus, questione onde a analogia da destilaria quebra, ou peça pra eu abrir qualquer arquivo real citado. A seguir, Lição 2 · O funil de destilação: como o corpus de IA jurídica de verdade vira o signal "fábrica de petições", tier por tier (T0→T3).