Step 02 · Foundation · Foundation · Contracts, tiers, and the model registry ENPT
Alembic Complete Visual Course

Contracts, tiers, and the model registry

The shared type spine that keeps every package speaking the same language.

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

Why contracts matter

@alembic/contracts is the only package with no internal dependencies. It defines the shapes every other package uses: how to ask a model for a completion, how to report success or failure, how to score a business opportunity, and how to structure a distilled wiki package.

Two ideas are especially important:

  • Tiers (T0–T4) are an autonomy/risk ladder. T0 is deterministic and free; T4 is parked for human approval.
  • Never-throws: every adapter returns a Result; callers branch on ok instead of catching exceptions.

Think of it like… the metric system in science: everyone uses the same units so measurements can be combined safely.

Under the hood

The package exports Zod schemas and inferred types: ModelRunInput, ModelRunResult, ModelAdapter, Tier, BusinessSignal, WikiPackage, CouncilDecision, and a hard-coded MODEL_REGISTRY mapping model ids to adapters, tiers, and per-1k pricing. To add a new model, you edit 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 are an autonomy ladder: lower tiers are cheaper and autonomous; T4 is parked for humans.
3

In the code

// pick the cheapest model for a tier
import { Tier, pickCheapestForTier } from '@alembic/contracts';
const entry = pickCheapestForTier(Tier.T2);
console.log(entry?.modelId);

Implementation notes

MODEL_REGISTRY is the single source of truth for model capability and cost. pickCheapestForTier filters by tier and returns the lowest-cost entry. The registry also records whether a model supports tool use, JSON mode, or vision, so the adapter layer can refuse incompatible requests.

4

Try it

Open packages/contracts/src/registry.ts and count how many models are registered. Which tier has the most options?

Design question: Why is the registry hard-coded instead of fetched from a remote config?
5

Quick check

What does T4 mean in the Alembic tier ladder?