Step 02 · Foundation · Foundation · Contracts, tiers e o registro de modelos ENPT
Alembic Complete Visual Course

Contracts, tiers e o registro de modelos

A coluna vertebral de tipos compartilhados que mantém todos os pacotes falando a mesma linguagem.

Read the plain version, or open the technical layer on any section.
1

Por que contracts importam

@alembic/contracts é o único pacote sem dependências internas. Ele define as formas que todos os outros pacotes usam: como pedir uma completion a um modelo, como reportar sucesso ou falha, como pontuar uma oportunidade de negócio e como estruturar um pacote wiki destilado.

Duas ideias são especialmente importantes:

  • Tiers (T0–T4) são uma escada de autonomia/risco. T0 é determinístico e gratuito; T4 é estacionado para aprovação humana.
  • Never-throws: todo adapter retorna um Result; callers ramificam em ok em vez de capturar exceções.

Pense assim… o sistema métrico na ciência: todos usam as mesmas unidades para que medições possam ser combinadas com segurança.

Under the hood

O pacote exporta schemas Zod e tipos inferidos: ModelRunInput, ModelRunResult, ModelAdapter, Tier, BusinessSignal, WikiPackage, CouncilDecision e um MODEL_REGISTRY hard-coded mapeando ids de modelos para adapters, tiers e preço por 1k tokens. Para adicionar um novo modelo, edite packages/contracts/src/registry.ts.

2

In one picture

T0 $0 T1 cheap T2 balanced T3 strong T4 parked Risk and cost increase → autonomy decreases at T4
Tiers são uma escada de autonomia: tiers baixos são mais baratos e autônomos; T4 é estacionado para humanos.
3

In the code

// escolha o modelo mais barato para um tier
import { Tier, pickCheapestForTier } from '@alembic/contracts';
const entry = pickCheapestForTier(Tier.T2);
console.log(entry?.modelId);

Implementation notes

MODEL_REGISTRY é a única fonte da verdade para capacidade e custo de modelos. pickCheapestForTier filtra por tier e retorna a entrada mais barata. O registro também registra se um modelo suporta tool use, JSON mode ou vision, para que a camada de adapter possa recusar requests incompatíveis.

4

Try it

Abra packages/contracts/src/registry.ts e conte quantos modelos estão registrados. Qual tier tem mais opções?

Questão de design: Por que o registro é hard-coded em vez de buscado de uma config remota?
5

Quick check

O que significa T4 na escada de tiers do Alembic?