AI models and provider catalog
Overview
Path routing coverage: this doc owns packages/ai/**. Route changes under this glob here, including runtime APIs in packages/ai/src/**, generated and source catalog files under packages/ai/catalog/** and packages/ai/src/providers/**, package scripts in packages/ai/scripts/**, package entrypoints in packages/…/package.json, and tests under packages/ai/test/**.
packages/ai is the @earendil-works/pi-ai package: a side-effect-light core model/provider abstraction plus generated built-in model catalogs. packages/…/package.json exposes the main entrypoint (src/index.ts), generated static model catalog (src/models.ts through src/…/all.ts and src/models.generated.ts), provider factories (src/providers/*), legacy compatibility (src/compat.ts), OAuth helpers, Bedrock wrappers, and utility subpaths.
The public runtime starts with src/index.ts, which deliberately exports only core types, createModels(), model-store support, provider-free utilities, and lazy API type surfaces. It avoids loading generated catalogs or provider factories. Built-in provider registration lives in src/…/all.ts: builtinProviders() constructs every provider factory, builtinModels() creates a Models collection and registers them, and typed getters (getBuiltinModel, getBuiltinImageModel, getBuiltinClassifierModel, getAllBuiltinModels) read from src/models.generated.ts.
src/models.ts defines the central Models and Provider contracts. A Provider owns auth, model lists, optional dynamic refresh, and operation implementations for chat streaming, image generation, and classification. createProvider() merges static models with a dynamic overlay returned by fetchModels(), dispatches chat/image/classifier operations by each model's api, and preserves chat-only behavior for legacy getModels() while getAllModels() includes image and classifier entries. createModels() wraps providers with credential resolution, context normalization, header/env/identity merging, and request delegation. It also coordinates refresh(): cached dynamic lists are restored from a ModelsStore, optional network refreshes run only for configured providers, publications are serialized per provider, and stale generations are discarded.
The catalog's model shape is defined by src/types.ts and src/…/model-schema.ts. Chat models omit or use type: "chat" and carry reasoning, thinkingLevelMap, prompt-cache metadata, costs, context windows, max output, sampling defaults, and provider/API-specific compat. Image models use type: "image", output, and generateImages(). Classifier models use type: "classifier" and classify(). src/model-catalog.ts turns generated provider JSON shards into typed per-provider chat/image/classifier maps by flattening API groups and stripping the internal type: key prefix.
Generated model data is split into committed TypeScript wrappers and JSON shards. Each generated src/…/<provider>.models.ts imports src/…/<provider>.json and exports *_MODELS, *_IMAGE_MODELS, and *_CLASSIFIER_MODELS through flatten*ModelCatalog(). src/models.generated.ts imports those wrappers and aggregates provider-keyed MODELS, IMAGE_MODELS, and CLASSIFIER_MODELS. The src/providers/data/** JSON files are validated/generated artifacts: scripts/model-data.ts groups entries by API under keys like chat:<id>, image:<id>, and classifier:<id>, validates ids/provider/api/type/cost/limits, and checks .manifest.json hashes and schema version.
Catalog source authoring happens under catalog/. catalog/generate.ts is the build/hydration driver used by package.json scripts: generate-models writes generated wrappers and data; hydrate-model-data updates only JSON data for existing provider shards; generate-model-catalog writes public JSON (models.json, models.all.json, provider files) for distribution. It fetches upstreams with catalog/…/index.ts (models.dev, decision metadata, OpenRouter, Vercel AI Gateway, NVIDIA ids, Radius config), then catalog/build.ts runs each catalog/…/<id>.ts definition. Provider definitions create chat/image/classifier entries, apply API-level compat defaults, run shared family rules from catalog/families/**, then run provider finalizers and image resize defaults. catalog/define.ts supplies helper operations such as modelsDevModels(), addMissing(), mergeCompat(), mergeThinking(), and image input-limit merging.
Runtime provider factories in src/…/<id>.ts bind generated catalog entries to implementation modules and auth. For example, src/…/openai.ts combines OpenAI chat and classifier catalogs, offers env-key and ChatGPT OAuth auth, and filters classifier models when an OAuth subscription credential is used. src/…/anthropic.ts has custom auth precedence for ANTHROPIC_AUTH_TOKEN, OAuth-token/API-key envs, and workload identity federation. src/…/openrouter.ts serves mixed chat APIs plus image and classifier APIs; personalizeOpenRouterCatalog() can filter and reprice chat entries with /models/user while leaving image/classifier entries unchanged.
Auth is part of provider behavior, not global state. src/…/helpers.ts provides envApiKeyAuth() and lazyOAuth() for most providers; src/…/resolve.ts defines the Models auth contract: explicit request API keys win, stored credentials own the provider, OAuth is refreshed with locking before use, and ambient env is consulted only when no credential is stored. src/models.ts applies resolved auth to requests and model-level headers before dispatching. The older global API lives in src/compat.ts; it registers lazy API implementations by model.api, preserves deprecated static catalog getters, injects env API keys for direct global stream() calls, and routes built-in models through their provider when possible. src/images.ts is the legacy global image-generation entrypoint and requires explicit auth; Models.generateImages() is preferred because it resolves provider auth.
Tests in packages/ai/test/** cover both catalog and runtime contracts. test/generate-models-strict.test.ts asserts strict generation fails before mutating generated artifacts. test/image-model-data.test.ts checks OpenRouter image/classifier parsing and multi-operation ids. test/images-models.test.ts exercises model type discrimination, Models typed accessors, image auth dispatch, dynamic model refresh storage, and built-in image catalog exposure. test/env-api-keys.test.ts, OAuth-specific tests, provider-specific streaming tests, and test/fetch-option.test.ts protect auth precedence and adapter options.
Coupling
- If a provider is added or removed, update both catalog and runtime registration: add catalog/…/<id>.ts to catalog/…/index.ts, add or remove src/…/<id>.ts from src/…/all.ts, and update
KnownProviderin src/types.ts. The generated src/models.generated.ts and src/…/<id>.models.ts files only appear after catalog/generate.ts runs. - If generated data layout changes in catalog/generate.ts or scripts/model-data.ts, update src/model-catalog.ts and every generated wrapper template in catalog/generate.ts; runtime imports expect src/…/<provider>.models.ts to import ./…/<provider>.json and flatten API-grouped values by
type:idkeys. - If model fields, model types, costs, or modality limits change in src/types.ts or src/…/model-schema.ts, update validation in scripts/model-data.ts, catalog builders in catalog/build.ts/catalog/define.ts, and tests that assert model type behavior (test/images-models.test.ts, test/image-model-data.test.ts). Unknown stored model types are intentionally dropped by src/models.ts during refresh restore.
- If an API id or provider id changes, check
KnownApi/KnownProviderin src/types.ts, catalog provider definitions, generated catalog shards, runtime provider factories, and operation dispatch maps increateProvider()callers. A model whoseapilacks a matching implementation returns a stream/error result rather than falling back. - If auth behavior changes in a provider factory under src/…/*.ts, verify src/…/resolve.ts semantics and compat behavior in src/compat.ts:
Modelsuses stored credentials before ambient env, while compat directstream()can inject env API keys through src/env-api-keys.ts. - If catalog compat defaults or family rules change under
catalog/families/**orcatalog/providers/**, keep released-client compatibility in mind: public JSON emitted bycatalog/generate.ts --json-onlymay be consumed by older code whose runtime defaults differ from HEAD. - If image or classifier models are added for a provider, ensure the runtime provider factory includes
imagesorclassifiersmaps in src/…/<id>.ts; otherwiseModels.getAllModels()can list entries whose operation returns provider errors.
Risks
- Generated artifact consistency is fragile across catalog/generate.ts, scripts/model-data.ts, src/models.generated.ts, and src/…/*.models.ts. If generation fails mid-run or a manual edit bypasses the manifest, builds fail through
npm run check:model-data; test/generate-models-strict.test.ts specifically guards rollback-before-mutation behavior. - Public catalog changes can break released clients even when HEAD tests pass. catalog/README.md notes that pi.dev serves catalogs to clients at or above the minimum supported version, so removing explicit compat in catalog/…/*.ts can make older clients send unsupported request shapes.
- Multi-operation model ids can collide if type is ignored. scripts/model-data.ts keys stored JSON by
type:id, src/model-catalog.ts flattens by operation type, and test/image-model-data.test.ts/test/images-models.test.ts cover OpenRouter entries that have both chat and image forms; changing this identity logic can hide one operation behind another.