@absolutejs/voice 0.0.22-beta.55 → 0.0.22-beta.57

package/README.md

@@ -1178,6 +1178,102 @@ app.use(
   - `benchmark-results/sessions-cheap-stt-runs-3.json`
   - `benchmark-results/stt-routing-run-manifest.json`
 
+## LLM Provider Routing
+
+Use `createVoiceProviderRouter(...)` when your assistant can run on more than one LLM provider. The router keeps provider choice inside your app: you define the available model adapters, profile each provider, and choose a policy.
+
+```ts
+import {
+	createAnthropicVoiceAssistantModel,
+	createGeminiVoiceAssistantModel,
+	createOpenAIVoiceAssistantModel,
+	createVoiceProviderRouter,
+	resolveVoiceProviderRoutingPolicyPreset
+} from '@absolutejs/voice';
+
+const model = createVoiceProviderRouter({
+	providers: {
+		openai: createOpenAIVoiceAssistantModel({ apiKey: process.env.OPENAI_API_KEY! }),
+		anthropic: createAnthropicVoiceAssistantModel({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+		gemini: createGeminiVoiceAssistantModel({ apiKey: process.env.GEMINI_API_KEY! })
+	},
+	providerHealth: {
+		failureThreshold: 1,
+		cooldownMs: 30_000,
+		rateLimitCooldownMs: 120_000
+	},
+	providerProfiles: {
+		openai: { cost: 6, latencyMs: 650, quality: 0.92, timeoutMs: 3500 },
+		anthropic: { cost: 7, latencyMs: 850, quality: 0.95, timeoutMs: 4500 },
+		gemini: { cost: 2, latencyMs: 700, quality: 0.86, timeoutMs: 3500 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('balanced')
+});
+```
+
+Built-in policy presets:
+
+- `quality-first`: rank by `providerProfiles[provider].quality`, then priority, latency, and cost.
+- `latency-first`: rank by expected latency.
+- `cost-first`: rank by expected cost.
+- `cost-cap`: rank by cost and reject providers above `maxCost`.
+- `balanced`: weighted score using cost, latency, quality, and priority.
+
+Budget filters are strict. If you pass `maxCost`, `maxLatencyMs`, or `minQuality`, providers outside those limits are removed before ranking, even if they were selected by the request.
+
+```ts
+const policy = resolveVoiceProviderRoutingPolicyPreset('cost-cap', {
+	maxCost: 3,
+	minQuality: 0.82
+});
+```
+
+For full control, pass an object policy:
+
+```ts
+const model = createVoiceProviderRouter({
+	providers,
+	providerProfiles,
+	policy: {
+		strategy: 'balanced',
+		maxLatencyMs: 1000,
+		weights: { cost: 1, latencyMs: 0.004, quality: 12 }
+	}
+});
+```
+
+The same profile and policy shape also works for STT and TTS provider routers, so a self-hosted app can choose the fastest provider for live calls, cap cost for background work, or require a minimum quality score without hard-coding provider branches.
+
+```ts
+const stt = createVoiceSTTProviderRouter({
+	adapters: {
+		deepgram,
+		assemblyai
+	},
+	providerHealth: { cooldownMs: 30_000 },
+	providerProfiles: {
+		deepgram: { cost: 4, latencyMs: 180, quality: 0.93, timeoutMs: 1500 },
+		assemblyai: { cost: 2, latencyMs: 650, quality: 0.88, timeoutMs: 3000 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('latency-first')
+});
+
+const tts = createVoiceTTSProviderRouter({
+	adapters: {
+		elevenlabs,
+		openai
+	},
+	providerProfiles: {
+		elevenlabs: { cost: 5, latencyMs: 220, quality: 0.94 },
+		openai: { cost: 2, latencyMs: 320, quality: 0.87 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('cost-cap', {
+		maxCost: 3,
+		minQuality: 0.85
+	})
+});
+```
+
 ## Presets
 
 Voice now ships named runtime presets so apps can start from a useful baseline instead of hand-tuning silence and capture settings every time.

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, crea
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool } from './agent';
 export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileExternalObjectMapStore, createVoiceFileAssistantMemoryStore, createVoiceFileIntegrationEventStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore } from './fileStore';
 export { createVoiceAssistantMemoryHandle, createVoiceAssistantMemoryRecord, createVoiceMemoryAssistantMemoryStore, resolveVoiceAssistantMemoryNamespace } from './assistantMemory';
-export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, createVoiceProviderRouter } from './modelAdapters';
+export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter } from './modelAdapters';
 export { createVoiceProviderHealthHTMLHandler, createVoiceProviderHealthJSONHandler, createVoiceProviderHealthRoutes, renderVoiceProviderHealthHTML, summarizeVoiceProviderHealth } from './providerHealth';
 export { buildVoiceOpsConsoleReport, createVoiceOpsConsoleRoutes, renderVoiceOpsConsoleHTML } from './opsConsoleRoutes';
 export { createVoiceQualityRoutes, evaluateVoiceQuality, renderVoiceQualityHTML } from './qualityRoutes';
@@ -46,12 +46,12 @@ export type { VoiceDiagnosticsRoutesOptions } from './diagnosticsRoutes';
 export type { VoiceEvalBaselineComparison, VoiceEvalBaselineComparisonOptions, VoiceEvalBaselineStore, VoiceEvalBaselineSummary, VoiceEvalLink, VoiceEvalReport, VoiceEvalRoutesOptions, VoiceEvalSessionReport, VoiceEvalStatus, VoiceEvalTrendBucket, VoiceScenarioEvalDefinition, VoiceScenarioEvalReport, VoiceScenarioEvalResult, VoiceScenarioEvalSessionResult, VoiceScenarioFixture, VoiceScenarioFixtureEvalReport, VoiceScenarioFixtureEvalResult, VoiceScenarioFixtureStore } from './evalRoutes';
 export type { VoiceWorkflowContract, VoiceWorkflowContractDefinition, VoiceWorkflowContractField, VoiceWorkflowContractFieldMatch, VoiceWorkflowContractPresetName, VoiceWorkflowContractPresetOptions, VoiceWorkflowContractTracePayload, VoiceWorkflowContractValidation, VoiceWorkflowContractValidationIssue, VoiceWorkflowOutcome } from './workflowContract';
 export type { VoiceSessionListHTMLHandlerOptions, VoiceSessionListItem, VoiceSessionListOptions, VoiceSessionListRoutesOptions, VoiceSessionListStatus, VoiceSessionReplay, VoiceSessionReplayHTMLHandlerOptions, VoiceSessionReplayOptions, VoiceSessionReplayRoutesOptions, VoiceSessionReplayTurn } from './sessionReplay';
-export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOptions, OpenAIVoiceAssistantModelOptions, VoiceProviderRouterEvent, VoiceProviderRouterFallbackMode, VoiceProviderRouterHealthOptions, VoiceProviderRouterOptions, VoiceProviderRouterPolicy, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceJSONAssistantModelHandler, VoiceJSONAssistantModelOptions } from './modelAdapters';
+export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOptions, OpenAIVoiceAssistantModelOptions, VoiceProviderRouterEvent, VoiceProviderRouterFallbackMode, VoiceProviderRouterHealthOptions, VoiceProviderRouterOptions, VoiceProviderRouterPolicy, VoiceProviderRouterPolicyPreset, VoiceProviderRouterPolicyWeights, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceProviderRouterStrategy, VoiceJSONAssistantModelHandler, VoiceJSONAssistantModelOptions } from './modelAdapters';
 export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProviderHealthSummaryOptions } from './providerHealth';
 export type { VoiceOpsConsoleLink, VoiceOpsConsoleReport, VoiceOpsConsoleRoutesOptions } from './opsConsoleRoutes';
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';
 export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingEvent, VoiceRoutingEventKind } from './resilienceRoutes';
-export type { VoiceIOProviderRouterEvent, VoiceSTTProviderRouterOptions, VoiceTTSProviderRouterOptions } from './providerAdapters';
+export type { VoiceIOProviderRouterEvent, VoiceIOProviderRouterOptions, VoiceIOProviderRouterPolicy, VoiceIOProviderRouterPolicyConfig, VoiceSTTProviderRouterOptions, VoiceTTSProviderRouterOptions } from './providerAdapters';
 export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadOptions, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
 export type { VoiceOpsRuntime, VoiceOpsRuntimeConfig, VoiceOpsRuntimeSummary, VoiceOpsRuntimeSinkWorkerConfig, VoiceOpsRuntimeTaskWorkerConfig, VoiceOpsRuntimeTickResult, VoiceOpsRuntimeWebhookWorkerConfig } from './opsRuntime';
 export type { VoiceOpsPresetName, VoiceOpsPresetOverrides, VoiceResolvedOpsPreset } from './opsPresets';

package/dist/index.js

@@ -10024,6 +10024,47 @@ var createStoredVoiceExternalObjectMap = (mapping) => createVoiceExternalObjectM
   sourceType: mapping.sourceType
 });
 // src/modelAdapters.ts
+var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
+  switch (preset) {
+    case "balanced":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "balanced",
+        weights: {
+          cost: 1,
+          latencyMs: 0.005,
+          priority: 1,
+          quality: 10,
+          ...options.weights
+        },
+        ...options
+      };
+    case "cost-cap":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-cheapest",
+        ...options
+      };
+    case "cost-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-cheapest",
+        ...options
+      };
+    case "latency-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-fastest",
+        ...options
+      };
+    case "quality-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "quality-first",
+        ...options
+      };
+  }
+};
 var OUTPUT_SCHEMA = {
   additionalProperties: false,
   properties: {
@@ -10191,7 +10232,7 @@ var createJSONVoiceAssistantModel = (options) => ({
 var createVoiceProviderRouter = (options) => {
   const providerIds = Object.keys(options.providers);
   const firstProvider = providerIds[0];
-  const policy = typeof options.policy === "string" ? {
+  const policy = typeof options.policy === "string" ? options.policy === "balanced" || options.policy === "cost-cap" || options.policy === "cost-first" || options.policy === "latency-first" || options.policy === "quality-first" ? resolveVoiceProviderRoutingPolicyPreset(options.policy) : {
     strategy: options.policy
   } : options.policy;
   const strategy = policy?.strategy ?? "prefer-selected";
@@ -10273,13 +10314,40 @@ var createVoiceProviderRouter = (options) => {
     const allowed = typeof allowProviders === "function" ? await allowProviders(input) : allowProviders;
     return new Set(allowed ?? providerIds);
   };
+  const passesBudgetFilters = (provider) => {
+    const profile = options.providerProfiles?.[provider];
+    if (typeof policy?.maxCost === "number" && typeof profile?.cost === "number" && profile.cost > policy.maxCost) {
+      return false;
+    }
+    if (typeof policy?.maxLatencyMs === "number" && typeof profile?.latencyMs === "number" && profile.latencyMs > policy.maxLatencyMs) {
+      return false;
+    }
+    if (typeof policy?.minQuality === "number" && typeof profile?.quality === "number" && profile.quality < policy.minQuality) {
+      return false;
+    }
+    return true;
+  };
+  const getBalancedScore = (provider) => {
+    const profile = options.providerProfiles?.[provider];
+    if (policy?.scoreProvider) {
+      return policy.scoreProvider(provider, profile);
+    }
+    const weights = policy?.weights ?? {};
+    return (profile?.cost ?? Number.MAX_SAFE_INTEGER) * (weights.cost ?? 1) + (profile?.latencyMs ?? Number.MAX_SAFE_INTEGER) * (weights.latencyMs ?? 0.005) + (profile?.priority ?? 0) * (weights.priority ?? 1) - (profile?.quality ?? 0) * (weights.quality ?? 10);
+  };
   const sortProviders = (providers) => {
-    if (strategy !== "prefer-cheapest" && strategy !== "prefer-fastest") {
+    if (strategy !== "prefer-cheapest" && strategy !== "prefer-fastest" && strategy !== "quality-first" && strategy !== "balanced") {
       return providers;
     }
     return [...providers].sort((left, right) => {
       const leftProfile = options.providerProfiles?.[left];
       const rightProfile = options.providerProfiles?.[right];
+      if (strategy === "quality-first") {
+        return (rightProfile?.quality ?? Number.MIN_SAFE_INTEGER) - (leftProfile?.quality ?? Number.MIN_SAFE_INTEGER) || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.cost ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.cost ?? Number.MAX_SAFE_INTEGER);
+      }
+      if (strategy === "balanced") {
+        return getBalancedScore(left) - getBalancedScore(right);
+      }
       const leftValue = strategy === "prefer-cheapest" ? leftProfile?.cost ?? Number.MAX_SAFE_INTEGER : leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
       const rightValue = strategy === "prefer-cheapest" ? rightProfile?.cost ?? Number.MAX_SAFE_INTEGER : rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
       return leftValue - rightValue || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER);
@@ -10289,12 +10357,13 @@ var createVoiceProviderRouter = (options) => {
     const selectedProvider = await options.selectProvider?.(input);
     const allowedProviders = await resolveAllowedProviders(input);
     const fallbackOrder = typeof options.fallback === "function" ? await options.fallback(input) : options.fallback;
-    const rankedProviders = sortProviders([
+    const allowedRankedProviders = sortProviders([
       ...fallbackOrder ?? providerIds
     ]).filter((provider) => allowedProviders.has(provider));
+    const rankedProviders = allowedRankedProviders.filter(passesBudgetFilters);
     const healthyRankedProviders = healthOptions ? rankedProviders.filter((provider) => !isSuppressed(provider)) : rankedProviders;
     const candidateRankedProviders = healthyRankedProviders.length ? healthyRankedProviders : rankedProviders;
-    const preferred = selectedProvider && allowedProviders.has(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : candidateRankedProviders[0] ?? firstProvider;
+    const preferred = selectedProvider && allowedProviders.has(selectedProvider) && passesBudgetFilters(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : candidateRankedProviders[0] ?? firstProvider;
     const seen = new Set;
     const order = [];
     const candidates = strategy === "ordered" ? candidateRankedProviders : [
@@ -10884,9 +10953,14 @@ var withTimeout = async (input) => {
     }
   }
 };
+var isVoiceProviderRoutingPolicyPreset = (policy) => policy === "balanced" || policy === "cost-cap" || policy === "cost-first" || policy === "latency-first" || policy === "quality-first";
 var createResolver = (options) => {
   const providerIds = Object.keys(options.adapters);
   const firstProvider = providerIds[0];
+  const policy = typeof options.policy === "string" ? isVoiceProviderRoutingPolicyPreset(options.policy) ? resolveVoiceProviderRoutingPolicyPreset(options.policy) : {
+    strategy: options.policy
+  } : options.policy;
+  const strategy = policy?.strategy ?? "prefer-selected";
   const healthOptions = typeof options.providerHealth === "object" ? options.providerHealth : options.providerHealth ? {} : undefined;
   const healthState = new Map;
   const now = () => healthOptions?.now?.() ?? Date.now();
@@ -10950,23 +11024,70 @@ var createResolver = (options) => {
     }
     return cloneHealth(provider);
   };
+  const resolveAllowedProviders = async (input) => {
+    const allowed = typeof policy?.allowProviders === "function" ? await policy.allowProviders(input) : policy?.allowProviders;
+    return new Set(allowed ?? providerIds);
+  };
+  const passesBudgetFilters = (provider) => {
+    const profile = options.providerProfiles?.[provider];
+    if (typeof policy?.maxCost === "number" && typeof profile?.cost === "number" && profile.cost > policy.maxCost) {
+      return false;
+    }
+    if (typeof policy?.maxLatencyMs === "number" && typeof profile?.latencyMs === "number" && profile.latencyMs > policy.maxLatencyMs) {
+      return false;
+    }
+    if (typeof policy?.minQuality === "number" && typeof profile?.quality === "number" && profile.quality < policy.minQuality) {
+      return false;
+    }
+    return true;
+  };
+  const getBalancedScore = (provider) => {
+    const profile = options.providerProfiles?.[provider];
+    if (policy?.scoreProvider) {
+      return policy.scoreProvider(provider, profile);
+    }
+    const weights = policy?.weights ?? {};
+    return (profile?.cost ?? Number.MAX_SAFE_INTEGER) * (weights.cost ?? 1) + (profile?.latencyMs ?? Number.MAX_SAFE_INTEGER) * (weights.latencyMs ?? 0.005) + (profile?.priority ?? 0) * (weights.priority ?? 1) - (profile?.quality ?? 0) * (weights.quality ?? 10);
+  };
+  const sortProviders = (providers) => {
+    if (strategy !== "prefer-cheapest" && strategy !== "prefer-fastest" && strategy !== "quality-first" && strategy !== "balanced") {
+      return providers;
+    }
+    return [...providers].sort((left, right) => {
+      const leftProfile = options.providerProfiles?.[left];
+      const rightProfile = options.providerProfiles?.[right];
+      if (strategy === "quality-first") {
+        return (rightProfile?.quality ?? Number.MIN_SAFE_INTEGER) - (leftProfile?.quality ?? Number.MIN_SAFE_INTEGER) || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.cost ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.cost ?? Number.MAX_SAFE_INTEGER);
+      }
+      if (strategy === "balanced") {
+        return getBalancedScore(left) - getBalancedScore(right);
+      }
+      const leftValue = strategy === "prefer-cheapest" ? leftProfile?.cost ?? Number.MAX_SAFE_INTEGER : leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
+      const rightValue = strategy === "prefer-cheapest" ? rightProfile?.cost ?? Number.MAX_SAFE_INTEGER : rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
+      return leftValue - rightValue || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER);
+    });
+  };
   const resolveOrder = async (input) => {
-    const selectedProvider = await options.selectProvider?.(input) ?? firstProvider;
+    const requestedProvider = await options.selectProvider?.(input);
+    const selectedProvider = requestedProvider ?? firstProvider;
+    const allowedProviders = await resolveAllowedProviders(input);
     const fallbackOrder = typeof options.fallback === "function" ? await options.fallback(input) : options.fallback;
     const candidates = [selectedProvider, ...fallbackOrder ?? providerIds];
     const seen = new Set;
-    const rankedOrder = candidates.filter((provider) => {
+    const orderedCandidates = candidates.filter((provider) => {
       if (!provider || seen.has(provider) || !options.adapters[provider]) {
         return false;
       }
       seen.add(provider);
       return true;
     });
+    const rankedOrder = sortProviders(orderedCandidates).filter((provider) => allowedProviders.has(provider)).filter(passesBudgetFilters);
     const healthyOrder = healthOptions ? rankedOrder.filter((provider) => !isSuppressed(provider)) : rankedOrder;
     const order = healthyOrder.length ? healthyOrder : rankedOrder;
+    const preferred = strategy === "prefer-selected" && selectedProvider && allowedProviders.has(selectedProvider) && passesBudgetFilters(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : order[0];
     return {
       order,
-      selectedProvider: selectedProvider && !isSuppressed(selectedProvider) ? selectedProvider : order[0]
+      selectedProvider: preferred
     };
   };
   const emit = async (event, input) => {
@@ -13978,6 +14099,7 @@ export {
   resolveVoiceTraceRedactionOptions,
   resolveVoiceSTTRoutingStrategy,
   resolveVoiceRuntimePreset,
+  resolveVoiceProviderRoutingPolicyPreset,
   resolveVoiceOutcomeRecipe,
   resolveVoiceOpsTaskPolicy,
   resolveVoiceOpsTaskAssignment,

package/dist/modelAdapters.d.ts

@@ -52,17 +52,32 @@ export type VoiceProviderRouterEvent<TProvider extends string = string> = {
     timedOut?: boolean;
 };
 export type VoiceProviderRouterFallbackMode = 'never' | 'provider-error' | 'rate-limit';
-export type VoiceProviderRouterPolicy<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string> = 'ordered' | 'prefer-cheapest' | 'prefer-fastest' | 'prefer-selected' | {
+export type VoiceProviderRouterStrategy = 'balanced' | 'ordered' | 'prefer-cheapest' | 'prefer-fastest' | 'prefer-selected' | 'quality-first';
+export type VoiceProviderRouterPolicyPreset = 'balanced' | 'cost-cap' | 'cost-first' | 'latency-first' | 'quality-first';
+export type VoiceProviderRouterPolicyWeights = {
+    cost?: number;
+    latencyMs?: number;
+    priority?: number;
+    quality?: number;
+};
+export type VoiceProviderRouterPolicy<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string> = VoiceProviderRouterStrategy | VoiceProviderRouterPolicyPreset | {
     allowProviders?: readonly TProvider[] | ((input: VoiceAgentModelInput<TContext, TSession>) => readonly TProvider[] | Promise<readonly TProvider[]>);
     fallbackMode?: VoiceProviderRouterFallbackMode;
-    strategy?: 'ordered' | 'prefer-cheapest' | 'prefer-fastest' | 'prefer-selected';
+    maxCost?: number;
+    maxLatencyMs?: number;
+    minQuality?: number;
+    scoreProvider?: (provider: TProvider, profile: VoiceProviderRouterProviderProfile | undefined) => number;
+    strategy?: VoiceProviderRouterStrategy;
+    weights?: VoiceProviderRouterPolicyWeights;
 };
 export type VoiceProviderRouterProviderProfile = {
     cost?: number;
     latencyMs?: number;
     priority?: number;
+    quality?: number;
     timeoutMs?: number;
 };
+export declare const resolveVoiceProviderRoutingPolicyPreset: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string>(preset: VoiceProviderRouterPolicyPreset, options?: Omit<Extract<VoiceProviderRouterPolicy<TContext, TSession, TProvider>, Record<string, unknown>>, "strategy">) => Extract<VoiceProviderRouterPolicy<TContext, TSession, TProvider>, Record<string, unknown>>;
 export type VoiceProviderRouterHealthOptions = {
     cooldownMs?: number;
     failureThreshold?: number;

package/dist/providerAdapters.d.ts

@@ -1,5 +1,5 @@
 import type { STTAdapter, STTAdapterOpenOptions, TTSAdapter, TTSAdapterOpenOptions } from './types';
-import type { VoiceProviderRouterHealthOptions, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile } from './modelAdapters';
+import type { VoiceProviderRouterHealthOptions, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceProviderRouterPolicyPreset, VoiceProviderRouterPolicyWeights, VoiceProviderRouterStrategy } from './modelAdapters';
 type MaybePromise<T> = T | Promise<T>;
 type VoiceIOProviderKind = 'stt' | 'tts';
 type VoiceIOProviderStatus = 'error' | 'fallback' | 'success';
@@ -20,11 +20,22 @@ export type VoiceIOProviderRouterEvent<TProvider extends string = string> = {
     suppressedUntil?: number;
     timedOut?: boolean;
 };
+export type VoiceIOProviderRouterPolicyConfig<TOpenOptions = unknown, TProvider extends string = string> = {
+    allowProviders?: readonly TProvider[] | ((input: TOpenOptions) => MaybePromise<readonly TProvider[]>);
+    maxCost?: number;
+    maxLatencyMs?: number;
+    minQuality?: number;
+    scoreProvider?: (provider: TProvider, profile: VoiceProviderRouterProviderProfile | undefined) => number;
+    strategy?: VoiceProviderRouterStrategy;
+    weights?: VoiceProviderRouterPolicyWeights;
+};
+export type VoiceIOProviderRouterPolicy<TOpenOptions = unknown, TProvider extends string = string> = VoiceProviderRouterStrategy | VoiceProviderRouterPolicyPreset | VoiceIOProviderRouterPolicyConfig<TOpenOptions, TProvider>;
 export type VoiceIOProviderRouterOptions<TProvider extends string, TAdapter, TOpenOptions> = {
     adapters: Partial<Record<TProvider, TAdapter>>;
     fallback?: readonly TProvider[] | ((input: TOpenOptions) => MaybePromise<readonly TProvider[]>);
     isProviderError?: (error: unknown, provider: TProvider) => boolean;
     onProviderEvent?: (event: VoiceIOProviderRouterEvent<TProvider>, input: TOpenOptions) => Promise<void> | void;
+    policy?: VoiceIOProviderRouterPolicy<TOpenOptions, TProvider>;
     providerHealth?: boolean | VoiceProviderRouterHealthOptions;
     providerProfiles?: Partial<Record<TProvider, VoiceProviderRouterProviderProfile>>;
     selectProvider?: (input: TOpenOptions) => MaybePromise<TProvider | undefined>;

package/dist/testing/index.js

@@ -3628,6 +3628,47 @@ var createVoiceIOProviderFailureSimulator = (options) => {
   };
 };
 // src/modelAdapters.ts
+var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
+  switch (preset) {
+    case "balanced":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "balanced",
+        weights: {
+          cost: 1,
+          latencyMs: 0.005,
+          priority: 1,
+          quality: 10,
+          ...options.weights
+        },
+        ...options
+      };
+    case "cost-cap":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-cheapest",
+        ...options
+      };
+    case "cost-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-cheapest",
+        ...options
+      };
+    case "latency-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "prefer-fastest",
+        ...options
+      };
+    case "quality-first":
+      return {
+        fallbackMode: "provider-error",
+        strategy: "quality-first",
+        ...options
+      };
+  }
+};
 var OUTPUT_SCHEMA = {
   additionalProperties: false,
   properties: {
@@ -3795,7 +3836,7 @@ var createJSONVoiceAssistantModel = (options) => ({
 var createVoiceProviderRouter = (options) => {
   const providerIds = Object.keys(options.providers);
   const firstProvider = providerIds[0];
-  const policy = typeof options.policy === "string" ? {
+  const policy = typeof options.policy === "string" ? options.policy === "balanced" || options.policy === "cost-cap" || options.policy === "cost-first" || options.policy === "latency-first" || options.policy === "quality-first" ? resolveVoiceProviderRoutingPolicyPreset(options.policy) : {
     strategy: options.policy
   } : options.policy;
   const strategy = policy?.strategy ?? "prefer-selected";
@@ -3877,13 +3918,40 @@ var createVoiceProviderRouter = (options) => {
     const allowed = typeof allowProviders === "function" ? await allowProviders(input) : allowProviders;
     return new Set(allowed ?? providerIds);
   };
+  const passesBudgetFilters = (provider) => {
+    const profile = options.providerProfiles?.[provider];
+    if (typeof policy?.maxCost === "number" && typeof profile?.cost === "number" && profile.cost > policy.maxCost) {
+      return false;
+    }
+    if (typeof policy?.maxLatencyMs === "number" && typeof profile?.latencyMs === "number" && profile.latencyMs > policy.maxLatencyMs) {
+      return false;
+    }
+    if (typeof policy?.minQuality === "number" && typeof profile?.quality === "number" && profile.quality < policy.minQuality) {
+      return false;
+    }
+    return true;
+  };
+  const getBalancedScore = (provider) => {
+    const profile = options.providerProfiles?.[provider];
+    if (policy?.scoreProvider) {
+      return policy.scoreProvider(provider, profile);
+    }
+    const weights = policy?.weights ?? {};
+    return (profile?.cost ?? Number.MAX_SAFE_INTEGER) * (weights.cost ?? 1) + (profile?.latencyMs ?? Number.MAX_SAFE_INTEGER) * (weights.latencyMs ?? 0.005) + (profile?.priority ?? 0) * (weights.priority ?? 1) - (profile?.quality ?? 0) * (weights.quality ?? 10);
+  };
   const sortProviders = (providers) => {
-    if (strategy !== "prefer-cheapest" && strategy !== "prefer-fastest") {
+    if (strategy !== "prefer-cheapest" && strategy !== "prefer-fastest" && strategy !== "quality-first" && strategy !== "balanced") {
       return providers;
     }
     return [...providers].sort((left, right) => {
       const leftProfile = options.providerProfiles?.[left];
       const rightProfile = options.providerProfiles?.[right];
+      if (strategy === "quality-first") {
+        return (rightProfile?.quality ?? Number.MIN_SAFE_INTEGER) - (leftProfile?.quality ?? Number.MIN_SAFE_INTEGER) || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.cost ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.cost ?? Number.MAX_SAFE_INTEGER);
+      }
+      if (strategy === "balanced") {
+        return getBalancedScore(left) - getBalancedScore(right);
+      }
       const leftValue = strategy === "prefer-cheapest" ? leftProfile?.cost ?? Number.MAX_SAFE_INTEGER : leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
       const rightValue = strategy === "prefer-cheapest" ? rightProfile?.cost ?? Number.MAX_SAFE_INTEGER : rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
       return leftValue - rightValue || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER);
@@ -3893,12 +3961,13 @@ var createVoiceProviderRouter = (options) => {
     const selectedProvider = await options.selectProvider?.(input);
     const allowedProviders = await resolveAllowedProviders(input);
     const fallbackOrder = typeof options.fallback === "function" ? await options.fallback(input) : options.fallback;
-    const rankedProviders = sortProviders([
+    const allowedRankedProviders = sortProviders([
       ...fallbackOrder ?? providerIds
     ]).filter((provider) => allowedProviders.has(provider));
+    const rankedProviders = allowedRankedProviders.filter(passesBudgetFilters);
     const healthyRankedProviders = healthOptions ? rankedProviders.filter((provider) => !isSuppressed(provider)) : rankedProviders;
     const candidateRankedProviders = healthyRankedProviders.length ? healthyRankedProviders : rankedProviders;
-    const preferred = selectedProvider && allowedProviders.has(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : candidateRankedProviders[0] ?? firstProvider;
+    const preferred = selectedProvider && allowedProviders.has(selectedProvider) && passesBudgetFilters(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : candidateRankedProviders[0] ?? firstProvider;
     const seen = new Set;
     const order = [];
     const candidates = strategy === "ordered" ? candidateRankedProviders : [

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.55",
+	"version": "0.0.22-beta.57",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",