Step 19 · Hands-on lab · Hands-on lab · Lab: Extend Alembic with a new collector or adapter ENPT
Alembic Complete Visual Course

Lab: Extend Alembic with a new collector or adapter

Walk through adding a new source type or model adapter and prove it with tests.

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

Make the monorepo yours

Alembic is designed to be extended. This lab has two tracks:

  • Track A — Collector: Add a new source type to @alembic/ingestion. For example, a Notion exporter, a YouTube transcript fetcher, or an RSS feed reader.
  • Track B — Adapter: Add a new model adapter to @alembic/adapters. For example, a local Ollama adapter or a new OpenAI-compatible endpoint.

In both tracks you edit the contract, implement the interface, add tests, and run the verification command.

Think of it like… adding a new power socket type to your house: the wiring rules stay the same, but the plug changes.

Under the hood

A collector implements the eight-phase contract and returns a WikiPackage. An adapter implements ModelAdapter and is registered through createAdapterRegistry. For adapters, add the model id and pricing to packages/contracts/src/registry.ts. For collectors, add a CLI subcommand in apps/cli/src/args.ts and a runner in commands.ts.

2

In one picture

Track Anew collector Contracttypes + tests Track Bnew adapter
Both extension tracks pass through the contracts layer and must include tests.
3

In the code

# verify the whole monorepo after changes
pnpm -r typecheck
pnpm -r build
pnpm -w test

# run just the package you changed
pnpm --filter @alembic/ingestion test

Implementation notes

Tests for adapters should assert on ModelRunResult shape and failure modes, not on live responses. Use nock or a local mock server. Tests for collectors should assert each phase: preflight, cursor, capture, materialize, validate. The offline adapter in @alembic/adapters is a good reference for deterministic behavior.

4

Try it

Pick Track A or B. Implement the minimal version, add one test, and run the package's test suite. Then run the full verification command.

Design: Why must an adapter never throw?
5

Quick check

Where do you register a new model id and pricing?