@x12i/ai-profiles 1.4.0 → 1.6.0

package/README.md

@@ -2,6 +2,86 @@
 
 Resolve AI profile names into concrete model choices. The package ships JSON in `src/data/` as the offline fallback. By default, registry data is fetched from public assets, validated, and cached in memory.
 
+## Why AI profiles
+
+Any system that runs many different AI tasks—classification, architecture review, JSON extraction, tool-using agents—faces the same problem: **tasks are not interchangeable**. They differ in reasoning quality, cost sensitivity, latency, output shape (prose vs schema vs citations), and which provider traits matter (instruction following, long context, tool use).
+
+Hardcoding one model everywhere leads to one of three failures: overpaying for simple high-volume work, under-serving hard problems with a weak model, or locking the product to a single vendor with no fallback when prices or availability change.
+
+### What a profile is
+
+An **AI profile** is **not** a model. It is a **capability contract**: a stable name for *what kind of work* you need, not *which SKU* fulfills it.
+
+When a graph node or function asks for `deep`, it means: high reasoning effort, complex work—resolve that intent to a concrete `provider` + `modelId` + runtime defaults **today**, without the caller caring whether that is Claude, GPT, or Gemini. The registry (`models-profiles.json`) is the mapping layer; profiles are the interface tasks depend on.
+
+### Profiles vs choices
+
+| Layer | Role | Example |
+|-------|------|---------|
+| **Profile** | Semantic intent (cost, speed, reasoning tier, output mode, agentic behavior) | `cheap`, `balanced`, `json`, `agentic` |
+| **Choice** | Implementation option within that profile (provider, model, batch vs sync, cost/quality trade-off) | `default`, `cost_floor`, `safer_provider` |
+
+Every profile has a **`defaultChoice`** (recommended) and typically **two alternatives** so operators can tune without changing task code:
+
+- **Provider diversity** — Anthropic (writing/reasoning), OpenAI (code/instruction following), Google (cost, long context) within the same profile.
+- **Cost flexibility** — e.g. `balanced` + `cost_balanced` vs `reasoning_balanced` for the same “normal work” intent.
+- **Capability variants** — e.g. `long_context_deep` when the constraint is window size, not reasoning tier alone.
+- **Execution mode** — e.g. `cheap` + `cost_floor` with `executionMode: batch` for background bulk work.
+- **Resilience** — swap choice or fall back within the same profile when a provider is down or rate-limited.
+
+**Shortcuts** (`profiles-shortcuts.json`) are named entry points that may pin a profile and optionally a choice (e.g. `cheapest` → `cheap` + `cost_floor`). **Aliases** on each profile are alternate names for the same profile (e.g. `economy` → `cheap`).
+
+Tasks should declare **requirements** (`profile` + optional `choice`), not model names. Profiles are the vocabulary; choices are how that vocabulary is implemented under different constraints.
+
+### Profile catalog (bundled)
+
+Profiles are grouped by **what kind of work** they represent—not only by price/quality tier. Several axes are orthogonal (structured output, agents, research, local inference).
+
+| Profile | Category | When to use it |
+|---------|----------|----------------|
+| `cheap` | cost | High-volume, non-critical work: routing, classification, simple transforms. “Cheap” means low-cost selection, not always the absolute cheapest SKU. |
+| `fast` | speed | Interactive UX where latency matters more than maximum reasoning depth. |
+| `balanced` | standard | Default workhorse: general graph execution, coding, product logic (~80% of tasks). |
+| `deep` | reasoning | Hard problems: architecture, planning, analysis, code review—work that needs real reasoning, not pattern matching. |
+| `pro` | premium | Critical outputs where quality or a wrong answer has high downstream cost; use sparingly. |
+| `json` | output | Strict JSON/schema, extraction, classification—machine-readable pipelines (`outputMode: schema`, low temperature). |
+| `agentic` | agentic | Tool use, planning, multi-step execution (`toolPolicy` allows writes with approval). |
+| `research` | research | Source-heavy reading, synthesis, citations (read-only tools, web/file search). |
+| `cyber` | security | Threat analysis, TPRM, contract verification, security log parsing. |
+| `content` | creative | Prose, marketing copy, programmatic SEO, brand voice. |
+| `summarization` | analysis | Document triage, digests, compressing very large corpora. |
+| `vision` | multimodal | Image understanding, OCR, charts, scanned PDF structure extraction. |
+| `coding` | engineering | Software engineering: implementation, refactors, reviews, debugging. |
+| `extraction` | extraction | NER, classification, taxonomy mapping, entity extraction, document labeling. |
+| `routing` | routing | Intent classification, record routing, workflow branching (cheapest viable). |
+| `open_weights` | resilience | Hosted open-source models (Llama, Qwen) as vendor hedge and self-host path (`deploymentType: openWeightsHosted`). |
+| `local` | local | On-device / offline CPU inference (privacy, edge, dev without API keys). |
+
+### Typical choices per profile
+
+Each profile’s `choices` in `models-profiles.json` follow a consistent pattern: **`default`** (recommended), plus variants along cost, provider family, or a specific capability.
+
+| Profile | Choices (bundled) | What the variants optimize |
+|---------|-------------------|------------------------------|
+| `cheap` | `default`, `cost_floor`, `safer_provider`, `absolute_floor` | Normal cheap vs batch floor vs safer Haiku vs DeepSeek V4 Flash volume floor |
+| `fast` | `default`, `cheaper_fast`, `quality_fast`, `grok_fast` | Interactive default vs lower cost vs stronger quality vs Grok 4.1 Fast (2M context) |
+| `balanced` | `default`, `reasoning_balanced`, `cost_balanced` | General default vs stronger reasoning vs lower cost |
+| `deep` | `default`, `openai_deep`, `long_context_deep`, `deepseek_pro`, `grok_flagship` | High reasoning default vs OpenAI vs long context vs cost-efficient DeepSeek vs Grok 4.3 |
+| `pro` | `default`, `claude_pro`, `cost_pro` | Premium default vs Claude premium vs Sonnet-level “pro-like” at lower cost |
+| `json` | `default`, `cheap_json`, `quality_json` | Reliable schema output vs volume/cost vs complex extraction needing reasoning |
+| `agentic` | `default`, `openai_agentic`, `cheap_agentic` | Agent default vs OpenAI orchestration vs lower-cost moderate agents |
+| `research` | `default`, `premium_research`, `long_context_research` | Synthesis default vs highest quality vs very large context |
+| `cyber` | `default`, `log_analysis`, `deep_forensics` | Policy/contract review vs bulk log JSON vs max forensics |
+| `content` | `default`, `pseo_bulk`, `brand_voice` | Natural prose vs batch pSEO schema vs premium copy |
+| `summarization` | `default`, `mega_context` | Fast digest (Haiku) vs multi-hundred-k token compression |
+| `vision` | `default`, `document_ocr` | General multimodal vs schema OCR from scans/PDFs |
+| `open_weights` | `default`, `multilingual_code` | Llama 3.3 70B vs Qwen 2.5 72B (coding / multilingual) |
+| `local` | `llama_cpp_gguf`, `transformersjs_default` | GGUF via llama.cpp vs Hugging Face Transformers.js on CPU |
+
+Bundled **shortcuts** that pin a choice include `cheapest`, `absolute-floor`, `grok-fast`, `deepseek-pro`, `qwen`, `cheap-json`, `audit`, `pseo`, `ocr`, and FuncX-style `weak` / `normal` / `strong` / `ultra` (see [Profile matrix](#profile-matrix-funcx-contract)).
+
+Registry fields on each choice—`runtime` (`reasoningEffort`, `toolPolicy`, `outputMode`, `instructionTier`, `backend`), `modelStatus` (`verified` | `predicted`), `api` (vendor + OpenRouter slugs), and `reason`—document *why* that model backs the choice. **Pricing and capabilities** come from `models-catalog.json` at resolve time. Profile-level `requiredCapabilities` describes intent for future dynamic selection (Optimixer). Consumers use `resolveAIProfile` to materialize the merged result.
+
 ## Install
 
 ```bash
@@ -10,17 +90,63 @@ npm install @x12i/ai-profiles
 
 ## Public API
 
+### Profiles and registry loading
+
 | Export | Sync? | Purpose |
 |--------|-------|---------|
 | `listAIProfiles(options?)` | No (async) | Profile summaries: primary `profile` key, `aliases[]`, choices, defaults |
+| `getAIRegistryStatistics(options?)` | No (async) | Counts: profiles, choices, providers, shortcuts, catalog models, linkage health |
+| `formatRegistryStatistics(stats)` | Yes | Human-readable summary for logs / CLI |
+| `loadAIProfilesRegistry(options?)` | No (async) | Raw profiles + shortcuts registry (`auto` / `remote` / `bundled`, 24h memory cache) |
+| `loadAIProfilesRegistryWithWarnings(options?)` | No (async) | Same as above, plus `warnings[]` (stale cache, bundled fallback, etc.) |
+| `loadModelsCatalog(options?)` | No (async) | Unified models catalog (`auto` / `remote` / `bundled`, same cache pattern as profiles) |
+| `loadBundledModelsCatalog()` | Yes | Package-shipped `models-catalog.json` only |
+| `loadBundledModelsRegistry()` | Yes | Package-shipped `models-registry.json` (linkage index) |
 | `listAIShortcuts()` | Yes | Shortcut table: `{ key, profile, choice?, description? }[]` |
-| `resolveAIProfile(input, options?)` | No (async) | Resolve input → model, pricing, runtime, canonical `profile` key |
-| `resolveUseOpenRouter(explicit?)` | Yes | Resolve OpenRouter vs vendor-direct routing (option → env → default) |
-| `buildOpenRouterModelId(provider, modelId)` | Yes | Build an OpenRouter slug (`openai/gpt-5.4`) from registry fields |
+| `resolveAIProfile(input, options?)` | No (async) | Resolve profile/shortcut/alias → model, pricing, runtime, canonical `profile` key |
 | `isKnownProfileOrShortcut(input)` | Yes (bundled only) | Whether input is a known primary key, shortcut, or alias |
 | `AIProfilesError` | — | Typed errors (`UNKNOWN_PROFILE`, …) |
 
-Registry JSON lives in `models-profiles.json` (profiles + aliases) and `profiles-shortcuts.json` (shortcuts).
+### Model identity (vendor + model strings)
+
+Use these when callers pass **raw model ids or OpenRouter slugs**, not profile names.
+
+| Export | Sync? | Purpose |
+|--------|-------|---------|
+| `resolveModelIdentity(input, options?)` | Yes | Given a bare id or `vendor/slug`, return `{ provider, modelId, invocation? }` via bundled registry + catalog fallback |
+| `buildModelInvocation(provider, modelId)` | Yes | `{ direct, openrouter }` endpoints for a provider hint + model string |
+| `buildDirectInvocation(provider, modelId)` | Yes | Vendor-direct `{ provider, modelId }`; splits prefixed slugs for all vendors |
+| `buildOpenRouterModelId(provider, modelId)` | Yes | Build an OpenRouter slug (`openai/gpt-5.4`) from registry fields |
+| `parseDirectFromOpenRouterSlug(slug, family?)` | Yes | Split `vendor/model` → direct slice (`custom` + bare id when vendor is not a first-class provider) |
+| `normalizeAnthropicVersionSlug(slug)` | Yes | Dotted minor versions for Anthropic (`4-6` → `4.6`) |
+| `buildRegistryKey(provider, modelId)` | Yes | Stable registry key (`vendor:…`) used in `models-registry.json` |
+| `matchOpenRouterCatalog(provider, modelId, index)` | Yes | Match a choice against a catalog index |
+| `lookupInvocationForChoice(registry, provider, modelId)` | Yes | Lookup prebuilt invocation from `models-registry.json` |
+
+**Prefixed slugs:** `buildDirectInvocation("meta-llama", "meta-llama/llama-3.1-8b-instruct")` yields `{ provider: "meta-llama", modelId: "llama-3.1-8b-instruct" }`. Host paths keep the nested id when the provider hint differs (e.g. Together: `together` + `meta-llama/Llama-3.3-70b-instruct`). Bare and prefixed Anthropic inputs normalize to the same direct and OpenRouter ids.
+
+### Routing, validation, and maintainer tooling
+
+| Export | Sync? | Purpose |
+|--------|-------|---------|
+| `resolveUseOpenRouter(explicit?)` | Yes | Resolve OpenRouter vs vendor-direct routing (option → env → default) |
+| `validateBundledProfileVendorCoverage(options?)` | Yes | Advisory report of leading-vendor coverage per profile |
+| `isProfileVendorTrimReady(profile, allowedProviders)` | Yes | Whether auto-pick can satisfy a vendor filter |
+| `listFaultyProfileChoices()` | Yes | Profile choices with faulty OpenRouter catalog linkage |
+| `buildModelsRegistry`, `verifyOpenRouterAlignment`, … | Yes | Catalog/registry build and alignment (see scripts below) |
+
+Registry JSON lives in four bundled assets:
+
+| File | Schema | Role |
+|------|--------|------|
+| `models-profiles.json` | `x12i.ai-profiles.model-registry.v3` | Profile intent, choices, `requiredCapabilities`, `modelStatus` — **no embedded pricing** |
+| `models-catalog.json` | `x12i.ai-profiles.models-catalog` | Per-model pricing, context window, capabilities (OpenRouter-normalized) |
+| `models-registry.json` | `x12i.ai-profiles.models-registry` | Built linkage index: vendor keys, OpenRouter slugs, `invocation` pairs |
+| `profiles-shortcuts.json` | `x12i.ai-profiles.shortcuts` | Named entry points |
+
+**v3 contract:** `modelId` is **vendor-native** (e.g. `claude-sonnet-4-5`). OpenRouter slugs live under `choice.api.openRouterModelId`. `resolveAIProfile` merges catalog data into `resolved.pricing`, `resolved.limits`, and `resolved.capabilities`. Default choices use **verified** SKUs; forward-looking models remain as alternates with `modelStatus: predicted`.
+
+Validate with `src/data/models-profiles.schema.json`. Maintainer scripts: `npm run migrate:profiles-v3`, `npm run registry:finish` (catalog supplement + verified defaults + linkage rebuild).
 
 ## Basic usage
 
@@ -39,11 +165,40 @@ console.log(model.profile); // canonical primary key: cheap
 console.log(model.provider); // "openrouter" by default for remote profiles
 console.log(model.modelId); // "google/gemini-2.5-flash-lite"
 console.log(model.routing); // "openrouter" | "direct"
-console.log(model.pricing);
+console.log(model.pricing); // from models-catalog.json
+console.log(model.modelStatus); // verified | predicted
+console.log(model.requiredCapabilities); // profile intent
+console.log(model.capabilities); // contextWindow, supportsTools, …
 console.log(model.instructionTier);
 console.log(model.backend);
 ```
 
+## Registry statistics
+
+Use **`getAIRegistryStatistics()`** for discovery dashboards, CI summaries, and operator tooling. It loads profiles and the models catalog with the same `source` / `refresh` options as `resolveAIProfile`, then returns structured counts.
+
+```ts
+import {
+  formatRegistryStatistics,
+  getAIRegistryStatistics,
+} from "@x12i/ai-profiles";
+
+const { statistics, warnings } = await getAIRegistryStatistics({
+  source: "bundled", // or "auto" | "remote"
+  includeCatalog: true,
+  includeLinkage: true,
+});
+
+console.log(statistics.profiles.total);
+console.log(statistics.profiles.providers);
+console.log(statistics.catalog?.totalModels);
+console.log(statistics.linkage?.faulty);
+
+console.log(formatRegistryStatistics(statistics));
+```
+
+CLI (after build): `npm run stats` (text) or `npm run stats:json`.
+
 ## Naming: many names, one profile
 
 Each **profile** has exactly one **primary key** (e.g. `balanced`, `cheap`) and **many aliases** — alternate strings that mean the same profile. Data is in `models-profiles.json` under each profile’s `aliases` array.
@@ -172,15 +327,31 @@ await resolveAIProfile("cheap", { useOpenRouter: true }); // still OpenRouter
 Helper exports:
 
 ```ts
-import { resolveUseOpenRouter, buildOpenRouterModelId } from "@x12i/ai-profiles";
+import {
+  resolveUseOpenRouter,
+  buildOpenRouterModelId,
+  buildModelInvocation,
+  resolveModelIdentity,
+} from "@x12i/ai-profiles";
 
 resolveUseOpenRouter(); // true by default
 resolveUseOpenRouter(false); // explicit override
 
 buildOpenRouterModelId("openai", "gpt-5.4"); // "openai/gpt-5.4"
+
+// Same direct + OpenRouter shape whether input is bare or prefixed:
+buildModelInvocation("anthropic", "claude-3-5-sonnet-20241022");
+buildModelInvocation("anthropic", "anthropic/claude-3-5-sonnet-20241022");
+
+// Bare model string → vendor + model (no profile name required):
+resolveModelIdentity("google/gemini-2.5-flash-lite");
+// { provider: "google", modelId: "gemini-2.5-flash-lite", invocation: { … } }
+
+resolveModelIdentity("google/gemini-2.5-flash-lite", { asOpenRouter: true });
+// { provider: "openrouter", modelId: "google/gemini-2.5-flash-lite", … }
 ```
 
-Tests: `test/resolveModelRouting.test.ts`.
+Tests: `test/resolveModelRouting.test.ts`, `test/modelIdentity.test.ts`, `test/resolveModelIdentity.test.ts`.
 
 ## Use bundled only
 
@@ -249,15 +420,25 @@ const modelConfig = {
 
 ## Profile matrix (FuncX contract)
 
-| Profile | Inference | Instruction tier | Example model |
-|---------|-----------|------------------|---------------|
-| `cheap` | Remote | **`default`** | `gemini-2.5-flash-lite` |
-| `fast` | Remote | **`default`** | `gpt-5.4-mini` |
-| `balanced` | Remote | **`default`** | `gpt-5.4` |
-| `deep` | Remote | **`reasoning`** | `claude-sonnet-4.6` |
-| `pro` | Remote | **`default`** | `gpt-5.5` |
-| `local` / `llama_cpp_gguf` | CPU | **`cpu`** | `funcx:llama-cpp:gguf` |
-| `local` / `transformersjs_default` | CPU | **`cpu`** | `Xenova/distilbart-cnn-6-6` |
+Default choice per profile (vendor-native ids in registry; OpenRouter slugs when `useOpenRouter` is true):
+
+| Profile | Inference | Instruction tier | Default choice | Example model |
+|---------|-----------|------------------|----------------|---------------|
+| `cheap` | Remote | **`default`** | `default` | `gemini-2.5-flash-lite` |
+| `fast` | Remote | **`default`** | `default` | `gpt-5.4-mini` |
+| `balanced` | Remote | **`default`** | `default` | `gpt-5.4` |
+| `deep` | Remote | **`reasoning`** | `default` | `claude-sonnet-4.6` |
+| `pro` | Remote | **`default`** | `default` | `gpt-5.5` |
+| `json` | Remote | **`default`** | `default` | `gpt-5.4-mini` (schema output) |
+| `agentic` | Remote | **`default`** | `default` | `claude-sonnet-4.6` |
+| `research` | Remote | **`reasoning`** | `default` | `claude-sonnet-4.6` |
+| `cyber` | Remote | **`reasoning`** | `default` | `claude-sonnet-4.6` |
+| `content` | Remote | **`default`** | `default` | `claude-sonnet-4.6` |
+| `summarization` | Remote | **`default`** | `default` | `claude-haiku-4.5` |
+| `vision` | Remote | **`default`** | `default` | `gpt-5.4` |
+| `open_weights` | Remote | **`default`** | `default` | `meta-llama/Llama-3.3-70b-instruct` |
+| `local` | CPU | **`cpu`** | `llama_cpp_gguf` | `funcx:llama-cpp:gguf` |
+| `local` | CPU | **`cpu`** | `transformersjs_default` | `Xenova/distilbart-cnn-6-6` |
 
 FuncX mode shortcuts (bundled): `weak` → local, `normal` → balanced, `strong` → pro, `ultra` → deep, `default` → balanced.
 
@@ -271,22 +452,57 @@ Remote profile choices in `models-profiles.json` use vendor-native `modelId` val
 - `modelId`: full slug such as `openai/gpt-5.4`
 - `routing`: `"openrouter"`
 
-Pass `useOpenRouter: false` (or `USE_OPENROUTER=0`) to get vendor-native `provider` + `modelId` for direct API calls. `@x12i/ai-tools` can still remap deprecated OpenRouter ids when the bundled catalog is stale.
+Pass `useOpenRouter: false` (or `USE_OPENROUTER=0`) to get vendor-native `provider` + `modelId` for direct API calls.
+
+Every resolved profile includes **`invocation`** with both call shapes:
+
+```ts
+resolved.invocation.direct    // { provider: "openai", modelId: "gpt-5.4" }
+resolved.invocation.openrouter // { provider: "openrouter", modelId: "openai/gpt-5.4" } | null
+```
+
+Top-level `provider` / `modelId` / `routing` remain the **active** path selected by `useOpenRouter`.
+
+### Vendor trimming
+
+Restrict resolution to specific vendors (auto-picks within the profile when the default is outside the set). **Leading vendors** (`openai`, `anthropic`, `google`, `deepseek`, `xai`) are **preferred** during auto-pick, not forced — explicit `choice` still honors `together` and other providers.
+
+```ts
+await resolveAIProfile("balanced", {
+  allowedProviders: ["google", "openai"],
+  preferLeadingVendors: true, // default
+});
+```
 
 ### Keeping models aligned over time
 
+Bundled linkage lives in `src/data/models-registry.json`, built from `models-profiles.json` and `src/data/models-catalog.json`.
+
+Each catalog model has **two explicit call shapes** (never `provider: "openrouter"` with `modelId: "qwen/..."` as the only view):
+
+- `direct` — vendor-native (`{ provider: "google", modelId: "gemini-3.5-flash" }`)
+- `openrouter` — transport (`{ provider: "openrouter", modelId: "google/gemini-3.5-flash" }`)
+
+Legacy open-assets files named `openrouter-models-catalog.json` are normalized into this shape on `catalog:pull`.
+
 When OpenRouter deprecates or renames a model slug:
 
 1. Update `src/data/models-profiles.json` to a current vendor-native id (preferred).
-2. Refresh the OpenRouter catalog in `@x12i/ai-tools` (`openrouter-models-catalog.json`).
+2. Refresh `src/data/models-catalog.json` via `npm run catalog:pull` (fetched from open-assets, normalized locally).
 3. Run alignment checks before publishing:
 
 ```bash
-npm run verify:openrouter       # bundled profiles vs ai-tools catalog (sibling or dev install)
-npm run verify:openrouter:live  # same vs live open-assets catalog (pre-release)
+npm run registry:finish         # merge profile catalog supplement, verified defaults, rebuild linkage
+npm run catalog:sync            # pull catalog, rebuild models-registry.json, verify
+npm run catalog:pull            # fetch open-assets catalog into src/data/
+npm run catalog:build           # rebuild models-registry.json + reports/fault-report.json
+npm run verify:openrouter       # alias for catalog:verify (fails on faulty OR linkage only)
+npm run verify:openrouter:live  # legacy script vs live catalog
 ```
 
-Unit tests in `test/openrouterAlignment.test.ts` and `test/resolveModelRouting.test.ts` guard resolution rules offline. Use `verify:openrouter` when updating profile model ids; use `verify:openrouter:live` after refreshing [open-assets](https://open-assets.x12i.com/openrouter-models-catalog.json).
+With the seed catalog (<50 models), choices not yet listed are marked `catalog-miss` in the registry (warnings in `reports/fault-report.json`, not CI failures). A full catalog promotes true `faulty` rows for slug mismatches.
+
+Unit tests in `test/openrouterAlignment.test.ts`, `test/modelIdentity.test.ts`, `test/resolveModelIdentity.test.ts`, and `test/resolveModelRouting.test.ts` guard resolution rules offline.
 
 Vendor-direct-only choices (not routed via OpenRouter) can opt out:
 

package/dist/buildCatalogFromOpenRouterApi.d.ts

@@ -0,0 +1,29 @@
+import type { ModelsCatalogJson } from "./types.js";
+export type OpenRouterApiModel = {
+    id: string;
+    canonical_slug?: string;
+    name?: string;
+    created?: number;
+    description?: string;
+    context_length?: number;
+    architecture?: {
+        modality?: string;
+        input_modalities?: string[];
+        output_modalities?: string[];
+    };
+    pricing?: Record<string, string | null | undefined>;
+    top_provider?: {
+        max_completion_tokens?: number;
+    };
+    supported_parameters?: string[];
+    knowledge_cutoff?: string | null;
+    expiration_date?: string | null;
+};
+export type OpenRouterApiModelsResponse = {
+    data: OpenRouterApiModel[];
+};
+/** Build the legacy OpenRouter-only catalog document (fed into {@link normalizeModelsCatalog}). */
+export declare function buildLegacyCatalogFromOpenRouterApi(response: OpenRouterApiModelsResponse): Record<string, unknown>;
+/** Fetch response → unified {@link ModelsCatalogJson}. */
+export declare function buildModelsCatalogFromOpenRouterApi(response: OpenRouterApiModelsResponse): ModelsCatalogJson;
+//# sourceMappingURL=buildCatalogFromOpenRouterApi.d.ts.map

package/dist/buildCatalogFromOpenRouterApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildCatalogFromOpenRouterApi.d.ts","sourceRoot":"","sources":["../src/buildCatalogFromOpenRouterApi.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiC,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE;QACb,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC5B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;KAC9B,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACpD,YAAY,CAAC,EAAE;QACb,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,kBAAkB,EAAE,CAAC;CAC5B,CAAC;AA8FF,mGAAmG;AACnG,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,2BAA2B,GACpC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB;AAED,0DAA0D;AAC1D,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,2BAA2B,GACpC,iBAAiB,CAoBnB"}

package/dist/buildCatalogFromOpenRouterApi.js

@@ -0,0 +1,113 @@
+import { OPENROUTER_MODELS_API_URL } from "./constants.js";
+import { MODELS_CATALOG_REMOTE_URL, normalizeModelsCatalog, } from "./modelsCatalog.js";
+function perTokenToPerMillion(tokenPrice) {
+    if (tokenPrice === null || tokenPrice === undefined || tokenPrice === "") {
+        return undefined;
+    }
+    const perToken = Number(tokenPrice);
+    if (!Number.isFinite(perToken)) {
+        return undefined;
+    }
+    return perToken * 1_000_000;
+}
+function inferFamily(modelId) {
+    const slash = modelId.indexOf("/");
+    if (slash <= 0) {
+        return undefined;
+    }
+    let prefix = modelId.slice(0, slash).toLowerCase();
+    if (prefix.startsWith("~")) {
+        prefix = prefix.slice(1);
+    }
+    return prefix || undefined;
+}
+function mapModalities(model) {
+    const input = model.architecture?.input_modalities ?? ["text"];
+    const output = model.architecture?.output_modalities ?? ["text"];
+    return {
+        input: input.map((m) => m.toLowerCase()),
+        output: output.map((m) => m.toLowerCase()),
+    };
+}
+function inferCapabilities(supported) {
+    if (!supported?.length) {
+        return undefined;
+    }
+    const caps = {};
+    if (supported.some((p) => p === "reasoning" || p === "include_reasoning")) {
+        caps.reasoning = true;
+    }
+    if (supported.some((p) => p === "tools" || p === "tool_choice")) {
+        caps.toolCalling = true;
+    }
+    if (supported.some((p) => p === "structured_outputs")) {
+        caps.structuredOutputs = true;
+    }
+    return Object.keys(caps).length > 0 ? caps : undefined;
+}
+function mapLegacyEntry(model) {
+    const pricing = model.pricing ?? {};
+    return {
+        modelId: model.id,
+        canonicalSlug: model.canonical_slug,
+        displayName: model.name,
+        family: inferFamily(model.id),
+        status: model.expiration_date ? "deprecated" : "active",
+        modalities: mapModalities(model),
+        contextWindow: model.context_length,
+        maxCompletionTokens: model.top_provider?.max_completion_tokens,
+        knowledgeCutoff: model.knowledge_cutoff ?? undefined,
+        pricing: {
+            input: perTokenToPerMillion(pricing.prompt),
+            output: perTokenToPerMillion(pricing.completion),
+            cachedInput: perTokenToPerMillion(pricing.input_cache_read),
+            cacheWrite: perTokenToPerMillion(pricing.input_cache_write),
+            imageInput: perTokenToPerMillion(pricing.image),
+            audioInput: perTokenToPerMillion(pricing.audio),
+            internalReasoning: perTokenToPerMillion(pricing.internal_reasoning),
+            webSearchPerRequest: perTokenToPerMillion(pricing.web_search),
+        },
+        capabilities: inferCapabilities(model.supported_parameters),
+    };
+}
+/** Build the legacy OpenRouter-only catalog document (fed into {@link normalizeModelsCatalog}). */
+export function buildLegacyCatalogFromOpenRouterApi(response) {
+    const models = (response.data ?? []).filter((m) => m?.id?.trim());
+    return {
+        schema: "x12i.openrouter-models.catalog",
+        version: "1.0.0",
+        generatedAt: new Date().toISOString(),
+        source: {
+            catalogUrl: OPENROUTER_MODELS_API_URL,
+            pricingUrl: "https://openrouter.ai/pricing",
+            verifiedAt: new Date().toISOString().slice(0, 10),
+            normalization: "OpenRouter API pricing fields are per-token decimal strings. Values are normalized to USD per 1M tokens.",
+        },
+        notes: [
+            "Generated from https://openrouter.ai/api/v1/models.",
+            "Upload the normalized models-catalog.json to open-assets for remote refresh.",
+        ],
+        models: models.map(mapLegacyEntry),
+    };
+}
+/** Fetch response → unified {@link ModelsCatalogJson}. */
+export function buildModelsCatalogFromOpenRouterApi(response) {
+    const legacy = buildLegacyCatalogFromOpenRouterApi(response);
+    const catalog = normalizeModelsCatalog(legacy);
+    return {
+        ...catalog,
+        sources: {
+            openrouter: {
+                catalogUrl: OPENROUTER_MODELS_API_URL,
+                pricingUrl: "https://openrouter.ai/pricing",
+                verifiedAt: new Date().toISOString().slice(0, 10),
+                normalization: "OpenRouter API pricing fields are per-token decimal strings. Values are normalized to USD per 1M tokens.",
+            },
+        },
+        notes: [
+            ...(catalog.notes ?? []),
+            `Remote asset URL: ${MODELS_CATALOG_REMOTE_URL}`,
+        ],
+    };
+}
+//# sourceMappingURL=buildCatalogFromOpenRouterApi.js.map

package/dist/buildCatalogFromOpenRouterApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildCatalogFromOpenRouterApi.js","sourceRoot":"","sources":["../src/buildCatalogFromOpenRouterApi.ts"],"names":[],"mappings":"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"}

package/dist/buildModelsRegistry.d.ts

@@ -0,0 +1,25 @@
+import type { ModelRegistryEntry, ModelsProfilesJson, ModelsRegistryJson, ModelsCatalogJson } from "./types.js";
+import { validateProfileVendorCoverage } from "./validateProfileVendorCoverage.js";
+export interface FaultyProfileChoice {
+    profile: string;
+    choice: string;
+    registryKey: string;
+    invocation: ModelRegistryEntry["invocation"];
+    candidates: string[];
+}
+export interface CatalogMissChoice {
+    profile: string;
+    choice: string;
+    registryKey: string;
+    invocation: ModelRegistryEntry["invocation"];
+    candidates: string[];
+}
+export interface ModelsRegistryBuildResult {
+    registry: ModelsRegistryJson;
+    faulty: FaultyProfileChoice[];
+    catalogMiss: CatalogMissChoice[];
+    vendorWarnings: ReturnType<typeof validateProfileVendorCoverage>;
+}
+export declare function buildModelsRegistry(profiles: ModelsProfilesJson, catalog: ModelsCatalogJson | unknown): ModelsRegistryBuildResult;
+export declare function listFaultyFromRegistry(registry: ModelsRegistryJson): FaultyProfileChoice[];
+//# sourceMappingURL=buildModelsRegistry.d.ts.map

package/dist/buildModelsRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildModelsRegistry.d.ts","sourceRoot":"","sources":["../src/buildModelsRegistry.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAC7C,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,cAAc,EAAE,UAAU,CAAC,OAAO,6BAA6B,CAAC,CAAC;CAClE;AAgBD,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,iBAAiB,GAAG,OAAO,GACnC,yBAAyB,CA6J3B;AAmBD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,kBAAkB,GAC3B,mBAAmB,EAAE,CAoBvB"}