@x12i/ai-profiles 3.1.0 → 3.2.0

package/README.md

@@ -2,7 +2,9 @@
 
 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.
 
-> **v3.0** removes legacy resolution inputs: shortcuts, bare profiles, and aliases. Only four forms are accepted — `profile/choice`, vendor slug, gateway wire, and `{ provider, modelId }`. See [CHANGELOG.md](CHANGELOG.md).
+> **v3.2** adds **`normalizeInvokeModel`**, **`resolveAndNormalizeInvokeModel`**, and **`resolveAndNormalizeBundledInvokeModel`** for gateway invoke wire shape. Downstream repos should pin **`"@x12i/ai-profiles": "^3.2.0"`**.
+>
+> **v3.0** removes legacy resolution inputs: shortcuts, bare profiles, and aliases. Only four resolution forms are accepted — `profile/choice`, vendor slug, gateway wire, and `{ provider, modelId }`. See [CHANGELOG.md](CHANGELOG.md).
 >
 > **v2.0** (still relevant): every `resolveAIProfile` call must pass `catalogLane` (`"text"`, `"image"`, …). Profile keys `deepseek` and `summarization` are gone — use `vol` and `sum`.
 
@@ -35,6 +37,36 @@ Every profile has a **`defaultChoice`** (recommended) and typically **two altern
 
 Tasks should declare **requirements** as explicit `profile/choice` keys (e.g. `cheap/default`), not model names. Use discovery APIs (`listAIProfiles`, `resolveAIProfileByTags`) to pick a profile when the caller does not already have a composite key.
 
+### Graph and stored model config
+
+Graph JSON, studio defaults, and run overrides store **profile slot strings only** — never concrete provider model ids. Each task uses a complete triple:
+
+| Slot | Example | Phase |
+|------|---------|-------|
+| `preActionModel` | `deep/default` | PRE (xynthesis / planning) |
+| `skillModel` | `balanced/default` | MAIN (skill gateway) |
+| `postActionModel` | `cheap/default` | POST (xynthesis / wrap-up) |
+
+Canonical storage form is **`profile/choice`** (separator `/`). Use **`formatProfileChoiceKey(profile, choice)`** when writing slots and **`isKnownProfileChoice(input)`** (or **`matchStrictProfileInput`**) before persist or execute. Always include the choice segment — even for the profile default (`cheap/default`, not bare `cheap`).
+
+```json
+"modelConfig": {
+  "cases": [
+    {
+      "modelConfig": {
+        "preActionModel": "cyber/default",
+        "skillModel": "audit/default",
+        "postActionModel": "cheap/default"
+      }
+    }
+  ]
+}
+```
+
+**At execute time**, hosts pass the stored alias triple unchanged; each phase resolves independently via `resolveAIProfile` (or `resolveAndNormalizeInvokeModel` at the gateway boundary). Do **not** pre-resolve aliases to concrete ids in graph JSON, `runtime.modelConfig`, or `aliasConfig`.
+
+**Forbidden in stored config:** legacy keys (`xynthesisModel`, `postStrategyModel`), legacy aliases (`default`, `strong`, `weak`), bare profile keys (`cheap`), concrete slugs (`openai/gpt-4o-mini`), and legacy `@` composites (`cheap@anthropic_cheap` — migrate to `cheap/anthropic_cheap` on save).
+
 ### 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).
@@ -213,7 +245,11 @@ npm install @x12i/ai-profiles
 | `loadBundledModelsCatalog()` | Yes | Package-shipped `models-catalog.json` only |
 | `loadBundledModelsRegistry()` | Yes | Package-shipped `models-registry.json` (linkage index) |
 | `listAIProfileChoices(options?)` | No (async) | List explicit `profile/choice` keys for strict pickers and stored config |
+| `formatProfileChoiceKey(profile, choice)` | Yes | Build canonical slot key (`cheap/default`) |
+| `parseProfileChoiceKey(input)` | Yes | Parse `profile/choice` (accepts `\` as separator on input) |
+| `matchStrictProfileInput(registry, input)` | Yes | Resolve input to profile+choice or `invalidChoice` |
 | `isKnownProfileChoice(input)` | Yes (bundled only) | Whether input is a known valid `profile/choice` key |
+| `isKnownProfileChoiceInput(registry, input)` | Yes | Same as above with an explicit registry |
 | `getBundledRegistry()` | Yes | Sync bundled profiles registry (no network) |
 | `resolveBundledAIProfile(input, options)` | Yes | Strict `profile/choice` → model, pricing, runtime (`source: "bundled"`) |
 | `resolveBundledInput(input, options)` | Yes | Unified resolver: `profile/choice` → registry; vendor slug / gateway wire / `{ provider, modelId }` → catalog |
@@ -230,7 +266,7 @@ npm install @x12i/ai-profiles
 | `listProfileSecondaries(profileKey, registry)` | Yes | List per-choice `secondary` declarations on a profile |
 | `resolveAIProfileByTags(tags, options?)` | No (async) | Pick best profile by tag overlap (partial match OK), then resolve |
 | `scoreProfileTags` / `rankProfilesByTags` | Yes | Tag overlap scoring for discovery and custom UIs |
-| `AIProfilesError` | — | Typed errors (`UNKNOWN_PROFILE`, …) |
+| `AIProfilesError` / `AIProfilesErrorCode` | — | Typed errors (`UNKNOWN_PROFILE`, `INVOKE_MODEL_ALIAS_AT_GATEWAY`, `INVOKE_MODEL_SHAPE_INVALID`, …) |
 
 ### Model identity (vendor + model strings)
 
@@ -437,40 +473,65 @@ ensureConcreteModel("google/gemini-2.5-flash-lite");
 
 ## Invoke wire shape (gateway / HTTP)
 
-Downstream packages (`ai-tasks`, `ai-skills`, `ai-gateway`, `xynthesis`, `optimixer`) must agree on what is sent on the wire **after** semantic resolution:
+Downstream packages (`ai-tasks`, `ai-skills`, `ai-gateway`, `xynthesis`, `optimixer`) must agree on what is sent on the wire **after** semantic resolution. **Stored graph config** uses `profile/choice` aliases; **gateway / HTTP** uses the invoke tuple below.
+
+### Display slug
+
+A **display slug** is a single string with an `openrouter/` prefix for human-readable UI and logs, e.g. `openrouter/deepseek/deepseek-v4-pro`. Studio pickers, plan previews, and Activix run logs may show this form. It is **not** the shape passed to `ai-gateway` catalog lookup or OpenRouter HTTP — normalize before those boundaries.
 
-| Shape | Example | Use |
-|-------|---------|-----|
-| **Display slug** | `openrouter/deepseek/deepseek-v4-pro` | Studio UI, plan logs, human preview only |
-| **Invoke tuple** | `{ provider: "openrouter", model: "deepseek/deepseek-v4-pro" }` | `ai-gateway` catalog lookup, OpenRouter HTTP, funcx PRE/POST |
+### Invoke tuple
 
-Call **`normalizeInvokeModel`** at every boundary before catalog lookup or HTTP (idempotent). Profile intent still goes through **`resolveAIProfile`** first (or **`resolveAndNormalizeInvokeModel`** for the combined path).
+An **invoke tuple** is `{ provider, model, routing }` where `provider` is `"openrouter"` (or a vendor for direct routing) and `model` is the **bare** vendor/model slug without a gateway prefix, e.g. `{ provider: "openrouter", model: "deepseek/deepseek-v4-pro", routing: "openrouter" }`. This is what `ai-gateway` uses for catalog lookup and what OpenRouter HTTP expects.
+
+Call **`normalizeInvokeModel`** at every gateway boundary (idempotent). Profile intent still goes through **`resolveAIProfile`** first, or use **`resolveAndNormalizeInvokeModel`** / **`resolveAndNormalizeBundledInvokeModel`** for the combined path.
+
+| Export | Sync? | Purpose |
+|--------|-------|---------|
+| `normalizeInvokeModel(input, options?)` | Yes | Display slug or invoke object → canonical invoke tuple; rejects unresolved `profile/choice` |
+| `resolveAndNormalizeInvokeModel(alias, options)` | No (async) | `resolveAIProfile` → `normalizeInvokeModel` |
+| `resolveAndNormalizeBundledInvokeModel(alias, options)` | Yes | Bundled `resolveAIProfile` → `normalizeInvokeModel` (no network) |
 
 ```ts
 import {
   normalizeInvokeModel,
   resolveAndNormalizeInvokeModel,
+  resolveAndNormalizeBundledInvokeModel,
 } from "@x12i/ai-profiles";
 
-// Display slug → invoke tuple (MAIN handoff fix)
+// Display slug → invoke tuple (string or { model } object)
 normalizeInvokeModel("openrouter/deepseek/deepseek-v4-pro");
+normalizeInvokeModel({ model: "openrouter/deepseek/deepseek-v4-pro" });
 // → { provider: "openrouter", model: "deepseek/deepseek-v4-pro", routing: "openrouter", displaySlug: "..." }
 
-// Already-correct tuple → unchanged
+// Already-correct tuple → unchanged (idempotent)
 normalizeInvokeModel({ provider: "openrouter", model: "deepseek/deepseek-v4-pro" });
 
-// Alias at gateway without resolution → INVOKE_MODEL_ALIAS_AT_GATEWAY
-normalizeInvokeModel("cyber/deep_forensics"); // throws
+// Unresolved profile/choice at gateway → INVOKE_MODEL_ALIAS_AT_GATEWAY
+normalizeInvokeModel("cheap/default");
+normalizeInvokeModel({ model: "cheap/default" }); // same error
 
-// Profile/choice → resolve, then normalize
+// Profile/choice → resolve, then normalize (gateway catalog-lookup tuple)
 await resolveAndNormalizeInvokeModel("cyber/deep_forensics", {
   catalogLane: "text",
   useOpenRouter: true,
 });
-// → { provider: "openrouter", model: "deepseek/deepseek-v4-pro", ... }
+// → { provider: "openrouter", model: "deepseek/deepseek-v4-pro", routing: "openrouter", ... }
+
+// Sync bundled variant (tests, predict paths)
+resolveAndNormalizeBundledInvokeModel("cyber/deep_forensics", {
+  catalogLane: "text",
+  useOpenRouter: true,
+});
 ```
 
-Errors: `INVOKE_MODEL_ALIAS_AT_GATEWAY` (unresolved `profile/choice`), `INVOKE_MODEL_SHAPE_INVALID` (unparseable composite or missing provider).
+**Error codes** (on `AIProfilesError.code`):
+
+| Code | When |
+|------|------|
+| `INVOKE_MODEL_ALIAS_AT_GATEWAY` | `profile/choice` reached `normalizeInvokeModel` without prior `resolveAIProfile` |
+| `INVOKE_MODEL_SHAPE_INVALID` | Empty model, missing provider, or unparseable composite after normalization |
+
+`allowAlias: true` exists for rare internal paths; **gateway and HTTP callers should not use it** — resolve aliases first.
 
 ## Sync validation (bundled registry)
 
@@ -531,14 +592,18 @@ This applies to any `profile/choice` input that resolves to a remote profile cho
 
 ### Avoid hardcoded OpenRouter slugs (especially dated previews)
 
-Do **not** copy OpenRouter slugs into app config (`preActionModel`, env vars, etc.) and do **not** use `canonicalSlug` from the catalog for API calls. OpenRouter retires dated preview ids (e.g. `google/gemini-2.5-flash-lite-preview-06-17`) while stable ids remain (`google/gemini-2.5-flash-lite`).
+Do **not** copy OpenRouter slugs into graph JSON or app config (`preActionModel`, `skillModel`, `postActionModel`, env vars, etc.) and do **not** use `canonicalSlug` from the catalog for API calls. OpenRouter retires dated preview ids (e.g. `google/gemini-2.5-flash-lite-preview-06-17`) while stable ids remain (`google/gemini-2.5-flash-lite`).
 
 ```ts
-// Good — profile pointer + resolver
+// Good — store profile/choice; resolve at execute time
+preActionModel: "cheap/default";
+skillModel: "balanced/default";
+postActionModel: "cheap/default";
+
 const pre = await resolveAIProfile("cheap/default", { catalogLane: "text" });
-preActionModel: pre.modelId; // "google/gemini-2.5-flash-lite"
+// pre.modelId → "google/gemini-2.5-flash-lite" (concrete id only after resolution)
 
-// Bad — stale transport slug from an old catalog page or doc
+// Bad — concrete slug in stored config (stale when catalog moves)
 preActionModel: "google/gemini-2.5-flash-lite-preview-06-17";
 ```
 
@@ -649,29 +714,26 @@ The `version` field in the JSON files (and `registryVersion` on resolved output)
 ## Integration example
 
 ```ts
-const resolved = await resolveAIProfile(
-  node.taskConfiguration.aiProfile ?? "balanced/default",
-  { catalogLane: "text" },
-);
+import { resolveAIProfile, resolveAndNormalizeInvokeModel } from "@x12i/ai-profiles";
 
-const modelConfig = {
-  provider: resolved.provider,
-  model: resolved.modelId,
-  routing: resolved.routing,
-  instructionTier: resolved.instructionTier,
-  backend: resolved.backend,
-  temperature: resolved.runtime.temperature,
-  outputMode: resolved.runtime.outputMode,
-  toolPolicy: resolved.runtime.toolPolicy,
-  reasoningEffort: resolved.runtime.reasoningEffort,
+// Graph JSON stores aliases only (merged job defaults + node overrides per task)
+const slots = {
+  preActionModel: node.taskConfiguration.modelConfig?.preActionModel ?? "deep/default",
+  skillModel: node.taskConfiguration.modelConfig?.skillModel ?? "balanced/default",
+  postActionModel: node.taskConfiguration.modelConfig?.postActionModel ?? "cheap/default",
 };
 
-// Default OpenRouter routing:
-// provider: "openrouter", model: "openai/gpt-5.4", routing: "openrouter"
+// Resolve each phase independently at execute time
+const pre = await resolveAIProfile(slots.preActionModel, { catalogLane: "text" });
+const main = await resolveAIProfile(slots.skillModel, { catalogLane: "text" });
+const post = await resolveAIProfile(slots.postActionModel, { catalogLane: "text" });
 
-// Vendor-direct:
-// await resolveAIProfile(..., { useOpenRouter: false })
-// provider: "openai", model: "gpt-5.4", routing: "direct"
+// Gateway handoff: resolve + normalize invoke tuple
+const mainInvoke = await resolveAndNormalizeInvokeModel(slots.skillModel, {
+  catalogLane: "text",
+  useOpenRouter: true,
+});
+// mainInvoke → { provider: "openrouter", model: "openai/gpt-5.4", routing: "openrouter", ... }
 ```
 
 ## Profile matrix (FuncX contract)
@@ -690,7 +752,7 @@ Default choice per profile (vendor-native ids in registry; OpenRouter slugs when
 | `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` |
+| `sum` | Remote | **`default`** | `default` | `claude-haiku-4.5` |
 | `vision` | Remote | **`default`** | `default` | `gpt-5.4` |
 | `local` | CPU (no OpenRouter) | **`cpu`** | `llama_cpp_gguf` | `funcx:llama-cpp:gguf` |
 | `local` | CPU | **`cpu`** | `transformersjs_default` | `Xenova/distilbart-cnn-6-6` |
@@ -858,7 +920,13 @@ Workflow YAML is in [`docs/github-workflows/`](docs/github-workflows/). Copy int
 Consumers install with:
 
 ```bash
-npm install @x12i/ai-profiles
+npm install @x12i/ai-profiles@^3.2.0
+```
+
+Peer dependency for downstream repos (graphs-studio, graph-engine, ai-tasks):
+
+```json
+"@x12i/ai-profiles": "^3.2.0"
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-profiles",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Resolve AI profile names into concrete model choices with bundled defaults and remote JSON refresh",
   "type": "module",
   "main": "./dist/index.js",