@absolutejs/voice 0.0.22-beta.103 → 0.0.22-beta.105

package/README.md

@@ -1,11 +1,48 @@
 # `@absolutejs/voice`
 
-`@absolutejs/voice` is the voice session layer for AbsoluteJS. It owns the duplex WebSocket lifecycle, transcript buffering, turn commits, reconnect behavior, and client primitives, while keeping speech vendors and session storage pluggable.
+`@absolutejs/voice` is the self-hosted voice operations layer for AbsoluteJS.
+
+It gives your app the primitives hosted voice platforms usually keep behind their dashboards: browser voice sessions, phone-call routes, provider routing, assistant tools, handoffs, traces, evals, production-readiness checks, latency proof, storage adapters, and framework-native UI helpers.
+
+Use it when you want Vapi/Retell/Bland-style voice-agent capability, but you want the orchestration, data, traces, storage, and UI to live inside the AbsoluteJS server you already operate.
+
+## Why AbsoluteJS Voice
+
+- Self-hosted by default: your app owns sessions, traces, reviews, tasks, handoffs, retention, and provider keys.
+- Provider-neutral: use Deepgram, AssemblyAI, OpenAI, Anthropic, Gemini, ElevenLabs-style TTS, or your own adapters without rewriting app workflow code.
+- Browser and phone surfaces: mount browser WebSocket voice routes plus Twilio, Telnyx, and Plivo telephony routes from the same package.
+- Production proof: App Kit, production readiness, turn quality, turn latency, live browser p50/p95 latency, trace timelines, evals, fixtures, and contracts are package primitives.
+- Framework parity: React, Vue, Svelte, Angular, HTML, HTMX, and plain client entrypoints share the same core behavior.
+- No hosted platform tax: AbsoluteJS Voice does not add a mandatory per-minute orchestration fee between your app and your providers.
+
+## Start Here
+
+Pick the path that matches what you are building:
+
+- Browser voice agent: mount `voice(...)`, choose an STT adapter, and use the React/Vue/Svelte/Angular/HTML/HTMX client helpers for mic, transcript, reconnect, and status UI.
+- Phone voice agent: mount Twilio, Telnyx, or Plivo routes, normalize carrier outcomes, inspect carrier readiness, and persist call lifecycle traces.
+- Production readiness: mount `createVoiceAppKitRoutes(...)` to get ops console/status, quality, evals, provider health, sessions, handoffs, diagnostics, and readiness gates.
+- Provider routing and fallback: use LLM/STT/TTS provider routers, provider health, provider simulation controls, and cost/latency-aware routing policies.
+- Evals and simulation: run scenario fixtures, workflow contracts, tool contracts, outcome contracts, baseline comparisons, and saved benchmark artifacts before live traffic.
+
+## How This Differs From Hosted Voice Platforms
+
+Hosted voice-agent platforms are strongest when you want a managed dashboard, phone-number provisioning, hosted orchestration, and campaign tooling out of the box.
+
+AbsoluteJS Voice is strongest when voice is part of your own product and you need code-owned primitives:
+
+- Your app stores the call data instead of a vendor dashboard being the source of truth.
+- Your app controls provider routing, fallback, retries, handoffs, and retention.
+- Your team can inspect and extend every primitive.
+- Your framework UI can render first-class voice state without iframe/dashboard handoffs.
+- Your production checks and evals can run in CI, smoke tests, or your own admin UI.
+
+The goal is not to clone a hosted platform. The goal is to make AbsoluteJS the best place to build and operate self-hosted voice products.
 
 ## Install
 
 ```bash
-bun add @absolutejs/voice
+bun add @absolutejs/voice @absolutejs/voice-deepgram
 ```
 
 Peer dependencies:
@@ -21,7 +58,12 @@ Optional framework entrypoints:
 - `@absolutejs/voice/angular`
 - `@absolutejs/voice/client`
 
-## Route Setup
+Common optional adapters:
+
+- `@absolutejs/voice-deepgram`
+- `@absolutejs/voice-assemblyai`
+
+## Browser Voice Agent
 
 ```ts
 import { Elysia } from 'elysia';
@@ -73,6 +115,132 @@ const app = new Elysia()
 
 `createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
 
+## Production Readiness Path
+
+Once the basic route works, mount the App Kit. This gives you the self-hosted operational surface that hosted platforms usually make mandatory:
+
+```ts
+import {
+	createVoiceAppKitRoutes,
+	createVoiceFileRuntimeStorage,
+	createVoiceLiveLatencyRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceTraceTimelineRoutes,
+	createVoiceTurnLatencyRoutes,
+	createVoiceTurnQualityRoutes
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+app
+	.use(
+		createVoiceAppKitRoutes({
+			store: runtime.traces,
+			llmProviders: ['openai', 'anthropic', 'gemini'],
+			sttProviders: ['deepgram', 'assemblyai']
+		}).routes
+	)
+	.use(
+		createVoiceTurnLatencyRoutes({
+			htmlPath: '/turn-latency',
+			path: '/api/turn-latency',
+			store: runtime.session,
+			traceStore: runtime.traces
+		})
+	)
+	.use(
+		createVoiceLiveLatencyRoutes({
+			htmlPath: '/live-latency',
+			path: '/api/live-latency',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceTurnQualityRoutes({
+			htmlPath: '/turn-quality',
+			path: '/api/turn-quality',
+			store: runtime.session
+		})
+	)
+	.use(
+		createVoiceTraceTimelineRoutes({
+			htmlPath: '/traces',
+			path: '/api/voice-traces',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			htmlPath: '/production-readiness',
+			path: '/api/production-readiness',
+			store: runtime.traces
+		})
+	);
+```
+
+Recommended proof routes:
+
+- `/app-kit/status`: compact customer-facing app status.
+- `/production-readiness`: production gate summary.
+- `/traces`: per-session trace timelines.
+- `/turn-latency`: server-side turn-stage latency.
+- `/live-latency`: browser-measured speech-to-assistant p50/p95 latency.
+- `/turn-quality`: STT confidence, correction, fallback, and transcript diagnostics.
+
+## Phone Voice Agent Path
+
+Use the telephony primitives when the agent needs to answer or place calls through your own carrier account:
+
+```ts
+import {
+	createVoicePhoneAgent,
+	createVoiceTelephonyOutcomePolicy
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const outcomePolicy = createVoiceTelephonyOutcomePolicy({
+	transferTarget: '+15551234567'
+});
+
+app
+	.use(
+		createVoicePhoneAgent({
+			matrix: {
+				path: '/api/carriers',
+				title: 'AbsoluteJS Voice Carrier Matrix'
+			},
+			carriers: [
+				{
+					provider: 'twilio',
+					options: {
+						context: {},
+						outcomePolicy,
+						session: runtime.session,
+						stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+						streamPath: '/api/voice/twilio/stream',
+						twiml: {
+							path: '/api/voice/twilio',
+							streamUrl: process.env.TWILIO_STREAM_URL
+						},
+						webhook: {
+							path: '/api/voice/twilio/webhook',
+							signingSecret: process.env.TWILIO_AUTH_TOKEN
+						},
+						async onTurn({ turn }) {
+							return { assistantText: `I heard: ${turn.text}` };
+						},
+						onComplete: async () => {}
+					}
+				}
+			]
+		}).routes
+	);
+```
+
+The wrapper mounts selected carrier routes and a readiness matrix. Telnyx and Plivo use the same wrapper with `{ provider: 'telnyx', options: ... }` or `{ provider: 'plivo', options: ... }`. The lower-level `createTwilioVoiceRoutes(...)`, `createTelnyxVoiceRoutes(...)`, and `createPlivoVoiceRoutes(...)` helpers remain available when you need carrier-specific control.
+
 ## App Kit And Status Widgets
 
 Use `createVoiceAppKitRoutes(...)` when you want a self-hosted operations surface without hand-wiring every dashboard route. It adds the ops console, quality gates, eval routes, provider health, session replay, handoff health, diagnostics, and `GET /app-kit/status`.

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export { createVoiceLiveLatencyRoutes, renderVoiceLiveLatencyHTML, summarizeVoic
 export { createVoiceTurnQualityHTMLHandler, createVoiceTurnQualityJSONHandler, createVoiceTurnQualityRoutes, renderVoiceTurnQualityHTML, summarizeVoiceTurnQuality } from './turnQuality';
 export { createVoiceOutcomeContractHTMLHandler, createVoiceOutcomeContractJSONHandler, createVoiceOutcomeContractRoutes, renderVoiceOutcomeContractHTML, runVoiceOutcomeContractSuite } from './outcomeContract';
 export { applyVoiceTelephonyOutcome, createMemoryVoiceTelephonyWebhookIdempotencyStore, createVoiceTelephonyOutcomePolicy, createVoiceTelephonyWebhookHandler, createVoiceTelephonyWebhookRoutes, parseVoiceTelephonyWebhookEvent, resolveVoiceTelephonyOutcome, signVoiceTwilioWebhook, verifyVoiceTwilioWebhookSignature, voiceTelephonyOutcomeToRouteResult } from './telephonyOutcome';
+export { createVoicePhoneAgent } from './phoneAgent';
 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, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter } from './modelAdapters';
@@ -68,6 +69,7 @@ export type { VoiceLiveLatencyOptions, VoiceLiveLatencyReport, VoiceLiveLatencyR
 export type { VoiceTurnQualityHTMLHandlerOptions, VoiceTurnQualityItem, VoiceTurnQualityOptions, VoiceTurnQualityReport, VoiceTurnQualityRoutesOptions, VoiceTurnQualityStatus } from './turnQuality';
 export type { VoiceOutcomeContractDefinition, VoiceOutcomeContractHTMLHandlerOptions, VoiceOutcomeContractIssue, VoiceOutcomeContractOptions, VoiceOutcomeContractReport, VoiceOutcomeContractRoutesOptions, VoiceOutcomeContractStatus, VoiceOutcomeContractSuiteReport } from './outcomeContract';
 export type { VoiceTelephonyOutcomeAction, VoiceTelephonyOutcomeDecision, VoiceTelephonyOutcomePolicy, VoiceTelephonyOutcomeProviderEvent, VoiceTelephonyOutcomeRouteResult, VoiceTelephonyOutcomeStatusDecision, VoiceTelephonyWebhookDecision, VoiceTelephonyWebhookHandlerOptions, VoiceTelephonyWebhookIdempotencyStore, VoiceTelephonyWebhookParseInput, VoiceTelephonyWebhookProvider, VoiceTelephonyWebhookRoutesOptions, VoiceTelephonyWebhookVerificationResult, StoredVoiceTelephonyWebhookDecision } from './telephonyOutcome';
+export type { VoicePhoneAgentCarrier, VoicePhoneAgentPlivoCarrier, VoicePhoneAgentRoutes, VoicePhoneAgentRoutesOptions, VoicePhoneAgentTelnyxCarrier, VoicePhoneAgentTwilioCarrier } from './phoneAgent';
 export type { VoiceOpsConsoleLink, VoiceOpsConsoleReport, VoiceOpsConsoleRoutesOptions } from './opsConsoleRoutes';
 export type { VoiceProductionReadinessAction, VoiceProductionReadinessCheck, VoiceProductionReadinessReport, VoiceProductionReadinessRoutesOptions, VoiceProductionReadinessStatus } from './productionReadiness';
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';