@x12i/ai-profiles 4.1.1 → 4.2.1

package/README.md

@@ -47,7 +47,7 @@ Graph JSON, studio defaults, and run overrides store **profile slot strings only
 | `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`).
+Canonical storage form is **`profile/choice`** (separator `/`). Use **`formatProfileChoiceKey(profile, choice)`** when writing slots and **`isKnownProfileInput(input)`** (or **`isKnownProfileChoice`** / **`matchStrictProfileInput`**) before persist or execute. Always include the choice segment — even for the profile default (`cheap/default`, not bare `cheap`).
 
 ```json
 "modelConfig": {
@@ -249,10 +249,13 @@ npm install @x12i/ai-profiles
 | `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 |
+| `isKnownProfileInput(input)` | Yes (bundled only) | Profile-intent gate: known `profile/choice` → `true`; concrete model ids → `false` |
+| `isKnownProfileOrShortcut(input)` | Yes (bundled only) | Alias of `isKnownProfileInput` (shortcuts are not supported) |
 | `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 |
+| `resolveBundledInput(input, options)` | Yes | Unified sync resolver: `profile/choice` → registry; vendor slug / gateway wire / `{ provider, modelId }` → catalog |
+| `resolveInput(input, options)` | No (async) | Unified async resolver (same order as `resolveBundledInput`; `source: "auto" \| "remote" \| "bundled"`) |
 | `resolveBundledCatalogModel(input, options?)` | Yes | Sync strict catalog resolution (exact/high confidence only) |
 | `ensureConcreteModel(input, options?)` | Yes | String normalizer: `profile/choice` (strict) or concrete model (catalog best-effort) → invoke-time `{ provider, modelId }` |
 | `normalizeInvokeModel(input, options?)` | Yes | Idempotent gateway invoke tuple: strips `openrouter/` display slugs; rejects unresolved `profile/choice` aliases |
@@ -271,8 +274,10 @@ npm install @x12i/ai-profiles
 | `resolveSecondaryModel(input, options?)` | No (async) | Resolve primary choice + optional companion `secondary` from profile `secondary` refs |
 | `getSecondaryForResolvedProfile(resolved, registry, catalog?)` | Yes | Secondary for an already-resolved primary (no extra I/O when catalog is passed) |
 | `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 |
+| `resolveAIProfileByTags(tags, options?)` | No (async) | Pick best profile by weighted tags (`tagMatch`, excludes discovery by default), then resolve |
+| `listAICatalogModels(options?)` | No (async) | Filter/rank catalog models by tags, provider, status, modalities, tools/reasoning; attaches intent `profileChoices` |
+| `resolveCatalogModelByTags(tags, options?)` | No (async) | Best catalog model by weighted tags (+ optional profile branch map) |
+| `scoreProfileTags` / `rankProfilesByTags` | Yes | Weighted tag scoring for discovery and custom UIs |
 | `AIProfilesError` / `AIProfilesErrorCode` | — | Typed errors (`UNKNOWN_PROFILE`, `INVOKE_MODEL_ALIAS_AT_GATEWAY`, `INVOKE_MODEL_SHAPE_INVALID`, …) |
 
 ### Model identity (vendor + model strings)
@@ -282,7 +287,7 @@ Use these when callers pass **raw model ids or OpenRouter slugs**, not profile n
 | Export | Sync? | Purpose |
 |--------|-------|---------|
 | `resolveCatalogModel(input, options?)` | No (async) | Resolve a model SKU or OpenRouter slug via `models-catalog.json` (strict; no profile intent) |
-| `resolveModelIdentity(input, options?)` | Yes | Given a bare id or `vendor/slug`, return `{ provider, modelId, invocation? }` via bundled registry + catalog fallback |
+| `resolveModelIdentity(input, options?)` | Yes | Given a bare id or `vendor/slug`, return `{ provider, modelId, invocation? }` via bundled registry + catalog fallback. Returns `null` for known `profile/choice` keys. |
 | `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 |
@@ -327,7 +332,7 @@ For consumers that need **no network** and a single entry point:
 ```ts
 import {
   ensureConcreteModel,
-  isKnownProfileChoice,
+  isKnownProfileInput,
   isReasoningModel,
   resolveBundledInput,
   resolveBundledAIProfile,
@@ -352,8 +357,9 @@ ensureConcreteModel("google/gemini-2.5-flash-lite");
 ensureConcreteModel("openrouter/openai/gpt-5.5");
 // → { provider: "openrouter", modelId: "openai/gpt-5.5" }
 
-if (isKnownProfileChoice("cheap/default")) {
+if (isKnownProfileInput("cheap/default")) {
   const resolved = resolveBundledInput("cheap/default", { catalogLane: "text" });
+  // resolved.provider is never "cheap"
 }
 
 const wire = normalizeGatewayWireId("openrouter/openai/gpt-5.5");
@@ -376,7 +382,16 @@ const routed = applyModelRouting(
 );
 ```
 
-`isKnownProfileChoice` returns **false** for bare profiles (`cheap`), legacy shortcuts (`cheapest`), and concrete slugs (`google/gemini-2.5-flash-lite`).
+For the same profile-first order with optional remote registry/catalog (`source: "auto"` / `"remote"` / `"bundled"`), use **`resolveInput`**:
+
+```ts
+import { resolveInput } from "@x12i/ai-profiles";
+
+await resolveInput("cheap/default", { catalogLane: "text", source: "auto" });
+await resolveInput("google/gemma-3-4b-it", { source: "bundled" });
+```
+
+`isKnownProfileInput` / `isKnownProfileChoice` return **false** for bare profiles (`cheap`), legacy shortcuts (`cheapest`), and concrete slugs (`google/gemini-2.5-flash-lite`).
 
 ## Basic usage
 
@@ -384,9 +399,10 @@ const routed = applyModelRouting(
 import {
   listAIProfiles,
   listAIProfileChoices,
-  isKnownProfileChoice,
+  isKnownProfileInput,
   resolveAIProfile,
   resolveCatalogModel,
+  resolveInput,
 } from "@x12i/ai-profiles";
 
 const profiles = await listAIProfiles();
@@ -394,6 +410,7 @@ const choices = await listAIProfileChoices();
 
 // Strict lookup key: profile/choice
 const model = await resolveAIProfile("cheap/default", { catalogLane: "text" });
+// Or unified async: await resolveInput("cheap/default", { catalogLane: "text" });
 
 console.log(model.profile); // canonical primary key: cheap
 console.log(model.provider); // "openrouter" by default for remote profiles
@@ -412,8 +429,8 @@ const sku = await resolveCatalogModel("google/gemini-2.5-flash-lite", {
   preferOpenRouter: false,
 });
 
-console.log(isKnownProfileChoice("cheap/default")); // true
-console.log(isKnownProfileChoice("cheap")); // false
+console.log(isKnownProfileInput("cheap/default")); // true
+console.log(isKnownProfileInput("cheap")); // false
 ```
 
 ## Registry statistics
@@ -455,7 +472,7 @@ Resolution accepts exactly **four** input forms:
 
 **Not supported:** shortcuts (`cheapest`), bare profiles (`cheap`), aliases (`cost-sensitive`). Use discovery to pick a profile, then resolve an explicit `profile/choice`.
 
-**Tags exist to filter.** Short codes on profiles (`cyb`, `eco`, `cod`, `oai`, …). Get the tag list, then filter profiles with those tags:
+**Tags exist to filter.** Short codes on profiles and catalog models (`cyb`, `eco`, `cod`, `oai`, …). Get the tag list, then filter:
 
 ```ts
 import {
@@ -463,6 +480,8 @@ import {
   listUsedAIProfileTags,   // tags present in the loaded registry
   listAIProfiles,          // filter profiles by tags
   resolveAIProfileByTags,  // pick best matching profile → resolve it
+  listAICatalogModels,     // filter catalog models by tags
+  resolveCatalogModelByTags, // pick best matching model (+ optional profile branch)
 } from "@x12i/ai-profiles";
 
 listAIProfileTags();                              // glossary for pickers
@@ -474,9 +493,21 @@ await listAIProfiles({ tags: ["cyb", "sec"], tagMatch: "all" });  // all of
 
 // Filter + resolve in one step
 await resolveAIProfileByTags(["cyb", "eco", "ds"], { catalogLane: "text" });
+
+// Catalog models (tags are derived + inherited during registry:finish)
+await listAICatalogModels({
+  tags: ["cod", "eco"],
+  tagMatch: "all",
+  provider: "google",
+  status: "active",
+  supportsTools: true,
+});
+await resolveCatalogModelByTags(["cod", "eco"], { catalogLane: "text" });
 ```
 
-`tagMatch: "any"` (default) = match if any requested tag is present. `"all"` = every requested tag must be present. Results are ranked by how many requested tags match.
+`tagMatch: "any"` (default) = match if any requested tag is present. `"all"` = every requested tag must be present. Results are ranked by **weighted** tag score (domain/task 3, capability 2, tier/vendor 1, `wf` 0.25), then coverage ratio, then fewer tags.
+
+**Discovery exclusion:** by default, tag list/resolve pools skip `vendorFamily` and `category: "discovery"` profiles (`catalog`, `claude`, `grok`, …). Pass `includeDiscovery: true`, or include the `vnd` tag, to include them.
 
 Input is normalized (trimmed, lowercased) before matching. Composite keys accept **`/` or `\`** as the separator (`cyber\default` → `cyber/default`). **Profile and choice segment names treat `-` and `_` as equivalent** (`cheap/google-floor` → `cheap/google_floor`).
 
@@ -563,12 +594,12 @@ resolveAndNormalizeBundledInvokeModel("cyber/deep_forensics", {
 
 ## Sync validation (bundled registry)
 
-Use **`isKnownProfileChoice(input)`** before run/execute or on first paint when the remote registry may not be loaded yet. It reads the **bundled** JSON only (no network, no in-memory cache race).
+Use **`isKnownProfileInput(input)`** (or **`isKnownProfileChoice`**) before run/execute or on first paint when the remote registry may not be loaded yet. It reads the **bundled** JSON only (no network, no in-memory cache race).
 
 ```ts
 const canRun =
-  isKnownProfileChoice(aiProfileKey) &&
-  isKnownProfileChoice(fallbackKey);
+  isKnownProfileInput(aiProfileKey) &&
+  isKnownProfileInput(fallbackKey);
 ```
 
 Accepts **valid `profile/choice` keys only**. Unknown strings return `false`.
@@ -1014,7 +1045,7 @@ Workflow YAML is in [`docs/github-workflows/`](docs/github-workflows/). Copy int
 Consumers install with:
 
 ```bash
-npm install @x12i/ai-profiles@^4.1.0
+npm install @x12i/ai-profiles@^4.2.0
 ```
 
 Peer dependency for downstream repos (graphs-studio, graph-engine, ai-tasks):