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

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

@@ -13,7 +13,7 @@ export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, cr
 export { createVoiceProviderHealthHTMLHandler, createVoiceProviderHealthJSONHandler, createVoiceProviderHealthRoutes, renderVoiceProviderHealthHTML, summarizeVoiceProviderHealth } from './providerHealth';
 export { buildVoiceOpsConsoleReport, createVoiceOpsConsoleRoutes, renderVoiceOpsConsoleHTML } from './opsConsoleRoutes';
 export { createVoiceQualityRoutes, evaluateVoiceQuality, renderVoiceQualityHTML } from './qualityRoutes';
-export { createVoiceResilienceRoutes, listVoiceRoutingEvents, renderVoiceResilienceHTML } from './resilienceRoutes';
+export { createVoiceResilienceRoutes, createVoiceRoutingDecisionSummary, listVoiceRoutingEvents, renderVoiceResilienceHTML, summarizeVoiceRoutingDecision } from './resilienceRoutes';
 export { createVoiceSTTProviderRouter, createVoiceTTSProviderRouter } from './providerAdapters';
 export { buildVoiceTraceReplay, createVoiceMemoryTraceSinkDeliveryStore, createVoiceTraceHTTPSink, createVoiceMemoryTraceEventStore, createVoiceTraceSinkDeliveryId, createVoiceTraceSinkDeliveryRecord, createVoiceTraceSinkStore, createVoiceTraceEvent, createVoiceTraceEventId, deliverVoiceTraceEventsToSinks, evaluateVoiceTrace, exportVoiceTrace, filterVoiceTraceEvents, pruneVoiceTraceEvents, redactVoiceTraceEvent, redactVoiceTraceEvents, redactVoiceTraceText, renderVoiceTraceHTML, renderVoiceTraceMarkdown, resolveVoiceTraceRedactionOptions, selectVoiceTraceEventsForPrune, summarizeVoiceTrace } from './trace';
 export { createVoiceSQLiteExternalObjectMapStore, createVoiceSQLiteIntegrationEventStore, createVoiceSQLiteReviewStore, createVoiceSQLiteRuntimeStorage, createVoiceSQLiteSessionStore, createVoiceSQLiteTaskStore, createVoiceSQLiteTraceSinkDeliveryStore, createVoiceSQLiteTraceEventStore } from './sqliteStore';
@@ -50,8 +50,8 @@ export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOpti
 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 { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingDecisionSummary, VoiceRoutingDecisionSummaryOptions, VoiceRoutingEvent, VoiceRoutingEventKind } from './resilienceRoutes';
+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

@@ -8493,15 +8493,37 @@ var listVoiceRoutingEvents = (events) => {
       latencyBudgetMs: getNumber4(event.payload.latencyBudgetMs),
       operation: getString7(event.payload.operation),
       provider,
+      routing: getString7(event.payload.routing),
       selectedProvider: getString7(event.payload.selectedProvider),
       sessionId: event.sessionId,
       status: providerStatus,
+      suppressionRemainingMs: getNumber4(event.payload.suppressionRemainingMs),
       timedOut: getBoolean2(event.payload.timedOut),
       turnId: event.turnId
     });
   }
   return routingEvents.sort((left, right) => right.at - left.at);
 };
+var summarizeVoiceRoutingDecision = (events, options = {}) => {
+  const routingEvents = listVoiceRoutingEvents(events).filter((event) => {
+    if (options.kind && event.kind !== options.kind) {
+      return false;
+    }
+    if (options.sessionId && event.sessionId !== options.sessionId) {
+      return false;
+    }
+    return true;
+  });
+  const limited = typeof options.limit === "number" && options.limit >= 0 ? routingEvents.slice(0, options.limit) : routingEvents;
+  return limited[0] ?? null;
+};
+var createVoiceRoutingDecisionSummary = async (options) => {
+  const events = await options.store.list({
+    sessionId: options.sessionId,
+    type: "session.error"
+  });
+  return summarizeVoiceRoutingDecision(events, options);
+};
 var summarizeRoutingEvents = (events) => {
   const byKind = new Map;
   let errors = 0;
@@ -10953,9 +10975,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 +11046,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) => {
@@ -14028,6 +14102,7 @@ export {
   summarizeVoiceTrace,
   summarizeVoiceSessions,
   summarizeVoiceSessionReplay,
+  summarizeVoiceRoutingDecision,
   summarizeVoiceProviderHealth,
   summarizeVoiceOpsTasks,
   summarizeVoiceOpsTaskQueue,
@@ -14142,6 +14217,7 @@ export {
   createVoiceSQLiteIntegrationEventStore,
   createVoiceSQLiteExternalObjectMapStore,
   createVoiceS3ReviewStore,
+  createVoiceRoutingDecisionSummary,
   createVoiceReviewSavedEvent,
   createVoiceResilienceRoutes,
   createVoiceRedisTaskLeaseCoordinator,

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

@@ -13,12 +13,21 @@ export type VoiceRoutingEvent = {
     latencyBudgetMs?: number;
     operation?: string;
     provider?: string;
+    routing?: string;
     selectedProvider?: string;
     sessionId: string;
     status?: string;
+    suppressionRemainingMs?: number;
     timedOut: boolean;
     turnId?: string;
 };
+export type VoiceRoutingDecisionSummary = VoiceRoutingEvent;
+export type VoiceRoutingDecisionSummaryOptions = {
+    kind?: VoiceRoutingEventKind;
+    limit?: number;
+    sessionId?: string;
+    store: VoiceTraceEventStore;
+};
 export type VoiceResilienceLink = {
     href: string;
     label: string;
@@ -63,6 +72,8 @@ export type VoiceResilienceRoutesOptions = {
     ttsSimulation?: VoiceResilienceIOSimulator<string>;
 };
 export declare const listVoiceRoutingEvents: (events: StoredVoiceTraceEvent[]) => VoiceRoutingEvent[];
+export declare const summarizeVoiceRoutingDecision: (events: StoredVoiceTraceEvent[], options?: Omit<VoiceRoutingDecisionSummaryOptions, "store">) => VoiceRoutingDecisionSummary | null;
+export declare const createVoiceRoutingDecisionSummary: (options: VoiceRoutingDecisionSummaryOptions) => Promise<VoiceRoutingDecisionSummary | null>;
 export declare const renderVoiceResilienceHTML: (input: VoiceResiliencePageData) => string;
 export declare const createVoiceResilienceRoutes: (options: VoiceResilienceRoutesOptions) => Elysia<"", {
     decorator: {};

package/package.json

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