CLAUDE.md

1# provider-registry — module instructions
2 
3The bundled AI **provider + model catalog**. This package has two faces:
4 
5- **Build-time**: a generation pipeline (`src/creators/` + `src/providers/` + `scripts/generate-catalog.ts`) that emits the three `data/*.json` files.
6- **Runtime**: schemas + `registry-loader.ts` that the app reads those JSON files through.
7 
8Full architecture: [docs/architecture.md](docs/architecture.md). Consumer API: [README.md](README.md).
9 
10## Cardinal rule — NEVER hand-edit `data/*.json`
11 
12`data/models.json`, `data/providers.json`, `data/provider-models.json` are **PURE GENERATED ARTIFACTS**. Editing them by hand is always wrong — the next `pnpm generate` silently reverts your change, and **CI rejects it**: the `catalog-hand-edit-check` job fails any PR that touches `data/*.json` without a matching change under `src/` or `scripts/`.
13 
14To change the catalog, edit the **source** and regenerate:
15 
16| You want to change… | Edit | Then |
17| --- | --- | --- |
18| a model's metadata (capabilities, modalities, context/limits, name) | `src/creators/<creator>.ts` | `pnpm generate` |
19| how a provider connects / which models it serves / its pricing & overrides | `src/providers/<provider>.ts` | `pnpm generate` |
20 
21`pnpm generate` reads the upstream catalogs (models.dev / OpenRouter text + image models) **live**; set `MODELSDEV_CACHE` / `OPENROUTER_CACHE` / `OPENROUTER_IMAGE_CACHE` to local files to cache them during dev. Always commit the **source change and the regenerated `data/*.json` together** — a data change with no source change reads as a hand-edit and CI blocks it.
22 
23## Source of truth
24 
25- **`src/creators/<creator>.ts`** — model **creators** (anthropic, openai, cohere, alibaba, …). Declares *what models exist* and their *intrinsic metadata*. Built with `defineCreator`. A creator is the home for capabilities/modalities/context — **creator owns metadata**.
26- **`src/providers/<provider>.ts`** — serving **providers** / gateways / clouds (dashscope, ppio, tokenhub, openrouter, aws-bedrock, …). Declares *how to connect* and *which models it serves* with per-provider `apiModelId`, pricing, and overrides. Built with `defineProvider` / `openaiCompatible` — **provider owns parameter support** (endpoints/transport, per-provider param sets).
27- **models.dev + OpenRouter** — read live at generation time to enrich metadata/pricing for the models the registry references (not committed; `pnpm generate` fetches them).
28 
29## Rules when editing source
30 
31- **Hand-list models with full metadata.** A creator model is `{ id, name, capabilities, … }` — never a bare `{ id }`. Add `name` + the relevant `capabilities` / `contextWindow` / `maxOutputTokens` / modalities; without them the model resolves with no capabilities.
32- **`imageGeneration`: creator carries `supports` (the param vocabulary) as the provider-agnostic DEFAULT; the provider carries `vendorTransport` (endpoint routing).** The runtime **replaces** `imageGeneration` wholesale (it does not deep-merge), so a model-level block must never contain a provider-specific `vendorTransport`, and any provider needing a custom endpoint restates the **full** block (supports + transport). See [docs/architecture.md#image-generation-design-b](docs/architecture.md#image-generation-design-b).
33- **`idPrefixes` must be vendor-specific.** A prefix claims every catalog id matching it, so a generic prefix (`rerank`, `embed`) will mis-attribute other vendors' models. Use the creator's own namespace (`rerank-v`, `command`, `c4ai`, …).
34- **A provider override whose `modelId` is not a base model must carry a standalone `name`** (vendor-exclusive). The catalog-invariants test fails on a dangling override (a `modelId` that is neither in `models.json` nor a named standalone).
35 
36## Verify (required before commit)
37 
38```bash
39pnpm --filter @cherrystudio/provider-registry generate   # regenerate data/*.json from source + live upstream
40pnpm --filter @cherrystudio/provider-registry test        # vitest: schema conformance + catalog invariants
41```
42 
43Commit the regenerated `data/*.json` alongside your `src/` change. Generation also re-pulls live upstream, so the data diff may include unrelated metadata/pricing drift since the last run — that's expected. CI enforces sync in **both** directions: the `catalog-hand-edit-check` job rejects a `data/*.json` change with no `src/`/`scripts/` change (a hand-edit), and the `catalog-source-sync` test (in `test:provider-registry`) rejects the reverse — a `src/` change you forgot to regenerate — by re-deriving the source-controlled facts (provider connection config, hand-listed creator models + their `ownedBy`/`name`, provider overrides) and diffing them against the committed JSON. It's deterministic (no upstream fetch), so it only covers source-derived data; upstream-enriched fields (pricing, inferred metadata) and overall correctness still rely on the schema/catalog-invariant tests above and code review.
44