@x12i/ai-profiles 4.1.0 → 4.2.0

package/README.md

@@ -271,8 +271,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; 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)
@@ -455,7 +457,36 @@ 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** are short (2–4 chars), many per profile (`cyb`, `eco`, `ds`, …). Use `listAIProfiles({ tags })` or `resolveAIProfileByTags(['cyb', 'eco'])` for discovery — partial overlap is OK; the profile with the most matching tags wins, then an explicit choice is resolved.
+**Tags exist to filter.** Short codes on profiles and catalog models (`cyb`, `eco`, `cod`, `oai`, …). Get the tag list, then filter:
+
+```ts
+import {
+  listAIProfileTags,       // all allowed tags (+ labels)
+  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
+await listUsedAIProfileTags({ source: "bundled" }); // what's actually used
+
+// Filter: keep profiles that have these tags
+await listAIProfiles({ tags: ["cyb", "eco"], tagMatch: "any" });  // any of
+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" });
+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 **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`).
 
@@ -993,7 +1024,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):