@x12i/ai-profiles 1.2.7 → 1.5.0

package/dist/resolveAIProfile.js

@@ -1,35 +1,50 @@
 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 { pickProfileChoice } from "./vendorPolicy.js";
+/**
+ * Resolve a profile primary key, alias, or shortcut to a concrete model and runtime config.
+ *
+ * `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` + `safer_provider`).
+ *
+ * @see README.md — “Why AI profiles”
+ */
 export async function resolveAIProfile(input, options = {}) {
-    const { registry, warnings } = await loadAIProfilesRegistryWithWarnings({
-        source: options.source,
-        refresh: options.refresh,
-    });
+    const [{ registry, warnings }, catalogResult] = await Promise.all([
+        loadAIProfilesRegistryWithWarnings({
+            source: options.source,
+            refresh: options.refresh,
+        }),
+        loadModelsCatalogWithWarnings({
+            source: options.source,
+            refresh: options.refresh,
+        }),
+    ]);
+    const loaderWarnings = [...warnings, ...catalogResult.warnings];
     const match = matchProfileInput(registry, input);
     if (!match) {
         throw new AIProfilesError("UNKNOWN_PROFILE", `Unknown AI profile, shortcut, or alias: ${input}`, { input });
     }
     let profileKey;
-    let choiceKey;
+    let requestedChoiceKey;
     let matchedShortcut;
     switch (match.kind) {
         case "profile":
             profileKey = match.profileKey;
-            choiceKey =
-                options.choice ?? registry.profiles[profileKey].defaultChoice;
+            requestedChoiceKey = options.choice;
             matchedShortcut = undefined;
             break;
         case "shortcut":
             profileKey = match.profileKey;
-            choiceKey = options.choice ?? match.shortcut.choice;
+            requestedChoiceKey = options.choice ?? match.shortcut.choice;
             matchedShortcut = match.shortcut;
             break;
         case "alias":
             profileKey = match.profileKey;
-            choiceKey =
-                options.choice ?? registry.profiles[profileKey].defaultChoice;
+            requestedChoiceKey = options.choice;
             matchedShortcut = undefined;
             break;
     }
@@ -37,15 +52,42 @@ export async function resolveAIProfile(input, options = {}) {
     if (!profile) {
         throw new AIProfilesError("UNKNOWN_PROFILE", `Unknown AI profile: ${profileKey}`, { input, profile: profileKey });
     }
-    const finalChoiceKey = choiceKey ?? profile.defaultChoice;
-    const choice = profile.choices[finalChoiceKey];
-    if (!choice) {
-        if (options.allowFallbackToDefaultChoice) {
-            return resolveAIProfile(profileKey, {
-                ...options,
-                choice: profile.defaultChoice,
+    let finalChoiceKey;
+    let choice;
+    try {
+        const picked = pickProfileChoice(profile, {
+            choiceKey: requestedChoiceKey,
+            allowedProviders: options.allowedProviders,
+            preferLeadingVendors: options.preferLeadingVendors ?? true,
+            explicitChoiceRequested: options.choice !== undefined,
+        });
+        finalChoiceKey = picked.choiceKey;
+        choice = picked.choice;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("allowedProviders")) {
+            throw new AIProfilesError("NO_ALLOWED_VENDOR", message, {
+                input,
+                profile: profileKey,
+                allowedProviders: options.allowedProviders,
+                availableProviders: [
+                    ...new Set(Object.values(profile.choices).map((c) => c.provider)),
+                ],
             });
         }
+        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 error;
+    }
+    if (!profile.choices[finalChoiceKey]) {
         throw new AIProfilesError("UNKNOWN_CHOICE", `Unknown choice '${finalChoiceKey}' for AI profile '${profileKey}'`, { input, profile: profileKey, choice: finalChoiceKey });
     }
     return buildResolvedProfile({
@@ -53,9 +95,12 @@ export async function resolveAIProfile(input, options = {}) {
         shortcutKey: match.kind === "shortcut" ? match.shortcutKey : undefined,
         profile,
         choice,
+        choiceKey: finalChoiceKey,
         shortcut: matchedShortcut,
         registry,
-        loaderWarnings: warnings,
+        loaderWarnings,
+        useOpenRouter: options.useOpenRouter,
+        catalog: catalogResult.catalog,
     });
 }
 //# sourceMappingURL=resolveAIProfile.js.map

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/resolveModelRouting.d.ts

@@ -0,0 +1,20 @@
+import type { AIProfileBackend, AIProfileChoice, AIProvider } from "./types.js";
+import { buildOpenRouterModelId } from "./modelIdentity.js";
+export type AIModelRoutingMode = "openrouter" | "direct";
+/** Reads `USE_OPENROUTER` from process env (loading `.env` once when unset). */
+export declare function readUseOpenRouterFromEnv(): boolean | undefined;
+/**
+ * Resolves whether to route via OpenRouter.
+ * Explicit option wins, then `USE_OPENROUTER` env, then default `true`.
+ */
+export declare function resolveUseOpenRouter(explicit?: boolean): boolean;
+export declare function isRemoteProfileChoice(choice: AIProfileChoice): boolean;
+export { buildOpenRouterModelId };
+export interface AppliedModelRouting {
+    provider: AIProvider;
+    modelId: string;
+    backend: AIProfileBackend;
+    routing: AIModelRoutingMode;
+}
+export declare function applyModelRouting(choice: AIProfileChoice, backend: AIProfileBackend, useOpenRouter: boolean): AppliedModelRouting;
+//# sourceMappingURL=resolveModelRouting.d.ts.map

package/dist/resolveModelRouting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveModelRouting.d.ts","sourceRoot":"","sources":["../src/resolveModelRouting.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAO5D,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAyBzD,gFAAgF;AAChF,wBAAgB,wBAAwB,IAAI,OAAO,GAAG,SAAS,CAU9D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAUtE;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAElC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,UAAU,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,OAAO,EAAE,gBAAgB,EACzB,aAAa,EAAE,OAAO,GACrB,mBAAmB,CAuBrB"}

package/dist/resolveModelRouting.js

@@ -0,0 +1,70 @@
+import { loadDotenv } from "@x12i/env";
+import { buildOpenRouterModelId } from "./modelIdentity.js";
+import { buildModelInvocationFromChoice, getChoiceOpenRouterModelId, getChoiceVendorModelId, } from "./profileRegistryV2.js";
+let dotenvLoaded = false;
+function ensureDotenvLoaded() {
+    if (!dotenvLoaded) {
+        loadDotenv();
+        dotenvLoaded = true;
+    }
+}
+function parseBooleanEnv(value) {
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized)) {
+        return true;
+    }
+    if (["0", "false", "no", "off"].includes(normalized)) {
+        return false;
+    }
+    return undefined;
+}
+/** Reads `USE_OPENROUTER` from process env (loading `.env` once when unset). */
+export function readUseOpenRouterFromEnv() {
+    ensureDotenvLoaded();
+    const raw = process.env.USE_OPENROUTER;
+    if (raw === undefined || raw.trim() === "") {
+        return undefined;
+    }
+    return parseBooleanEnv(raw);
+}
+/**
+ * Resolves whether to route via OpenRouter.
+ * Explicit option wins, then `USE_OPENROUTER` env, then default `true`.
+ */
+export function resolveUseOpenRouter(explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    return readUseOpenRouterFromEnv() ?? true;
+}
+export function isRemoteProfileChoice(choice) {
+    if (choice.provider === "local") {
+        return false;
+    }
+    if (choice.modelId.startsWith("funcx:") || choice.modelId.startsWith("Xenova/")) {
+        return false;
+    }
+    return true;
+}
+export { buildOpenRouterModelId };
+export function applyModelRouting(choice, backend, useOpenRouter) {
+    const vendorModelId = getChoiceVendorModelId(choice);
+    if (!isRemoteProfileChoice(choice) || !useOpenRouter) {
+        return {
+            provider: choice.provider,
+            modelId: vendorModelId,
+            backend: useOpenRouter ? backend : backend === "openrouter" ? "custom" : backend,
+            routing: "direct",
+        };
+    }
+    const openRouterModelId = getChoiceOpenRouterModelId(choice) ??
+        buildModelInvocationFromChoice(choice).openrouter?.modelId ??
+        buildOpenRouterModelId(choice.provider, vendorModelId);
+    return {
+        provider: "openrouter",
+        modelId: openRouterModelId,
+        backend: "openrouter",
+        routing: "openrouter",
+    };
+}
+//# sourceMappingURL=resolveModelRouting.js.map

package/dist/resolveModelRouting.js.map

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

package/dist/types.d.ts

@@ -1,4 +1,14 @@
-export type AIProvider = "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "xai" | "local" | "custom";
+/**
+ * Registry types for {@link https://github.com/x12i/ai-profiles | @x12i/ai-profiles}.
+ *
+ * An **AI profile** is a capability contract (e.g. `cheap`, `deep`, `json`) — what kind of
+ * work is needed — not a specific model. Each profile has a **default choice** and optional
+ * **choices** (alternatives) that map intent to `provider`, `modelId`, pricing, and runtime
+ * defaults. Tasks should reference profiles (and optional choices), not vendor model names.
+ *
+ * @see README.md — “Why AI profiles” for the full design rationale.
+ */
+export type AIProvider = "openai" | "anthropic" | "google" | "deepseek" | "mistral" | "groq" | "together" | "xai" | "local" | "custom" | "openrouter";
 export type InstructionTier = "default" | "cpu" | "reasoning";
 export type AIProfileBackend = "openrouter" | "llama-cpp" | "transformersjs" | "custom";
 export interface AIModelPricing {
@@ -31,27 +41,121 @@ export interface AIRuntimeDefaults {
     instructionTier?: InstructionTier;
     backend?: AIProfileBackend;
 }
+/**
+ * One implementation option within a profile (e.g. `default`, `cost_floor`, `openai_deep`).
+ * Choices let the same profile intent use different providers, cost/quality trade-offs, or
+ * capabilities (long context, batch execution) without changing caller code.
+ */
+export interface ProfileChoiceApi {
+    defaultTransport: "openrouter" | "direct";
+    vendorModelId: string;
+    openRouterModelId?: string | null;
+}
+export interface ProfileChoicePricingV2 {
+    billingModel: "token" | "self_hosted";
+    currency: "USD";
+    unit: "1M_tokens";
+    priceStatus?: "standard" | "promotional" | "estimated";
+    notes?: string;
+    standard?: {
+        input?: number;
+        output?: number;
+        cachedInput?: number;
+    };
+    batch?: {
+        input?: number;
+        output?: number;
+    };
+    cache?: {
+        write5m?: number;
+        write1h?: number;
+        hit?: number;
+        write?: number;
+    };
+    futureStandard?: {
+        input?: number;
+        output?: number;
+        validUntil?: string;
+        notes?: string;
+    };
+}
+export interface ProfileChoiceVerification {
+    lastVerifiedAt?: string;
+    sourceRefs?: string[];
+}
+export interface ProfileChoiceLimits {
+    contextWindow?: number;
+    maxOutputTokens?: number;
+}
+export type ModelAvailabilityStatus = "verified" | "predicted";
+export type DeploymentType = "proprietary" | "openWeightsHosted" | "selfHosted";
+export interface ProfileRequiredCapabilities {
+    reasoning?: "minimal" | "low" | "medium" | "high" | "max";
+    coding?: boolean;
+    context?: "standard" | "large" | "xlarge";
+    cost?: "low" | "medium" | "high";
+    speed?: "high";
+    latency?: "low";
+    quality?: "high" | "premium";
+    structuredOutput?: boolean;
+    supportsJsonSchema?: boolean;
+    supportsVision?: boolean;
+    supportsTools?: boolean;
+}
+export interface ModelCapabilitiesSnapshot {
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    supportsVision?: boolean;
+    supportsTools?: boolean;
+    supportsReasoning?: boolean;
+    supportsJsonSchema?: boolean;
+    supportsCaching?: boolean;
+    supportsBatch?: boolean;
+    supportsStreaming?: boolean;
+}
 export interface AIProfileChoice {
     choice: string;
     displayName: string;
     description: string;
+    /** Canonical vendor-native model identifier. */
     provider: AIProvider;
     modelId: string;
-    pricing?: AIModelPricing;
+    /** Whether the SKU is production-stable or a forward-looking placeholder. */
+    modelStatus?: ModelAvailabilityStatus;
+    /** How the model is operated when not a proprietary vendor API. */
+    deploymentType?: DeploymentType;
+    /** Transport mapping (v2 registry). */
+    api?: ProfileChoiceApi;
+    /** Legacy flat pricing and/or v2 nested pricing blocks. */
+    pricing?: AIModelPricing | ProfileChoicePricingV2;
     runtime?: AIRuntimeDefaults;
     reason?: string;
     status?: "active" | "experimental" | "deprecated";
+    verification?: ProfileChoiceVerification;
+    limits?: ProfileChoiceLimits;
     metadata?: Record<string, unknown>;
 }
+/**
+ * Capability contract for a class of AI work (cost, speed, reasoning, structured output,
+ * agentic tools, research, local inference). Resolved via {@link resolveAIProfile}.
+ */
 export interface AIProfileDefinition {
     profile: string;
     displayName: string;
     description: string;
+    /** Grouping for filtering (`cost`, `speed`, `standard`, `reasoning`, `output`, `agentic`, `research`, `local`). */
     category: string;
     /** Many alternate names for this profile (see `matchProfileInput`). */
     aliases?: string[];
     defaultChoice: string;
     choices: Record<string, AIProfileChoice>;
+    /** Intent contract for dynamic model selection (Optimixer). */
+    requiredCapabilities?: ProfileRequiredCapabilities;
+    /** Profile-level deployment strategy (e.g. open weights). */
+    deploymentType?: DeploymentType;
+    /** Deterministic failover order when trimming vendors or choices. */
+    fallbackChoiceOrder?: string[];
+    intendedUseCases?: string[];
     status?: "active" | "experimental" | "deprecated";
     runtime?: AIRuntimeDefaults;
     metadata?: Record<string, unknown>;
@@ -61,11 +165,25 @@ export interface AIProfileShortcut {
     choice?: string;
     description?: string;
 }
+export type ModelsProfilesSchemaId = "x12i.ai-profiles.models-profiles" | "x12i.ai-profiles.model-registry.v2" | "x12i.ai-profiles.model-registry.v3";
 export interface ModelsProfilesJson {
-    schema: "x12i.ai-profiles.models-profiles";
+    schema: ModelsProfilesSchemaId;
+    registryId?: string;
     /** Optional label in source JSON; not used for compatibility or selection logic. */
     version?: string;
     generatedAt?: string;
+    lastVerifiedAt?: string;
+    namingConvention?: string;
+    semantics?: Record<string, string>;
+    sourceCatalog?: {
+        providers: Array<{
+            id: string;
+            docsUrl?: string;
+        }>;
+        modelsCatalogUrl?: string;
+        /** @deprecated Use modelsCatalogUrl */
+        openRouterCatalogUrl?: string;
+    };
     currency: "USD";
     pricingUnit: "1M_tokens";
     profiles: Record<string, AIProfileDefinition>;
@@ -111,9 +229,149 @@ export interface AIShortcutSummary {
     description?: string;
 }
 export interface AIProfileWarning {
-    code: "USING_BUNDLED_FALLBACK" | "PROFILE_DEPRECATED" | "CHOICE_DEPRECATED" | "PRICING_MISSING" | "REMOTE_REFRESH_FAILED_USING_CACHE";
+    code: "USING_BUNDLED_FALLBACK" | "PROFILE_DEPRECATED" | "CHOICE_DEPRECATED" | "PRICING_MISSING" | "MODEL_PREDICTED" | "PRICING_FROM_CATALOG" | "REMOTE_REFRESH_FAILED_USING_CACHE" | "OPENROUTER_UNAVAILABLE";
     message: string;
 }
+export interface ModelInvocationEndpoint {
+    provider: AIProvider;
+    modelId: string;
+}
+export interface ModelInvocation {
+    direct: ModelInvocationEndpoint;
+    openrouter: ModelInvocationEndpoint | null;
+}
+export type ModelRegistryKind = "linked" | "openrouter-only" | "local-only" | "faulty";
+export type ModelLinkageStatus = "matched" | "faulty" | "skipped" | "catalog-miss";
+export interface ModelRegistryLinkage {
+    status: ModelLinkageStatus;
+    openRouterCatalogId?: string;
+    canonicalSlug?: string;
+    matchMethod?: string;
+    exemptReason?: string;
+}
+export interface ModelRegistryEntry {
+    registryKey: string;
+    kind: ModelRegistryKind;
+    vendor: ModelInvocationEndpoint;
+    invocation: ModelInvocation;
+    linkage: ModelRegistryLinkage;
+    usage: {
+        profileChoices: Array<{
+            profile: string;
+            choice: string;
+        }>;
+    };
+}
+export interface ModelsRegistryJson {
+    schema: "x12i.ai-profiles.models-registry";
+    version?: string;
+    generatedAt?: string;
+    inputs?: {
+        openRouterCatalog?: {
+            schema?: string;
+            version?: string;
+            generatedAt?: string;
+            modelCount?: number;
+        };
+        modelsProfiles?: {
+            version?: string;
+            generatedAt?: string;
+            choiceCount?: number;
+        };
+    };
+    models: Record<string, ModelRegistryEntry>;
+}
+export interface CatalogOpenRouterPricing {
+    input?: number;
+    output?: number;
+    cachedInput?: number;
+    cacheWrite?: number;
+    batchInput?: number;
+    batchOutput?: number;
+    imageInput?: number;
+    audioInput?: number;
+    internalReasoning?: number;
+    webSearchPerRequest?: number;
+}
+export interface CatalogOpenRouterCapabilities {
+    reasoning?: boolean;
+    toolCalling?: boolean;
+    structuredOutputs?: boolean;
+    imageGeneration?: boolean;
+}
+export interface CatalogDirectSlice {
+    provider: AIProvider;
+    modelId: string;
+    /**
+     * OpenRouter slug prefix when `provider` is `custom` (e.g. `qwen` for `qwen/qwen3.7-max`).
+     * Not used for API calls — documents the upstream vendor namespace.
+     */
+    vendorNamespace?: string;
+}
+export interface CatalogOpenRouterSlice {
+    provider: "openrouter";
+    modelId: string;
+    canonicalSlug?: string;
+    status?: string;
+    modalities?: {
+        input?: string[];
+        output?: string[];
+    };
+    contextWindow?: number;
+    maxCompletionTokens?: number;
+    knowledgeCutoff?: string;
+    pricing?: CatalogOpenRouterPricing;
+    capabilities?: CatalogOpenRouterCapabilities;
+}
+/**
+ * Unified catalog model: two explicit call shapes (never conflate them).
+ * - `direct` — vendor-native / direct API identity
+ * - `openrouter` — OpenRouter transport (`provider` is always `openrouter`)
+ */
+export interface CatalogModelEntry {
+    direct: CatalogDirectSlice;
+    openrouter: CatalogOpenRouterSlice;
+    displayName?: string;
+    family?: string;
+    status?: string;
+    modalities?: CatalogOpenRouterSlice["modalities"];
+    contextWindow?: number;
+    maxCompletionTokens?: number;
+    knowledgeCutoff?: string;
+}
+export interface ModelsCatalogJson {
+    schema: "x12i.ai-profiles.models-catalog";
+    version?: string;
+    generatedAt?: string;
+    currency: "USD";
+    pricingUnit: "1M_tokens";
+    sources: {
+        openrouter: {
+            catalogUrl: string;
+            pricingUrl?: string;
+            verifiedAt?: string;
+            normalization?: string;
+        };
+    };
+    notes?: string[];
+    models: CatalogModelEntry[];
+}
+/** @deprecated Use {@link ModelsCatalogJson} */
+export type OpenRouterModelsCatalogJson = ModelsCatalogJson;
+export interface ProfileVendorCoverageResult {
+    profile: string;
+    leadingVendorsPresent: AIProvider[];
+    leadingVendorsMissing: AIProvider[];
+    nonLeadingChoices: Array<{
+        choice: string;
+        provider: AIProvider;
+    }>;
+}
+export interface ValidateProfileVendorCoverageResult {
+    ok: boolean;
+    profiles: ProfileVendorCoverageResult[];
+}
+/** Materialized profile + choice: model, pricing, runtime, and routing after registry resolution. */
 export interface ResolvedAIProfile {
     input: string;
     profile: string;
@@ -125,12 +383,20 @@ export interface ResolvedAIProfile {
     choiceDescription: string;
     provider: AIProvider;
     modelId: string;
+    /** How the resolved provider/model were routed (`openrouter` vs vendor-direct). */
+    routing: "openrouter" | "direct";
     instructionTier: InstructionTier;
     backend: AIProfileBackend;
     pricing?: AIModelPricing & {
         currency: "USD";
         unit: "1M_tokens";
     };
+    /** Echo of choice modelStatus when present. */
+    modelStatus?: ModelAvailabilityStatus;
+    limits?: ProfileChoiceLimits;
+    capabilities?: ModelCapabilitiesSnapshot;
+    /** Profile intent contract (from registry definition). */
+    requiredCapabilities?: ProfileRequiredCapabilities;
     runtime: Required<AIRuntimeDefaults>;
     metadata?: Record<string, unknown>;
     reason?: string;
@@ -144,6 +410,8 @@ export interface ResolvedAIProfile {
         profile: string;
         choice?: string;
     };
+    /** Direct and OpenRouter call shapes for the resolved choice. */
+    invocation: ModelInvocation;
     warnings?: AIProfileWarning[];
 }
 export interface ListAIProfilesOptions {
@@ -159,6 +427,17 @@ export interface ResolveAIProfileOptions {
     refresh?: boolean;
     allowFallbackToDefaultChoice?: boolean;
     strict?: boolean;
+    /**
+     * When true (default), remote models resolve via OpenRouter (`provider: "openrouter"`,
+     * `modelId: "{vendor}/{model}"`). When false, use the choice's vendor provider and model id.
+     * Falls back to `USE_OPENROUTER` in `.env` when omitted (`1`/`true` → OpenRouter,
+     * `0`/`false` → direct). Azure and AWS routing are not supported yet.
+     */
+    useOpenRouter?: boolean;
+    /** Restrict resolution to these vendors; auto-picks when default is outside the set. */
+    allowedProviders?: AIProvider[];
+    /** When auto-picking, rank {@link LEADING_VENDORS} ahead of other providers (default true). */
+    preferLeadingVendors?: boolean;
 }
 export interface LoadRegistryOptions {
     source?: RegistrySourceMode;
@@ -168,4 +447,69 @@ export interface LoadRegistryResult {
     registry: AIProfilesRegistry;
     warnings: AIProfileWarning[];
 }
+export interface ProfileStatisticsFilter {
+    includeDeprecated?: boolean;
+    includeExperimental?: boolean;
+    category?: string;
+}
+export interface GetAIRegistryStatisticsOptions extends LoadRegistryOptions {
+    /** Include models catalog counts (default true). */
+    includeCatalog?: boolean;
+    /** Include profile↔catalog linkage counts (default true). */
+    includeLinkage?: boolean;
+    includeDeprecated?: boolean;
+    includeExperimental?: boolean;
+    category?: string;
+}
+export interface AIRegistryStatistics {
+    schema: "x12i.ai-profiles.registry-statistics";
+    generatedAt: string;
+    sources: {
+        profiles: "remote" | "bundled";
+        catalog?: "remote" | "bundled";
+    };
+    registry: {
+        version?: string;
+        loadedAt: string;
+        currency: "USD";
+        pricingUnit: "1M_tokens";
+    };
+    profiles: {
+        total: number;
+        choices: number;
+        aliases: number;
+        uniqueProviders: number;
+        providers: AIProvider[];
+        uniqueModelKeys: number;
+        uniqueVendorModelIds: number;
+        byStatus: Record<string, number>;
+        byCategory: Record<string, number>;
+        categories: string[];
+        averageChoicesPerProfile: number;
+    };
+    shortcuts: {
+        total: number;
+    };
+    catalog?: {
+        totalModels: number;
+        uniqueDirectProviders: number;
+        directProviders: string[];
+        active: number;
+        deprecated: number;
+        withPricing: number;
+        withReasoningCapability: number;
+        catalogVersion?: string;
+        generatedAt?: string;
+    };
+    linkage?: {
+        registryEntries: number;
+        profileChoiceReferences: number;
+        byLinkageStatus: Record<string, number>;
+        byKind: Record<string, number>;
+        matched: number;
+        faulty: number;
+        catalogMiss: number;
+        skipped: number;
+    };
+}
 //# sourceMappingURL=types.d.ts.map