@x12i/ai-profiles 2.0.1 → 2.1.1

package/dist/profileChoiceKey.js

@@ -0,0 +1,96 @@
+import { normalizeKey, normalizeSegmentKey, resolveSegmentKey, } from "./normalizeKey.js";
+/** Separator for the canonical profile+choice lookup key (`cheap/default`). */
+export const PROFILE_CHOICE_KEY_SEP = "/";
+/** Normalize composite input: trim/lowercase and treat `\` like `/`. */
+function normalizeProfileChoiceInput(input) {
+    return normalizeKey(input).replace(/\\/g, PROFILE_CHOICE_KEY_SEP);
+}
+export function formatProfileChoiceKey(profile, choice) {
+    return `${profile}${PROFILE_CHOICE_KEY_SEP}${choice}`;
+}
+/**
+ * Parse `profile/choice` (also accepts `profile\choice` on input).
+ * Rejects empty segments and keys with more than one separator.
+ * Segment names accept `-` or `_` interchangeably at lookup time.
+ */
+export function parseProfileChoiceKey(input) {
+    const normalized = normalizeProfileChoiceInput(input);
+    if (!normalized.includes(PROFILE_CHOICE_KEY_SEP)) {
+        return undefined;
+    }
+    const slash = normalized.indexOf(PROFILE_CHOICE_KEY_SEP);
+    const profile = normalized.slice(0, slash);
+    const choice = normalized.slice(slash + 1);
+    if (!profile || !choice || choice.includes(PROFILE_CHOICE_KEY_SEP)) {
+        return undefined;
+    }
+    return { profile, choice };
+}
+export function isProfileChoiceKeyFormat(input) {
+    return parseProfileChoiceKey(input) !== undefined;
+}
+function resolveProfileChoiceSegments(registry, profileSegment, choiceSegment) {
+    const profileKey = resolveSegmentKey(Object.keys(registry.profiles), profileSegment);
+    if (!profileKey) {
+        return undefined;
+    }
+    const profile = registry.profiles[profileKey];
+    const choiceKey = resolveSegmentKey(Object.keys(profile.choices), choiceSegment);
+    if (!choiceKey) {
+        return {
+            kind: "invalidChoice",
+            profile: profileKey,
+            choice: normalizeSegmentKey(choiceSegment),
+        };
+    }
+    return {
+        kind: "profileChoice",
+        profile: profileKey,
+        choice: choiceKey,
+    };
+}
+/**
+ * Resolve input to an explicit profile+choice pair.
+ * Accepts `profile/choice` or `profile\choice` composite keys, or shortcuts that pin both fields.
+ */
+export function matchStrictProfileInput(registry, input) {
+    const key = normalizeKey(input);
+    if (!key) {
+        return undefined;
+    }
+    const composite = parseProfileChoiceKey(key);
+    if (composite) {
+        return resolveProfileChoiceSegments(registry, composite.profile, composite.choice);
+    }
+    const shortcutKey = resolveSegmentKey(Object.keys(registry.shortcuts), key);
+    if (shortcutKey) {
+        const shortcut = registry.shortcuts[shortcutKey];
+        if (!shortcut.choice) {
+            return undefined;
+        }
+        const resolved = resolveProfileChoiceSegments(registry, shortcut.profile, shortcut.choice);
+        if (!resolved || resolved.kind === "invalidChoice") {
+            return undefined;
+        }
+        return {
+            kind: "shortcut",
+            shortcutKey,
+            profile: resolved.profile,
+            choice: resolved.choice,
+        };
+    }
+    return undefined;
+}
+export function listRegistryProfileChoiceKeys(registry) {
+    const out = [];
+    for (const [profileKey, profile] of Object.entries(registry.profiles)) {
+        for (const choiceKey of Object.keys(profile.choices)) {
+            out.push({ profile: profileKey, choice: choiceKey });
+        }
+    }
+    return out;
+}
+export function isKnownProfileChoiceInput(registry, input) {
+    return matchStrictProfileInput(registry, input) !== undefined;
+}
+//# sourceMappingURL=profileChoiceKey.js.map

package/dist/profileChoiceKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileChoiceKey.js","sourceRoot":"","sources":["../src/profileChoiceKey.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAG3B,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAY,CAAC;AAEnD,wEAAwE;AACxE,SAAS,2BAA2B,CAAC,KAAa;IAChD,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,sBAAsB,CAAC,CAAC;AACpE,CAAC;AAOD,MAAM,UAAU,sBAAsB,CAAC,OAAe,EAAE,MAAc;IACpE,OAAO,GAAG,OAAO,GAAG,sBAAsB,GAAG,MAAM,EAAE,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,MAAM,UAAU,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;IACtD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC;QACjD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAE3C,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC;QACnE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAa;IACpD,OAAO,qBAAqB,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;AACpD,CAAC;AAYD,SAAS,4BAA4B,CACnC,QAA8C,EAC9C,cAAsB,EACtB,aAAqB;IAErB,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,CAAC;IACrF,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAE,CAAC;IAC/C,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC;IACjF,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO;YACL,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,UAAU;YACnB,MAAM,EAAE,mBAAmB,CAAC,aAAa,CAAC;SAC3C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,SAAS;KAClB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAA4D,EAC5D,KAAa;IAEb,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,SAAS,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IAC7C,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,4BAA4B,CACjC,QAAQ,EACR,SAAS,CAAC,OAAO,EACjB,SAAS,CAAC,MAAM,CACjB,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5E,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,WAAW,CAAE,CAAC;QAClD,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACrB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,QAAQ,GAAG,4BAA4B,CAC3C,QAAQ,EACR,QAAQ,CAAC,OAAO,EAChB,QAAQ,CAAC,MAAM,CAChB,CAAC;QACF,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;YACnD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,WAAW;YACX,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;SACxB,CAAC;IACJ,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,6BAA6B,CAC3C,QAA8C;IAE9C,MAAM,GAAG,GAAuB,EAAE,CAAC;IACnC,KAAK,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtE,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,QAA4D,EAC5D,KAAa;IAEb,OAAO,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAK,SAAS,CAAC;AAChE,CAAC"}

package/dist/profileDiscoveryMatch.d.ts

@@ -0,0 +1,15 @@
+import type { AIProfilesRegistry } from "./types.js";
+/**
+ * Loose profile-level match for discovery APIs only (tags, search, cost scouting).
+ * Never used by {@link resolveAIProfile}.
+ */
+export type DiscoveryProfileMatch = {
+    kind: "profile";
+    profileKey: string;
+} | {
+    kind: "alias";
+    profileKey: string;
+    alias: string;
+};
+export declare function matchDiscoveryProfileInput(registry: Pick<AIProfilesRegistry, "profiles">, input: string): DiscoveryProfileMatch | undefined;
+//# sourceMappingURL=profileDiscoveryMatch.d.ts.map

package/dist/profileDiscoveryMatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileDiscoveryMatch.d.ts","sourceRoot":"","sources":["../src/profileDiscoveryMatch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,CAAC,EAC9C,KAAK,EAAE,MAAM,GACZ,qBAAqB,GAAG,SAAS,CAsBnC"}

package/dist/profileDiscoveryMatch.js

@@ -0,0 +1,18 @@
+import { normalizeKey, normalizeSegmentKey, resolveSegmentKey } from "./normalizeKey.js";
+export function matchDiscoveryProfileInput(registry, input) {
+    const key = normalizeKey(input);
+    if (!key) {
+        return undefined;
+    }
+    const profileKey = resolveSegmentKey(Object.keys(registry.profiles), key);
+    if (profileKey) {
+        return { kind: "profile", profileKey };
+    }
+    for (const [profileKey, profile] of Object.entries(registry.profiles)) {
+        if (profile.aliases?.some((alias) => normalizeSegmentKey(alias) === normalizeSegmentKey(key))) {
+            return { kind: "alias", profileKey, alias: key };
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=profileDiscoveryMatch.js.map

package/dist/profileDiscoveryMatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileDiscoveryMatch.js","sourceRoot":"","sources":["../src/profileDiscoveryMatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAWzF,MAAM,UAAU,0BAA0B,CACxC,QAA8C,EAC9C,KAAa;IAEb,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,CAAC;IAC1E,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;IACzC,CAAC;IAED,KAAK,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtE,IACE,OAAO,CAAC,OAAO,EAAE,IAAI,CACnB,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC,KAAK,mBAAmB,CAAC,GAAG,CAAC,CACnE,EACD,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QACnD,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/resolveAIProfile.d.ts

@@ -1,11 +1,10 @@
 import type { ResolveAIProfileOptions, ResolvedAIProfile } from "./types.js";
 /**
- * Resolve a profile primary key, alias, or shortcut to a concrete model and runtime config.
+ * Resolve an explicit `profile/choice` key (or a shortcut that pins both) to a concrete model.
  *
- * `input` names **intent** (e.g. `balanced`, `cheapest`, `cost-sensitive`), not a vendor model id.
- * Use `options.choice` to pick an alternative within the profile (e.g. `cheap` + `anthropic_cheap`).
- *
- * @see README.md — “Why AI profiles”
+ * For discovery (tags, search, profile-level intent), use {@link listAIProfiles},
+ * {@link resolveAIProfileByTags}, or {@link resolveAIProfileWithCostAlternatives}.
+ * For raw model SKUs, use {@link resolveCatalogModel}.
  */
 export declare function resolveAIProfile(input: string, options: ResolveAIProfileOptions): Promise<ResolvedAIProfile>;
 //# sourceMappingURL=resolveAIProfile.d.ts.map

package/dist/resolveAIProfile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveAIProfile.d.ts","sourceRoot":"","sources":["../src/resolveAIProfile.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE7E;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CA8O5B"}
+{"version":3,"file":"resolveAIProfile.d.ts","sourceRoot":"","sources":["../src/resolveAIProfile.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE7E;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAoM5B"}

package/dist/resolveAIProfile.js

@@ -2,20 +2,18 @@ import { buildResolvedProfile } from "./buildResolvedProfile.js";
 import { AIProfilesError } from "./errors.js";
 import { loadAIProfilesRegistryWithWarnings } from "./loader/loadAIProfilesRegistry.js";
 import { loadModelsCatalogWithWarnings } from "./loader/loadModelsCatalog.js";
-import { matchProfileInput } from "./profileInputMatch.js";
-import { buildResolvedModelInput, modelInputLogMeta, resolveModelFromInput, } from "./modelInputFallback.js";
+import { formatProfileChoiceKey, matchStrictProfileInput, } from "./profileChoiceKey.js";
 import { pickProfileChoiceWithConstraints } from "./modalityPolicy.js";
 import { normalizeCostCap } from "./costPolicy.js";
-import { logxer } from "./logger.js";
+import { resolveCostTierCap } from "./costTiers.js";
 import { assertOpenRouterCatalogCoverage, assertProfileCatalogLane, } from "./profileCatalogLane.js";
 import { attachSecondaryToResolved } from "./resolveSecondaryModel.js";
 /**
- * Resolve a profile primary key, alias, or shortcut to a concrete model and runtime config.
+ * Resolve an explicit `profile/choice` key (or a shortcut that pins both) to a concrete model.
  *
- * `input` names **intent** (e.g. `balanced`, `cheapest`, `cost-sensitive`), not a vendor model id.
- * Use `options.choice` to pick an alternative within the profile (e.g. `cheap` + `anthropic_cheap`).
- *
- * @see README.md — “Why AI profiles”
+ * For discovery (tags, search, profile-level intent), use {@link listAIProfiles},
+ * {@link resolveAIProfileByTags}, or {@link resolveAIProfileWithCostAlternatives}.
+ * For raw model SKUs, use {@link resolveCatalogModel}.
  */
 export async function resolveAIProfile(input, options) {
     if (!options.catalogLane) {
@@ -32,70 +30,39 @@ export async function resolveAIProfile(input, options) {
         }),
     ]);
     const loaderWarnings = [...warnings, ...catalogResult.warnings];
-    const match = matchProfileInput(registry, input);
-    const modelFallback = match
-        ? undefined
-        : resolveModelFromInput(input, catalogResult.catalog);
+    const match = matchStrictProfileInput(registry, input);
     if (!match) {
-        if (modelFallback) {
-            const meta = modelInputLogMeta(input, modelFallback);
-            if (modelFallback.confidence === "low") {
-                logxer.warn("Best-effort AI model fallback for model-like input", meta);
-            }
-            else {
-                logxer.info("Resolved model-like input to catalog model", meta);
-            }
-            return buildResolvedModelInput({
-                input,
-                match: modelFallback,
-                registry,
-                loaderWarnings,
-                useOpenRouter: options.useOpenRouter,
-            });
-        }
-        throw new AIProfilesError("UNKNOWN_PROFILE", `Unknown AI profile, shortcut, or alias: ${input}`, { input });
+        throw new AIProfilesError("UNKNOWN_PROFILE_CHOICE", `Unknown profile/choice key: ${input}. Use "profile/choice" (e.g. "cheap/default") or a shortcut that pins both.`, { input });
     }
-    let profileKey;
-    let requestedChoiceKey;
-    let matchedShortcut;
-    switch (match.kind) {
-        case "profile":
-            profileKey = match.profileKey;
-            requestedChoiceKey = options.choice;
-            matchedShortcut = undefined;
-            break;
-        case "shortcut":
-            profileKey = match.profileKey;
-            requestedChoiceKey = options.choice ?? match.shortcut.choice;
-            matchedShortcut = match.shortcut;
-            break;
-        case "alias":
-            profileKey = match.profileKey;
-            requestedChoiceKey = options.choice;
-            matchedShortcut = undefined;
-            break;
+    if (match.kind === "invalidChoice") {
+        throw new AIProfilesError("UNKNOWN_CHOICE", `Unknown choice '${match.choice}' for AI profile '${match.profile}'`, { input, profile: match.profile, choice: match.choice });
     }
+    const profileKey = match.profile;
+    const requestedChoiceKey = match.choice;
+    const matchedShortcut = match.kind === "shortcut"
+        ? registry.shortcuts[match.shortcutKey]
+        : undefined;
     const profile = registry.profiles[profileKey];
     if (!profile) {
         throw new AIProfilesError("UNKNOWN_PROFILE", `Unknown AI profile: ${profileKey}`, { input, profile: profileKey });
     }
-    if (options.catalogLane) {
-        try {
-            assertProfileCatalogLane({
-                profileKey,
-                profile,
-                requestedLane: options.catalogLane,
-            });
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            throw new AIProfilesError("CATALOG_LANE_MISMATCH", message, {
-                input,
-                profile: profileKey,
-                catalogLane: options.catalogLane,
-            });
-        }
+    try {
+        assertProfileCatalogLane({
+            profileKey,
+            profile,
+            requestedLane: options.catalogLane,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new AIProfilesError("CATALOG_LANE_MISMATCH", message, {
+            input,
+            profile: profileKey,
+            catalogLane: options.catalogLane,
+        });
     }
+    const costCapPer1M = options.costCapPer1M ??
+        resolveCostTierCap(options.costTier, options.costTiers);
     let finalChoiceKey;
     let choice;
     try {
@@ -103,11 +70,12 @@ export async function resolveAIProfile(input, options) {
             choiceKey: requestedChoiceKey,
             allowedProviders: options.allowedProviders,
             preferLeadingVendors: options.preferLeadingVendors ?? true,
-            explicitChoiceRequested: options.choice !== undefined ||
-                (match.kind === "shortcut" && match.shortcut.choice !== undefined),
+            explicitChoiceRequested: true,
             inputModalities: options.inputModalities,
             outputModalities: options.outputModalities,
-            costCapPer1M: options.costCapPer1M,
+            costCapPer1M,
+            capabilityFilter: options.capabilityFilter,
+            focus: options.focus,
             catalog: catalogResult.catalog,
         });
         finalChoiceKey = picked.choiceKey;
@@ -119,10 +87,8 @@ export async function resolveAIProfile(input, options) {
             throw new AIProfilesError("NO_ALLOWED_VENDOR", message, {
                 input,
                 profile: profileKey,
+                choice: requestedChoiceKey,
                 allowedProviders: options.allowedProviders,
-                availableProviders: [
-                    ...new Set(Object.values(profile.choices).map((c) => c.provider)),
-                ],
             });
         }
         if (message.includes("required modalities")) {
@@ -139,22 +105,26 @@ export async function resolveAIProfile(input, options) {
                 input,
                 profile: profileKey,
                 choice: requestedChoiceKey,
-                costCapPer1M: options.costCapPer1M,
+                costCapPer1M,
             });
         }
         if (message.startsWith("Unknown choice")) {
-            if (options.allowFallbackToDefaultChoice) {
-                return resolveAIProfile(profileKey, {
-                    ...options,
-                    choice: profile.defaultChoice,
-                });
-            }
-            throw new AIProfilesError("UNKNOWN_CHOICE", message, { input, profile: profileKey, choice: requestedChoiceKey });
+            throw new AIProfilesError("UNKNOWN_CHOICE", message, {
+                input,
+                profile: profileKey,
+                choice: requestedChoiceKey,
+            });
         }
         throw error;
     }
-    if (!profile.choices[finalChoiceKey]) {
-        throw new AIProfilesError("UNKNOWN_CHOICE", `Unknown choice '${finalChoiceKey}' for AI profile '${profileKey}'`, { input, profile: profileKey, choice: finalChoiceKey });
+    if (finalChoiceKey !== requestedChoiceKey) {
+        throw new AIProfilesError("CHOICE_SUBSTITUTED", `Explicit choice '${requestedChoiceKey}' was replaced with '${finalChoiceKey}' for profile '${profileKey}'. Use a different profile/choice key or discovery APIs.`, {
+            input,
+            profile: profileKey,
+            choice: requestedChoiceKey,
+            resolvedChoice: finalChoiceKey,
+            expectedKey: formatProfileChoiceKey(profileKey, requestedChoiceKey),
+        });
     }
     const enforceOpenRouterCatalog = profileKey === "local"
         ? options.requireOpenRouterCatalog === true
@@ -190,7 +160,7 @@ export async function resolveAIProfile(input, options) {
         loaderWarnings,
         useOpenRouter: options.useOpenRouter,
         catalog: catalogResult.catalog,
-        costCapApplied: normalizeCostCap(options.costCapPer1M),
+        costCapApplied: normalizeCostCap(costCapPer1M),
     });
     if (options.includeSecondary) {
         return attachSecondaryToResolved(resolved, registry, catalogResult.catalog, options.useOpenRouter);

package/dist/resolveAIProfile.js.map

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

package/dist/resolveAIProfileByTags.d.ts

@@ -4,8 +4,8 @@ export interface ResolveAIProfileByTagsOptions extends ResolveAIProfileOptions {
     minScore?: number;
 }
 /**
- * Resolve the best-matching profile for a tag set (partial overlap OK).
- * Picks the profile with the most matching tags; see {@link pickBestProfileByTags}.
+ * Discovery: pick the best-matching profile by tags, auto-select a choice under constraints,
+ * then resolve the resulting `profile/choice` key.
  */
 export declare function resolveAIProfileByTags(tags: AIProfileTag[], options: ResolveAIProfileByTagsOptions): Promise<ResolvedAIProfile>;
 //# sourceMappingURL=resolveAIProfileByTags.d.ts.map

package/dist/resolveAIProfileByTags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolveAIProfileByTags.d.ts","sourceRoot":"","sources":["../src/resolveAIProfileByTags.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE3F,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;IAC5E,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,YAAY,EAAE,EACpB,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CA4C5B"}
+{"version":3,"file":"resolveAIProfileByTags.d.ts","sourceRoot":"","sources":["../src/resolveAIProfileByTags.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,YAAY,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE3F,MAAM,WAAW,6BAA8B,SAAQ,uBAAuB;IAC5E,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,YAAY,EAAE,EACpB,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CA8D5B"}

package/dist/resolveAIProfileByTags.js

@@ -1,11 +1,14 @@
 import { AIProfilesError } from "./errors.js";
 import { loadAIProfilesRegistryWithWarnings } from "./loader/loadAIProfilesRegistry.js";
+import { loadModelsCatalogWithWarnings } from "./loader/loadModelsCatalog.js";
 import { profileMatchesCatalogLane } from "./profileCatalogLane.js";
 import { pickBestProfileByTags } from "./profileDiscovery.js";
+import { formatProfileChoiceKey } from "./profileChoiceKey.js";
+import { pickProfileChoiceWithConstraints } from "./modalityPolicy.js";
 import { resolveAIProfile } from "./resolveAIProfile.js";
 /**
- * Resolve the best-matching profile for a tag set (partial overlap OK).
- * Picks the profile with the most matching tags; see {@link pickBestProfileByTags}.
+ * Discovery: pick the best-matching profile by tags, auto-select a choice under constraints,
+ * then resolve the resulting `profile/choice` key.
  */
 export async function resolveAIProfileByTags(tags, options) {
     if (!options.catalogLane) {
@@ -15,19 +18,34 @@ export async function resolveAIProfileByTags(tags, options) {
     if (uniqueTags.length === 0) {
         throw new AIProfilesError("UNKNOWN_PROFILE", "resolveAIProfileByTags requires at least one tag", { tags });
     }
-    const { registry } = await loadAIProfilesRegistryWithWarnings({
-        source: options.source,
-        refresh: options.refresh,
-    });
+    const [{ registry }, catalogResult] = await Promise.all([
+        loadAIProfilesRegistryWithWarnings({
+            source: options.source,
+            refresh: options.refresh,
+        }),
+        loadModelsCatalogWithWarnings({
+            source: options.source,
+            refresh: options.refresh,
+        }),
+    ]);
     const minScore = options.minScore ?? 1;
-    const pool = options.catalogLane
-        ? Object.fromEntries(Object.entries(registry.profiles).filter(([, profile]) => profileMatchesCatalogLane(profile, options.catalogLane)))
-        : registry.profiles;
+    const pool = Object.fromEntries(Object.entries(registry.profiles).filter(([, profile]) => profileMatchesCatalogLane(profile, options.catalogLane)));
     const best = pickBestProfileByTags(pool, uniqueTags);
     if (!best || best.score < minScore) {
         throw new AIProfilesError("UNKNOWN_PROFILE", `No profile matches tags: ${uniqueTags.join(", ")}`, { tags: uniqueTags, minScore });
     }
+    const profile = registry.profiles[best.profileKey];
+    const picked = pickProfileChoiceWithConstraints(best.profileKey, profile, {
+        allowedProviders: options.allowedProviders,
+        preferLeadingVendors: options.preferLeadingVendors ?? true,
+        explicitChoiceRequested: false,
+        inputModalities: options.inputModalities,
+        outputModalities: options.outputModalities,
+        capabilityFilter: options.capabilityFilter,
+        focus: options.focus,
+        catalog: catalogResult.catalog,
+    });
     const { minScore: _minScore, ...resolveOptions } = options;
-    return resolveAIProfile(best.profileKey, resolveOptions);
+    return resolveAIProfile(formatProfileChoiceKey(best.profileKey, picked.choiceKey), resolveOptions);
 }
 //# sourceMappingURL=resolveAIProfileByTags.js.map

package/dist/resolveAIProfileByTags.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolveAIProfileByTags.js","sourceRoot":"","sources":["../src/resolveAIProfileByTags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,kCAAkC,EAAE,MAAM,oCAAoC,CAAC;AACxF,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAQzD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,IAAoB,EACpB,OAAsC;IAEtC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,IAAI,eAAe,CACvB,sBAAsB,EACtB,qDAAqD,EACrD,EAAE,IAAI,EAAE,CACT,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,eAAe,CACvB,iBAAiB,EACjB,kDAAkD,EAClD,EAAE,IAAI,EAAE,CACT,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,kCAAkC,CAAC;QAC5D,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW;QAC9B,CAAC,CAAC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CACvD,yBAAyB,CAAC,OAAO,EAAE,OAAO,CAAC,WAAY,CAAC,CACzD,CACF;QACH,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAEtB,MAAM,IAAI,GAAG,qBAAqB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAErD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,GAAG,QAAQ,EAAE,CAAC;QACnC,MAAM,IAAI,eAAe,CACvB,iBAAiB,EACjB,4BAA4B,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACnD,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAC/B,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,CAAC;IAC3D,OAAO,gBAAgB,CAAC,IAAI,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"resolveAIProfileByTags.js","sourceRoot":"","sources":["../src/resolveAIProfileByTags.ts"],"names":[],"mappings":"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"}

package/dist/resolveAIProfileWithCostAlternatives.d.ts

@@ -0,0 +1,17 @@
+import type { CostTierSpec, ResolveAIProfileOptions, ResolvedAIProfile } from "./types.js";
+export interface ResolveAIProfileWithCostAlternativesResult {
+    primary: ResolvedAIProfile;
+    alternativesByCostTier: Array<{
+        tier: string;
+        resolved: ResolvedAIProfile | null;
+        reason?: string;
+    }>;
+}
+/**
+ * Resolve a fixed `profile/choice` and scout alternate choices under other cost-tier caps.
+ */
+export declare function resolveAIProfileWithCostAlternatives(input: string, options: ResolveAIProfileOptions & {
+    tiers?: CostTierSpec[];
+    includePrimaryTier?: boolean;
+}): Promise<ResolveAIProfileWithCostAlternativesResult>;
+//# sourceMappingURL=resolveAIProfileWithCostAlternatives.d.ts.map

package/dist/resolveAIProfileWithCostAlternatives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveAIProfileWithCostAlternatives.d.ts","sourceRoot":"","sources":["../src/resolveAIProfileWithCostAlternatives.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,0CAA0C;IACzD,OAAO,EAAE,iBAAiB,CAAC;IAC3B,sBAAsB,EAAE,KAAK,CAAC;QAC5B,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;QACnC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAQD;;GAEG;AACH,wBAAsB,oCAAoC,CACxD,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,uBAAuB,GAAG;IACjC,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GACA,OAAO,CAAC,0CAA0C,CAAC,CAwJrD"}