@absolutejs/voice 0.0.21 → 0.0.22-beta.0

package/dist/testing/review.d.ts

@@ -0,0 +1,143 @@
+import type { VoiceCallDisposition, VoiceServerMessage } from '../types';
+type ReviewTimelineSource = 'benchmark' | 'stt' | 'turn' | 'twilio';
+export type VoiceCallReviewTimelineEvent = {
+    atMs: number;
+    event: string;
+    source: ReviewTimelineSource;
+    bytes?: number;
+    chunkDurationMs?: number;
+    chunkIndex?: number;
+    confidence?: number;
+    name?: string;
+    reason?: string;
+    text?: string;
+    track?: string;
+};
+export type VoiceCallReviewConfig = {
+    preset?: string;
+    stt?: Record<string, unknown>;
+    tts?: Record<string, unknown>;
+    turnDetection?: Record<string, unknown>;
+};
+export type VoiceCallReviewPostCallSummary = {
+    label: string;
+    recommendedAction: string;
+    reason?: string;
+    summary: string;
+    target?: string;
+};
+export type VoiceCallReviewSummary = {
+    clearLatencyMs?: number;
+    elapsedMs?: number;
+    firstOutboundMediaLatencyMs?: number;
+    firstTurnLatencyMs?: number;
+    markLatencyMs?: number;
+    outcome?: VoiceCallDisposition;
+    outboundMediaCount?: number;
+    pass: boolean;
+    termRecall?: number;
+    turnCount?: number;
+    wordErrorRate?: number;
+};
+export type VoiceCallReviewArtifact = {
+    id?: string;
+    config?: VoiceCallReviewConfig;
+    errors: string[];
+    expectedText?: string;
+    fixtureId?: string;
+    generatedAt?: number;
+    latencyBreakdown: Array<{
+        label: string;
+        valueMs: number;
+    }>;
+    notes: string[];
+    path?: string;
+    postCall?: VoiceCallReviewPostCallSummary;
+    summary: VoiceCallReviewSummary;
+    title: string;
+    timeline: VoiceCallReviewTimelineEvent[];
+    transcript: {
+        actual: string;
+        expected?: string;
+    };
+};
+export type StoredVoiceCallReviewArtifact = VoiceCallReviewArtifact & {
+    id: string;
+};
+export type VoiceCallReviewStore<TArtifact extends StoredVoiceCallReviewArtifact = StoredVoiceCallReviewArtifact> = {
+    get: (id: string) => Promise<TArtifact | undefined> | TArtifact | undefined;
+    list: () => Promise<TArtifact[]> | TArtifact[];
+    remove: (id: string) => Promise<void> | void;
+    set: (id: string, artifact: TArtifact) => Promise<void> | void;
+};
+type LiveTelephonyFixture = {
+    actualText: string;
+    clearLatencyMs?: number;
+    elapsedMs?: number;
+    errors?: string[];
+    expectedText?: string;
+    fixtureId?: string;
+    firstOutboundMediaLatencyMs?: number;
+    firstTurnLatencyMs?: number;
+    markLatencyMs?: number;
+    outboundMediaCount?: number;
+    passes: boolean;
+    termRecall?: number;
+    title?: string;
+    turnCount?: number;
+    wordErrorRate?: number;
+};
+type LiveTelephonyTraceEvent = VoiceCallReviewTimelineEvent;
+type LiveTelephonyReviewInput = {
+    fixtures?: LiveTelephonyFixture[];
+    generatedAt?: number;
+    trace?: LiveTelephonyTraceEvent[];
+    ttsConfig?: Record<string, unknown>;
+    turnDetectionConfig?: Record<string, unknown>;
+    variant?: {
+        description?: string;
+        id?: string;
+        model?: string;
+    };
+};
+export type VoiceCallReviewRecorderOptions = {
+    config?: VoiceCallReviewConfig;
+    fixtureId?: string;
+    now?: () => number;
+    path?: string;
+    title?: string;
+};
+export type VoiceCallReviewRecorder = {
+    finalize: () => VoiceCallReviewArtifact;
+    recordError: (error: unknown) => void;
+    recordTwilioInbound: (input: {
+        bytes?: number;
+        chunkDurationMs?: number;
+        event: 'connected' | 'mark' | 'media' | 'start' | 'stop';
+        name?: string;
+        reason?: string;
+        text?: string;
+        track?: string;
+    }) => void;
+    recordTwilioOutbound: (input: {
+        bytes?: number;
+        chunkDurationMs?: number;
+        event: 'clear' | 'mark' | 'media';
+        name?: string;
+        reason?: string;
+        text?: string;
+        track?: string;
+    }) => void;
+    recordVoiceMessage: (message: VoiceServerMessage) => void;
+};
+export declare const withVoiceCallReviewId: <TArtifact extends VoiceCallReviewArtifact = VoiceCallReviewArtifact>(id: string, artifact: TArtifact) => TArtifact & {
+    id: string;
+};
+export declare const createVoiceCallReviewFromLiveTelephonyReport: (report: LiveTelephonyReviewInput, options?: {
+    path?: string;
+    preset?: string;
+}) => VoiceCallReviewArtifact;
+export declare const createVoiceCallReviewRecorder: (options?: VoiceCallReviewRecorderOptions) => VoiceCallReviewRecorder;
+export declare const renderVoiceCallReviewMarkdown: (artifact: VoiceCallReviewArtifact) => string;
+export declare const renderVoiceCallReviewHTML: (artifact: VoiceCallReviewArtifact) => string;
+export {};

package/dist/testing/sessionBenchmark.d.ts

@@ -5,7 +5,9 @@ export type VoiceSessionBenchmarkScenario = VoiceTestFixture & {
     expectedTurnTexts: string[];
     phraseHints?: VoicePhraseHint[];
     reconnectAtChunkIndex?: number;
+    reconnectAtChunkIndices?: number[];
     reconnectPauseMs?: number;
+    reconnectPauseMsByIndex?: number[];
     silenceMs?: number;
     speechThreshold?: number;
     transcriptStabilityMs?: number;
@@ -29,14 +31,20 @@ export type VoiceSessionBenchmarkTurnResult = {
 };
 export type VoiceSessionBenchmarkScenarioResult = {
     actualTurns: string[];
+    averageRelativeCostUnits: number;
     duplicateTurnCount: number;
     elapsedMs: number;
+    fallbackReplayAudioMs: number;
+    expectedReconnectCount: number;
     expectedTurns: string[];
     fixtureId: string;
+    primaryAudioMs: number;
     passes: boolean;
+    reconnectCount: number;
     reconnectTriggered: boolean;
     tags: string[];
     title: string;
+    turnPassRate: number;
     turnCountDelta: number;
     turnResults: VoiceSessionBenchmarkTurnResult[];
     trace?: VoiceSessionBenchmarkTraceEntry[];
@@ -44,10 +52,16 @@ export type VoiceSessionBenchmarkScenarioResult = {
 export type VoiceSessionBenchmarkSummary = {
     adapterId: string;
     averageElapsedMs: number;
+    averageFallbackReplayAudioMs: number;
+    averagePrimaryAudioMs: number;
+    averageReconnectCount: number;
+    averageRelativeCostUnits: number;
+    averageTurnPassRate: number;
     averageWordErrorRate: number;
     duplicateTurnRate: number;
     passCount: number;
     passRate: number;
+    reconnectCoverageRate: number;
     reconnectSuccessRate: number;
     scenarioCount: number;
     scenariosWithDuplicateTurns: number;
@@ -61,6 +75,11 @@ export type VoiceSessionBenchmarkReport = {
 };
 export type VoiceSessionBenchmarkScenarioAggregate = {
     averageElapsedMs: number;
+    averageFallbackReplayAudioMs: number;
+    averagePrimaryAudioMs: number;
+    averageReconnectCount: number;
+    averageRelativeCostUnits: number;
+    averageTurnPassRate: number;
     averageWordErrorRate: number;
     bestWordErrorRate: number;
     fixtureId: string;
@@ -75,10 +94,16 @@ export type VoiceSessionBenchmarkScenarioAggregate = {
 export type VoiceSessionBenchmarkSeriesSummary = {
     adapterId: string;
     averageElapsedMs: number;
+    averageFallbackReplayAudioMs: number;
     averagePassRate: number;
+    averagePrimaryAudioMs: number;
+    averageReconnectCount: number;
+    averageRelativeCostUnits: number;
+    averageTurnPassRate: number;
     averageWordErrorRate: number;
     flakyScenarioCount: number;
     generatedRunCount: number;
+    reconnectCoverageRate: number;
     reconnectSuccessRate: number;
     scenarioCount: number;
     stableScenarioCount: number;

package/dist/testing/stt.d.ts

@@ -1,9 +1,10 @@
 import { type VoiceTranscriptAccuracy } from './accuracy';
-import type { STTAdapter, VoiceCloseEvent, VoiceEndOfTurnEvent, VoiceErrorEvent, VoiceFinalEvent, VoicePartialEvent } from '../types';
+import type { STTAdapter, STTAdapterOpenOptions, VoiceCloseEvent, VoiceEndOfTurnEvent, VoiceErrorEvent, VoiceFinalEvent, VoicePartialEvent } from '../types';
 import type { VoiceTestFixture } from './fixtures';
 export type VoiceSTTAdapterHarnessOptions = {
     chunkDurationMs?: number;
     idleTimeoutMs?: number;
+    openOptions?: Partial<STTAdapterOpenOptions> | ((fixture: VoiceTestFixture) => Partial<STTAdapterOpenOptions> | undefined);
     settleMs?: number;
     tailPaddingMs?: number;
     transcriptThreshold?: number;

package/dist/testing/telephony.d.ts

@@ -0,0 +1,70 @@
+export type VoiceTelephonyBenchmarkScenario = {
+    expectClear: boolean;
+    expectMark: boolean;
+    expectOutboundMedia: boolean;
+    id: string;
+    secondInboundDelayMs?: number;
+    sttDelayMs?: number;
+    title: string;
+    ttsChunkCount?: number;
+    ttsChunkDelayMs?: number;
+};
+export type VoiceTelephonyBenchmarkScenarioResult = {
+    clearCount: number;
+    clearLatencyMs?: number;
+    elapsedMs: number;
+    expectClear: boolean;
+    expectMark: boolean;
+    expectOutboundMedia: boolean;
+    fixtureId: string;
+    firstOutboundMediaLatencyMs?: number;
+    markCount: number;
+    markLatencyMs?: number;
+    outboundMediaCount: number;
+    passes: boolean;
+    receivedAudioBytes: number;
+    title: string;
+};
+export type VoiceTelephonyBenchmarkSummary = {
+    averageClearLatencyMs?: number;
+    averageElapsedMs: number;
+    averageFirstOutboundMediaLatencyMs?: number;
+    averageMarkLatencyMs?: number;
+    passCount: number;
+    passRate: number;
+    scenarioCount: number;
+    totalOutboundMediaCount: number;
+};
+export type VoiceTelephonyBenchmarkReport = {
+    fixtures: VoiceTelephonyBenchmarkScenarioResult[];
+    generatedAt: number;
+    summary: VoiceTelephonyBenchmarkSummary;
+};
+type VoiceTelephonyBenchmarkOptions = {
+    timeoutMs?: number;
+};
+export declare const getDefaultVoiceTelephonyBenchmarkScenarios: () => {
+    expectClear: boolean;
+    expectMark: boolean;
+    expectOutboundMedia: boolean;
+    id: string;
+    secondInboundDelayMs?: number;
+    sttDelayMs?: number;
+    title: string;
+    ttsChunkCount?: number;
+    ttsChunkDelayMs?: number;
+}[];
+export declare const runVoiceTelephonyBenchmarkScenario: (scenario: VoiceTelephonyBenchmarkScenario, options?: VoiceTelephonyBenchmarkOptions) => Promise<VoiceTelephonyBenchmarkScenarioResult>;
+export declare const summarizeVoiceTelephonyBenchmark: (fixtures: VoiceTelephonyBenchmarkScenarioResult[]) => VoiceTelephonyBenchmarkSummary;
+export declare const runVoiceTelephonyBenchmark: (scenarios?: {
+    expectClear: boolean;
+    expectMark: boolean;
+    expectOutboundMedia: boolean;
+    id: string;
+    secondInboundDelayMs?: number;
+    sttDelayMs?: number;
+    title: string;
+    ttsChunkCount?: number;
+    ttsChunkDelayMs?: number;
+}[], options?: VoiceTelephonyBenchmarkOptions) => Promise<VoiceTelephonyBenchmarkReport>;
+export {};

package/dist/testing/tts.d.ts

@@ -0,0 +1,73 @@
+import type { AudioFormat, RealtimeAdapter, RealtimeAdapterOpenOptions, TTSAdapter, TTSAdapterOpenOptions } from '../types';
+export type VoiceTTSBenchmarkFixture = {
+    id: string;
+    tags?: string[];
+    text: string;
+    title: string;
+};
+export type VoiceTTSBenchmarkFixtureResult = {
+    audioChunkCount: number;
+    audioDurationMs: number;
+    audioFormat?: AudioFormat;
+    closeCount: number;
+    elapsedMs: number;
+    errorCount: number;
+    fixtureId: string;
+    firstAudioLatencyMs?: number;
+    interruptionLatencyMs?: number;
+    interruptionRequestedAtMs?: number;
+    passes: boolean;
+    postInterruptAudioBytes?: number;
+    preInterruptAudioBytes?: number;
+    tags: string[];
+    textLength: number;
+    title: string;
+    totalAudioBytes: number;
+};
+export type VoiceTTSBenchmarkSummary = {
+    adapterId: string;
+    averageAudioChunkCount: number;
+    averageAudioDurationMs: number;
+    averageElapsedMs: number;
+    averageFirstAudioLatencyMs?: number;
+    averageInterruptionLatencyMs?: number;
+    averageTextLength: number;
+    fixtureCount: number;
+    passCount: number;
+    passRate: number;
+    totalAudioBytes: number;
+    totalErrorCount: number;
+};
+export type VoiceTTSBenchmarkReport = {
+    adapterId: string;
+    fixtures: VoiceTTSBenchmarkFixtureResult[];
+    generatedAt: number;
+    profileId?: string;
+    summary: VoiceTTSBenchmarkSummary;
+};
+export type VoiceTTSBenchmarkOptions = {
+    idleTimeoutMs?: number;
+    interruptAfterFirstAudioMs?: number;
+    minAudioBytes?: number;
+    openOptions?: Partial<TTSAdapterOpenOptions & RealtimeAdapterOpenOptions> | ((fixture: VoiceTTSBenchmarkFixture) => Partial<TTSAdapterOpenOptions & RealtimeAdapterOpenOptions> | undefined);
+    realtimeFormat?: AudioFormat;
+    settleMs?: number;
+    waitForFirstAudioMs?: number;
+    waitForCloseAfterInterruptMs?: number;
+};
+type VoiceOutputAdapter = TTSAdapter | RealtimeAdapter;
+export declare const getDefaultTTSBenchmarkFixtures: () => {
+    id: string;
+    tags?: string[];
+    text: string;
+    title: string;
+}[];
+export declare const runTTSAdapterFixture: (adapter: VoiceOutputAdapter, fixture: VoiceTTSBenchmarkFixture, options?: VoiceTTSBenchmarkOptions) => Promise<VoiceTTSBenchmarkFixtureResult>;
+export declare const runTTSAdapterBenchmark: (adapterId: string, adapter: VoiceOutputAdapter, fixtures?: {
+    id: string;
+    tags?: string[];
+    text: string;
+    title: string;
+}[], options?: VoiceTTSBenchmarkOptions) => Promise<VoiceTTSBenchmarkReport>;
+export declare const summarizeTTSBenchmark: (adapterId: string, fixtures: VoiceTTSBenchmarkFixtureResult[]) => VoiceTTSBenchmarkSummary;
+export {};