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

package/README.md

@@ -1178,6 +1178,70 @@ 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 }
+	}
+});
+```
+
 ## 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,7 +46,7 @@ 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';

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 : [
@@ -13978,6 +14047,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/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.56",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",