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

package/README.md

@@ -1242,6 +1242,38 @@ const model = createVoiceProviderRouter({
 });
 ```
 
+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

@@ -51,7 +51,7 @@ export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProvid
 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

@@ -10953,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();
@@ -11019,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) => {

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/package.json

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