@absolutejs/voice 0.0.22-beta.209 → 0.0.22-beta.210

package/README.md

@@ -249,6 +249,236 @@ The demo UI should show a mic button, transcript, current specialist badge, read
 
 This recipe covers the hosted-platform expectations that matter for support triage: assistant entrypoint, business tools, specialist handoff, post-call task creation, simulation proof, tool contract proof, production readiness, audit-compatible runtime storage, and a call-log replacement at `/voice-operations/:sessionId`.
 
+## Use-Case Recipe: Appointment Scheduling
+
+Use this path when the assistant needs to check availability, book a slot, create a confirmation task, and prove the post-call workflow before production traffic. This is the self-hosted version of a hosted scheduling agent: your app owns the calendar tool, booking policy, storage, follow-up tasks, and call evidence.
+
+The production shape is:
+
+1. Persist sessions, traces, reviews, tasks, integration events, and audit events in app-owned runtime storage.
+2. Define `check_availability` and `book_appointment` as server-side tools with deterministic tool contracts.
+3. Use `resolveVoiceOutcomeRecipe('appointment-booking')` so completed calls create appointment-confirmation work.
+4. Add an outcome contract that requires a completed session, review, task, and integration events.
+5. Mount simulation, outcome-contract, readiness, and operations-record routes so scheduling regressions fail before live calls.
+
+```ts
+import { Elysia } from 'elysia';
+import {
+	createVoiceAgent,
+	createVoiceAgentTool,
+	createVoiceFileRuntimeStorage,
+	createVoiceOperationsRecordRoutes,
+	createVoiceOutcomeContractRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceSimulationSuiteRoutes,
+	createVoiceToolContractRoutes,
+	createVoiceToolRuntimeContractDefaults,
+	resolveVoiceOutcomeRecipe,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/appointments'
+});
+
+const checkAvailability = createVoiceAgentTool({
+	name: 'check_availability',
+	description: 'Return open appointment slots for a service and date.',
+	parameters: {
+		type: 'object',
+		properties: {
+			date: { type: 'string' },
+			service: { type: 'string' }
+		},
+		required: ['date', 'service']
+	},
+	execute: async ({ args }) => ({
+		date: args.date,
+		service: args.service,
+		slots: ['2026-05-04T15:00:00-04:00', '2026-05-04T16:30:00-04:00']
+	})
+});
+
+const bookAppointment = createVoiceAgentTool({
+	name: 'book_appointment',
+	description: 'Book a confirmed appointment slot.',
+	parameters: {
+		type: 'object',
+		properties: {
+			customerName: { type: 'string' },
+			phone: { type: 'string' },
+			service: { type: 'string' },
+			startsAt: { type: 'string' }
+		},
+		required: ['customerName', 'phone', 'service', 'startsAt']
+	},
+	execute: async ({ args }) => ({
+		appointmentId: `appt_${args.startsAt}`,
+		customerName: args.customerName,
+		phone: args.phone,
+		service: args.service,
+		startsAt: args.startsAt,
+		status: 'confirmed'
+	})
+});
+
+const scheduler = createVoiceAgent({
+	id: 'scheduler',
+	system: 'Collect caller details, check availability, book an appointment, and summarize the confirmation.',
+	tools: [checkAvailability, bookAppointment],
+	trace: runtime.traces,
+	model: {
+		async generate({ tools }) {
+			return {
+				assistantText: `I can check times and book the appointment. Available tools: ${tools.map((tool) => tool.name).join(', ')}`
+			};
+		}
+	}
+});
+
+const toolContractDefinitions = [
+	{
+		id: 'check-availability-contract',
+		label: 'Availability returns bookable slots',
+		tool: checkAvailability,
+		cases: [
+			{
+				id: 'consultation-slots',
+				args: { date: '2026-05-04', service: 'consultation' },
+				expect: { expectStatus: 'ok' }
+			}
+		],
+		defaultRuntime: createVoiceToolRuntimeContractDefaults()
+	},
+	{
+		id: 'book-appointment-contract',
+		label: 'Booking returns a confirmed appointment',
+		tool: bookAppointment,
+		cases: [
+			{
+				id: 'confirmed-consultation',
+				args: {
+					customerName: 'Ada Lovelace',
+					phone: '+15551234567',
+					service: 'consultation',
+					startsAt: '2026-05-04T15:00:00-04:00'
+				},
+				expect: {
+					expectedResult: {
+						appointmentId: 'appt_2026-05-04T15:00:00-04:00',
+						customerName: 'Ada Lovelace',
+						phone: '+15551234567',
+						service: 'consultation',
+						startsAt: '2026-05-04T15:00:00-04:00',
+						status: 'confirmed'
+					},
+					expectStatus: 'ok'
+				}
+			}
+		],
+		defaultRuntime: createVoiceToolRuntimeContractDefaults()
+	}
+];
+
+const outcomeContractDefinitions = [
+	{
+		id: 'appointment-booked',
+		label: 'Completed appointment call produces follow-up work',
+		expectedDisposition: 'completed',
+		minSessions: 1,
+		minTasks: 1,
+		requireIntegrationEvents: ['call.completed', 'review.saved', 'task.created'],
+		requireReview: true,
+		requireTask: true
+	}
+];
+
+const app = new Elysia()
+	.use(
+		voice({
+			path: '/voice/appointments',
+			preset: 'reliability',
+			session: runtime.session,
+			stt: deepgram({
+				apiKey: process.env.DEEPGRAM_API_KEY!,
+				model: 'flux-general-en'
+			}),
+			trace: runtime.traces,
+			onTurn: scheduler.onTurn,
+			onComplete: async () => {},
+			ops: {
+				...resolveVoiceOutcomeRecipe('appointment-booking', {
+					assignee: 'scheduling-oncall',
+					queue: 'appointments'
+				}),
+				events: runtime.events,
+				reviews: runtime.reviews,
+				tasks: runtime.tasks
+			}
+		})
+	)
+	.use(
+		createVoiceToolContractRoutes({
+			contracts: toolContractDefinitions,
+			htmlPath: '/voice/appointments/tool-contracts',
+			path: '/api/voice/appointments/tool-contracts'
+		})
+	)
+	.use(
+		createVoiceOutcomeContractRoutes({
+			contracts: outcomeContractDefinitions,
+			events: runtime.events,
+			htmlPath: '/voice/appointments/outcome-contracts',
+			operationsRecordHref: '/voice-operations/:sessionId',
+			path: '/api/voice/appointments/outcome-contracts',
+			reviews: runtime.reviews,
+			sessions: runtime.session,
+			tasks: runtime.tasks
+		})
+	)
+	.use(
+		createVoiceSimulationSuiteRoutes({
+			htmlPath: '/voice/appointments/simulations',
+			operationsRecordHref: '/voice-operations/:sessionId',
+			outcomes: {
+				contracts: outcomeContractDefinitions,
+				events: runtime.events,
+				reviews: runtime.reviews,
+				sessions: runtime.session,
+				tasks: runtime.tasks
+			},
+			path: '/api/voice/appointments/simulations',
+			tools: toolContractDefinitions
+		})
+	)
+	.use(
+		createVoiceOperationsRecordRoutes({
+			htmlPath: '/voice-operations/:sessionId',
+			integrationEvents: runtime.events,
+			path: '/api/voice-operations/:sessionId',
+			reviews: runtime.reviews,
+			store: runtime.traces,
+			tasks: runtime.tasks
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			htmlPath: '/production-readiness',
+			links: {
+				operationsRecords: '/voice-operations/:sessionId',
+				simulations: '/voice/appointments/simulations'
+			},
+			path: '/api/production-readiness',
+			store: runtime.traces
+		})
+	);
+```
+
+The UI should keep the scheduling flow simple: microphone, transcript, selected slot, booking status, confirmation task link, `/voice/appointments/simulations`, `/voice/appointments/outcome-contracts`, `/production-readiness`, and `/voice-operations/:sessionId`. If the booking or confirmation proof fails, the operator should start at the outcome contract and follow the linked operations record.
+
+This recipe covers the hosted-platform expectations that matter for appointment scheduling: scheduling tools, deterministic tool proof, post-call confirmation work, outcome validation, simulation proof, production readiness, and one call-log replacement for debugging.
+
 ## 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.

package/package.json

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