@absolutejs/voice 0.0.22-beta.1 → 0.0.22-beta.100

package/README.md

@@ -73,6 +73,197 @@ const app = new Elysia()
 
 `createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
 
+## 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`.
+
+```ts
+import { createVoiceAppKitRoutes, createVoiceFileRuntimeStorage } from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({ directory: '.voice-runtime/support' });
+
+app.use(
+	createVoiceAppKitRoutes({
+		store: runtime.traces,
+		llmProviders: ['openai', 'anthropic', 'gemini'],
+		sttProviders: ['deepgram', 'assemblyai']
+	}).routes
+);
+```
+
+The status endpoint is intentionally small enough for customer-facing demos. It can report fixture-backed workflow readiness while leaving deeper live quality/session failures visible on the ops pages.
+
+```ts
+app.use(
+	createVoiceAppKitRoutes({
+		appStatus: {
+			include: { quality: false, sessions: false },
+			preferFixtureWorkflows: true
+		},
+		evals: { fixtures: certificationFixtures, scenarios: workflowScenarios },
+		store: runtime.traces
+	}).routes
+);
+```
+
+### React Status Widget
+
+```tsx
+import { VoiceOpsStatus } from '@absolutejs/voice/react';
+
+export function OpsBadge() {
+	return <VoiceOpsStatus intervalMs={5000} />;
+}
+```
+
+### Vue Status Widget
+
+```vue
+<script setup lang="ts">
+import { VoiceOpsStatus } from '@absolutejs/voice/vue';
+</script>
+
+<template>
+	<VoiceOpsStatus :interval-ms="5000" />
+</template>
+```
+
+### Svelte Status Widget
+
+```svelte
+<script lang="ts">
+	import { onDestroy, onMount } from 'svelte';
+	import { createVoiceOpsStatus } from '@absolutejs/voice/svelte';
+
+	const status = createVoiceOpsStatus('/app-kit/status', { intervalMs: 5000 });
+	let html = '';
+	onMount(() => status.subscribe(() => (html = status.getHTML())));
+	onDestroy(() => status.close());
+</script>
+
+{@html html}
+```
+
+### Angular Status Widget
+
+```ts
+import { VoiceAppKitStatusService } from '@absolutejs/voice/angular';
+
+status = inject(VoiceAppKitStatusService).connect('/app-kit/status', {
+	intervalMs: 5000
+});
+```
+
+```html
+<h2>{{ status.report()?.status === 'pass' ? 'Passing' : 'Needs attention' }}</h2>
+<p>{{ status.report()?.passed ?? 0 }} passing checks</p>
+```
+
+### HTML Or HTMX Status Widget
+
+```html
+<div id="voice-ops-status"></div>
+<script type="module">
+	import { mountVoiceOpsStatus } from '@absolutejs/voice/client';
+
+	mountVoiceOpsStatus(document.querySelector('#voice-ops-status'), '/app-kit/status', {
+		intervalMs: 5000
+	});
+</script>
+```
+
+For custom elements:
+
+```html
+<absolute-voice-ops-status interval-ms="5000"></absolute-voice-ops-status>
+<script type="module">
+	import { defineVoiceOpsStatusElement } from '@absolutejs/voice/client';
+	defineVoiceOpsStatusElement();
+</script>
+```
+
+## Voice Assistants
+
+Use `createVoiceAssistant(...)` when you want one product-level surface for a voice agent instead of wiring tools, guardrails, experiments, traces, and ops recipes separately. It returns a standard `onTurn` handler, plus an `ops` object you can pass to `voice(...)`.
+
+```ts
+import {
+	createVoiceAssistant,
+	createVoiceExperiment,
+	createVoiceFileRuntimeStorage,
+	createVoiceMemoryStore,
+	createVoiceAgentTool,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtimeStorage = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+const lookupOrder = createVoiceAgentTool({
+	name: 'lookup_order',
+	description: 'Look up an order by id.',
+	execute: async ({ args }) => ({ orderId: args.orderId, status: 'shipped' })
+});
+
+const assistant = createVoiceAssistant({
+	id: 'support',
+	artifactPlan: {
+		ops: {
+			events: runtimeStorage.events,
+			reviews: runtimeStorage.reviews,
+			tasks: runtimeStorage.tasks
+		},
+		preset: {
+			name: 'support-triage',
+			options: {
+				queue: 'support-triage'
+			}
+		}
+	},
+	experiment: createVoiceExperiment({
+		id: 'support-prompt',
+		variants: [
+			{ id: 'baseline', weight: 1 },
+			{
+				id: 'direct',
+				weight: 1,
+				system: 'You are concise, practical, and resolve the caller quickly.'
+			}
+		]
+	}),
+	guardrails: {
+		beforeTurn: ({ turn }) =>
+			turn.text.toLowerCase().includes('human')
+				? { escalate: { reason: 'caller requested a human' } }
+				: undefined
+	},
+	model: {
+		async generate({ messages, tools }) {
+			return {
+				assistantText: `I can help. Available tools: ${tools.map((tool) => tool.name).join(', ')}`
+			};
+		}
+	},
+	system: 'You are a support voice assistant.',
+	tools: [lookupOrder],
+	trace: runtimeStorage.traces
+});
+
+voice({
+	path: '/voice',
+	session: createVoiceMemoryStore(),
+	stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+	trace: runtimeStorage.traces,
+	ops: assistant.ops,
+	onTurn: assistant.onTurn,
+	onComplete: async () => {}
+});
+```
+
+Assistant experiments are deterministic by session id, so a caller stays on the same variant for a call. Variants can change the model, system prompt, tools, and tool-round budget; guardrails can block a turn before model execution or rewrite the returned `VoiceRouteResult`.
+
 ## Agent Tools And Squads
 
 For assistant-style products, use `createVoiceAgent(...)` as the `onTurn` handler. The agent layer is provider-neutral: plug in any model adapter, register server-side tools, and return normal voice route results like `assistantText`, `transfer`, `escalate`, or `complete`.
@@ -987,6 +1178,102 @@ 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 }
+	}
+});
+```
+
+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/agent.d.ts

@@ -1,5 +1,6 @@
 import type { VoiceOnTurnObjectHandler, VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord, VoiceTurnRecord } from './types';
 import type { VoiceTraceEventStore } from './trace';
+import type { VoiceToolRuntime } from './toolRuntime';
 export type VoiceAgentMessageRole = 'assistant' | 'system' | 'tool' | 'user';
 export type VoiceAgentMessage = {
     content: string;
@@ -86,6 +87,7 @@ export type VoiceAgentOptions<TContext = unknown, TSession extends VoiceSessionR
         turn: VoiceTurnRecord;
     }) => Promise<string | undefined> | string | undefined);
     trace?: VoiceTraceEventStore;
+    toolRuntime?: VoiceToolRuntime<TContext, TSession, TResult>;
     tools?: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
 };
 export type VoiceAgentSquadOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {

package/dist/angular/index.d.ts

@@ -1,2 +1,10 @@
+export { VoiceAppKitStatusService } from './voice-app-kit-status.service';
 export { VoiceStreamService } from './voice-stream.service';
 export { VoiceControllerService } from './voice-controller.service';
+export { VoiceProviderCapabilitiesService } from './voice-provider-capabilities.service';
+export { VoiceProviderStatusService } from './voice-provider-status.service';
+export { VoiceRoutingStatusService } from './voice-routing-status.service';
+export { VoiceTraceTimelineService } from './voice-trace-timeline.service';
+export { VoiceTurnLatencyService } from './voice-turn-latency.service';
+export { VoiceTurnQualityService } from './voice-turn-quality.service';
+export { VoiceWorkflowStatusService } from './voice-workflow-status.service';