@absolutejs/voice 0.0.22-beta.291 → 0.0.22-beta.293

package/README.md

@@ -3888,6 +3888,108 @@ Built-in policy presets:
 - `cost-cap`: rank by cost and reject providers above `maxCost`.
 - `balanced`: weighted score using cost, latency, quality, and priority.
 
+Use `createVoiceProviderOrchestrationProfile(...)` when one app has multiple provider surfaces with different tradeoffs. This is the Vapi-style "choose providers without glue" layer, but still code-owned: a live call can prefer low latency with a circuit breaker, while a background summary can prefer lower cost and stricter budget caps.
+
+```ts
+import {
+	createVoiceProviderOrchestrationProfile,
+	createVoiceProviderRouter
+} from '@absolutejs/voice';
+
+const providerProfile = createVoiceProviderOrchestrationProfile({
+	id: 'support-agent-providers',
+	defaultSurface: 'live-call',
+	surfaces: {
+		'live-call': {
+			policy: 'latency-first',
+			fallback: ['openai', 'anthropic', 'gemini'],
+			maxLatencyMs: 900,
+			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 }
+			}
+		},
+		'background-summary': {
+			policy: 'cost-cap',
+			fallback: ['gemini', 'openai'],
+			maxCost: 3,
+			minQuality: 0.82,
+			providerProfiles: {
+				openai: { cost: 6, latencyMs: 650, quality: 0.92 },
+				gemini: { cost: 2, latencyMs: 700, quality: 0.86 }
+			}
+		}
+	}
+});
+
+const liveModel = createVoiceProviderRouter({
+	providers,
+	orchestrationProfile: providerProfile,
+	orchestrationSurface: 'live-call'
+});
+
+const summaryModel = createVoiceProviderRouter({
+	providers,
+	orchestrationProfile: providerProfile,
+	orchestrationSurface: 'background-summary'
+});
+```
+
+Mount `createVoiceProviderOrchestrationRoutes(...)` and pass the report into production readiness when provider policy should be deploy-gated. This proves that required surfaces have enough providers, explicit fallback order, circuit-breaker settings, timeout budgets, and cost/latency/quality bounds.
+
+```ts
+import {
+	buildVoiceProviderOrchestrationReport,
+	createVoiceProviderOrchestrationRoutes,
+	createVoiceProductionReadinessRoutes
+} from '@absolutejs/voice';
+
+const providerOrchestration = () =>
+	buildVoiceProviderOrchestrationReport({
+		profile: providerProfile,
+		requirements: {
+			'live-call': {
+				minProviders: 2,
+				requireBudgetPolicy: true,
+				requireCircuitBreaker: true,
+				requireFallback: true,
+				requireTimeoutBudget: true
+			}
+		}
+	});
+
+app
+	.use(
+		createVoiceProviderOrchestrationRoutes({
+			profile: providerProfile,
+			requirements: {
+				'live-call': {
+					minProviders: 2,
+					requireBudgetPolicy: true,
+					requireCircuitBreaker: true,
+					requireFallback: true,
+					requireTimeoutBudget: true
+				}
+			}
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			store: runtime.traces,
+			providerOrchestration,
+			links: {
+				providerOrchestration: '/voice/provider-orchestration'
+			}
+		})
+	);
+```
+
 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

package/dist/index.d.ts

@@ -46,11 +46,12 @@ export { applyVoiceTelephonyOutcome, assertVoiceTelephonyWebhookNormalizationEvi
 export { assertVoicePhoneCallControlEvidence, assertVoicePhoneAssistantEvidence, createVoicePhoneAgent, evaluateVoicePhoneCallControlEvidence, evaluateVoicePhoneAssistantEvidence } from './phoneAgent';
 export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileIncidentBundleStore, createVoiceFileExternalObjectMapStore, createVoiceFileAssistantMemoryStore, createVoiceFileAuditEventStore, createVoiceFileAuditSinkDeliveryStore, createVoiceFileCampaignStore, createVoiceFileIntegrationEventStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore } from './fileStore';
 export { createVoiceAssistantMemoryHandle, createVoiceAssistantMemoryRecord, createVoiceMemoryAssistantMemoryStore, resolveVoiceAssistantMemoryNamespace } from './assistantMemory';
-export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter } from './modelAdapters';
+export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, createVoiceProviderOrchestrationProfile, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter } from './modelAdapters';
 export { createOpenAIRealtimeAdapter } from './openaiRealtime';
 export { createOpenAIVoiceTTS } from './openaiTTS';
 export { createVoiceProviderHealthHTMLHandler, createVoiceProviderHealthJSONHandler, createVoiceProviderHealthRoutes, renderVoiceProviderHealthHTML, summarizeVoiceProviderHealth } from './providerHealth';
 export { createVoiceProviderCapabilityHTMLHandler, createVoiceProviderCapabilityJSONHandler, createVoiceProviderCapabilityRoutes, renderVoiceProviderCapabilityHTML, summarizeVoiceProviderCapabilities } from './providerCapabilities';
+export { buildVoiceProviderOrchestrationReport, createVoiceProviderOrchestrationRoutes, renderVoiceProviderOrchestrationHTML, renderVoiceProviderOrchestrationMarkdown } from './providerOrchestration';
 export { assertVoiceProviderRoutingContractEvidence, assertVoiceProviderRoutingContract, evaluateVoiceProviderRoutingContractEvidence, runVoiceProviderRoutingContract } from './providerRoutingContract';
 export { assertVoiceProviderSloEvidence, buildVoiceProviderSloReport, createVoiceProviderSloRoutes, evaluateVoiceProviderSloEvidence, renderVoiceProviderSloHTML, renderVoiceProviderSloMarkdown } from './providerSlo';
 export { createVoicePhoneAgentProductionSmokeHTMLHandler, createVoicePhoneAgentProductionSmokeJSONHandler, createVoicePhoneAgentProductionSmokeRoutes, renderVoicePhoneAgentProductionSmokeHTML, runVoicePhoneAgentProductionSmokeContract } from './phoneAgentProductionSmoke';
@@ -106,11 +107,12 @@ export type { VoiceEvalBaselineComparison, VoiceEvalBaselineComparisonOptions, V
 export type { VoiceSimulationSuiteAssertionInput, VoiceSimulationSuiteAssertionReport, VoiceSimulationSuiteEvalRoutesOptions, VoiceSimulationSuiteOptions, VoiceSimulationSuiteReport, VoiceSimulationSuiteRoutesOptions, VoiceSimulationSuiteSection, VoiceSimulationSuiteSectionSummary, VoiceSimulationSuiteStatus } from './simulationSuite';
 export type { VoiceWorkflowContract, VoiceWorkflowContractDefinition, VoiceWorkflowContractField, VoiceWorkflowContractFieldMatch, VoiceWorkflowContractPresetName, VoiceWorkflowContractPresetOptions, VoiceWorkflowContractTracePayload, VoiceWorkflowContractValidation, VoiceWorkflowContractValidationIssue, VoiceWorkflowOutcome } from './workflowContract';
 export type { VoiceSessionListHTMLHandlerOptions, VoiceSessionListItem, VoiceSessionListOptions, VoiceSessionListRoutesOptions, VoiceSessionListStatus, VoiceProviderFallbackRecoverySummary, VoiceSessionReplay, VoiceSessionReplayHTMLHandlerOptions, VoiceSessionReplayOptions, VoiceSessionReplayRoutesOptions, VoiceSessionReplayTurn } from './sessionReplay';
-export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOptions, OpenAIVoiceAssistantModelOptions, VoiceProviderRouterEvent, VoiceProviderRouterFallbackMode, VoiceProviderRouterHealthOptions, VoiceProviderRouterOptions, VoiceProviderRouterPolicy, VoiceProviderRouterPolicyPreset, VoiceProviderRouterPolicyWeights, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceProviderRouterStrategy, VoiceJSONAssistantModelHandler, VoiceJSONAssistantModelOptions } from './modelAdapters';
+export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOptions, OpenAIVoiceAssistantModelOptions, VoiceProviderRouterEvent, VoiceProviderRouterFallbackMode, VoiceProviderRouterHealthOptions, VoiceProviderRouterOptions, VoiceProviderOrchestrationProfile, VoiceProviderOrchestrationProfileOptions, VoiceProviderOrchestrationResolvedSurface, VoiceProviderOrchestrationSurface, VoiceProviderRouterPolicy, VoiceProviderRouterPolicyPreset, VoiceProviderRouterPolicyWeights, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceProviderRouterStrategy, VoiceJSONAssistantModelHandler, VoiceJSONAssistantModelOptions } from './modelAdapters';
 export type { OpenAIVoiceTTSOptions, OpenAIVoiceTTSVoice } from './openaiTTS';
 export type { OpenAIRealtimeAdapterOptions, OpenAIRealtimeModel, OpenAIRealtimeNoiseReduction, OpenAIRealtimeResponseMode, OpenAIRealtimeTranscriptionModel, OpenAIRealtimeVoice } from './openaiRealtime';
 export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProviderHealthSummaryOptions } from './providerHealth';
 export type { VoiceProviderCapabilityDefinition, VoiceProviderCapabilityHandlerOptions, VoiceProviderCapabilityHTMLHandlerOptions, VoiceProviderCapabilityKind, VoiceProviderCapabilityOptions, VoiceProviderCapabilityReport, VoiceProviderCapabilityRoutesOptions, VoiceProviderCapabilitySummary } from './providerCapabilities';
+export type { VoiceProviderOrchestrationIssue, VoiceProviderOrchestrationReport, VoiceProviderOrchestrationReportOptions, VoiceProviderOrchestrationRequirement, VoiceProviderOrchestrationRoutesOptions, VoiceProviderOrchestrationStatus, VoiceProviderOrchestrationSurfaceReport } from './providerOrchestration';
 export type { VoiceProviderRoutingContractAssertionInput, VoiceProviderRoutingContractAssertionReport, VoiceProviderRoutingContractDefinition, VoiceProviderRoutingContractIssue, VoiceProviderRoutingContractReport, VoiceProviderRoutingContractRunOptions, VoiceProviderRoutingExpectation, VoiceProviderRoutingStatus } from './providerRoutingContract';
 export type { VoiceProviderSloAssertionInput, VoiceProviderSloAssertionReport, VoiceProviderSloIssue, VoiceProviderSloKindReport, VoiceProviderSloMetric, VoiceProviderSloReport, VoiceProviderSloReportOptions, VoiceProviderSloRoutesOptions, VoiceProviderSloSessionReport, VoiceProviderSloStatus, VoiceProviderSloThresholdConfig, VoiceProviderSloThresholds } from './providerSlo';
 export type { VoiceTurnLatencyHTMLHandlerOptions, VoiceTurnLatencyItem, VoiceTurnLatencyOptions, VoiceTurnLatencyReport, VoiceTurnLatencyRoutesOptions, VoiceTurnLatencyStage, VoiceTurnLatencyStatus } from './turnLatency';