@absolutejs/voice 0.0.20 → 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

@@ -1,13 +1,25 @@
-import type { STTAdapter } from '../types';
+import type { STTAdapter, VoiceAudioConditioningConfig, VoicePhraseHint, VoiceSTTFallbackConfig, VoiceSTTLifecycle, VoiceTurnCorrectionHandler, VoiceTurnProfile, VoiceTranscriptQuality } from '../types';
 import { type VoiceTranscriptAccuracy } from './accuracy';
 import type { VoiceTestFixture } from './fixtures';
 export type VoiceSessionBenchmarkScenario = VoiceTestFixture & {
     expectedTurnTexts: string[];
+    phraseHints?: VoicePhraseHint[];
     reconnectAtChunkIndex?: number;
+    reconnectAtChunkIndices?: number[];
     reconnectPauseMs?: number;
+    reconnectPauseMsByIndex?: number[];
     silenceMs?: number;
     speechThreshold?: number;
+    transcriptStabilityMs?: number;
     transcriptThreshold?: number;
+    turnProfile?: VoiceTurnProfile;
+    audioConditioning?: VoiceAudioConditioningConfig;
+    sttLifecycle?: VoiceSTTLifecycle;
+};
+export type VoiceSessionBenchmarkTraceEntry = {
+    atMs: number;
+    data?: unknown;
+    phase: string;
 };
 export type VoiceSessionBenchmarkTurnResult = {
     actualText: string;
@@ -15,27 +27,41 @@ export type VoiceSessionBenchmarkTurnResult = {
     expectedText?: string;
     index: number;
     passes: boolean;
+    quality?: VoiceTranscriptQuality;
 };
 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[];
 };
 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;
@@ -47,15 +73,79 @@ export type VoiceSessionBenchmarkReport = {
     scenarios: VoiceSessionBenchmarkScenarioResult[];
     summary: VoiceSessionBenchmarkSummary;
 };
-export declare const runVoiceSessionBenchmarkScenario: (adapter: STTAdapter, fixture: VoiceSessionBenchmarkScenario) => Promise<VoiceSessionBenchmarkScenarioResult>;
+export type VoiceSessionBenchmarkScenarioAggregate = {
+    averageElapsedMs: number;
+    averageFallbackReplayAudioMs: number;
+    averagePrimaryAudioMs: number;
+    averageReconnectCount: number;
+    averageRelativeCostUnits: number;
+    averageTurnPassRate: number;
+    averageWordErrorRate: number;
+    bestWordErrorRate: number;
+    fixtureId: string;
+    passCount: number;
+    passRate: number;
+    reconnectSuccessRate: number;
+    runCount: number;
+    tags: string[];
+    title: string;
+    worstWordErrorRate: number;
+};
+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;
+    totalPassCount: number;
+    totalRunCount: number;
+};
+export type VoiceSessionBenchmarkSeriesReport = {
+    adapterId: string;
+    generatedAt: number;
+    runCount: number;
+    scenarios: VoiceSessionBenchmarkScenarioAggregate[];
+    summary: VoiceSessionBenchmarkSeriesSummary;
+};
+export declare const runVoiceSessionBenchmarkScenario: (adapter: STTAdapter, fixture: VoiceSessionBenchmarkScenario, options?: {
+    correctTurn?: VoiceTurnCorrectionHandler;
+    sttFallback?: VoiceSTTFallbackConfig;
+    trace?: boolean;
+}) => Promise<VoiceSessionBenchmarkScenarioResult>;
 export declare const summarizeVoiceSessionBenchmark: (adapterId: string, scenarios: VoiceSessionBenchmarkScenarioResult[]) => VoiceSessionBenchmarkSummary;
+export declare const summarizeVoiceSessionBenchmarkSeries: (input: {
+    adapterId: string;
+    reports: VoiceSessionBenchmarkReport[];
+}) => VoiceSessionBenchmarkSeriesReport;
 export declare const runVoiceSessionBenchmark: (input: {
     adapter: STTAdapter;
     adapterId: string;
+    correctTurn?: VoiceTurnCorrectionHandler;
     scenarios: VoiceSessionBenchmarkScenario[];
+    sttFallback?: VoiceSTTFallbackConfig;
+    trace?: boolean;
 }) => Promise<{
     adapterId: string;
     generatedAt: number;
     scenarios: VoiceSessionBenchmarkScenarioResult[];
     summary: VoiceSessionBenchmarkSummary;
 }>;
+export declare const runVoiceSessionBenchmarkSeries: (input: {
+    adapter: STTAdapter;
+    adapterId: string;
+    correctTurn?: VoiceTurnCorrectionHandler;
+    runs: number;
+    scenarios: VoiceSessionBenchmarkScenario[];
+    sttFallback?: VoiceSTTFallbackConfig;
+    trace?: boolean;
+}) => Promise<VoiceSessionBenchmarkSeriesReport>;

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;
@@ -17,6 +18,7 @@ export type VoiceSTTAdapterHarnessResult = {
     finalEvents: VoiceFinalEvent[];
     finalText: string;
     partialEvents: VoicePartialEvent[];
+    speechEndedAt: number;
     startedAt: number;
 };
 export declare const runSTTAdapterFixture: (adapter: STTAdapter, fixture: VoiceTestFixture, options?: VoiceSTTAdapterHarnessOptions) => Promise<VoiceSTTAdapterHarnessResult>;

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 {};

package/dist/turnDetection.d.ts

@@ -2,4 +2,8 @@ import type { AudioChunk, Transcript } from './types';
 export declare const DEFAULT_SILENCE_MS = 700;
 export declare const DEFAULT_SPEECH_THRESHOLD = 0.015;
 export declare const measureAudioLevel: (audio: AudioChunk) => number;
-export declare const buildTurnText: (transcripts: Transcript[], partialText: string) => string;
+export declare const selectPreferredTranscriptText: (currentText: string, nextText: string) => string;
+export declare const buildTurnText: (transcripts: Transcript[], partialText: string, options?: {
+    partialEndedAtMs?: number;
+    partialStartedAtMs?: number;
+}) => string;

package/dist/turnProfiles.d.ts

@@ -0,0 +1,6 @@
+import type { VoiceResolvedTurnDetectionConfig, VoiceTurnDetectionConfig, VoiceTurnQualityProfile, VoiceTurnProfile } from './types';
+export declare const TURN_PROFILE_DEFAULTS: Record<VoiceTurnProfile, Omit<VoiceResolvedTurnDetectionConfig, 'profile'>>;
+export declare const QUALITY_PROFILE_DEFAULTS: Record<VoiceTurnQualityProfile, Partial<VoiceResolvedTurnDetectionConfig>>;
+export declare const DEFAULT_TURN_PROFILE: VoiceTurnProfile;
+export declare const DEFAULT_QUALITY_PROFILE: VoiceTurnQualityProfile;
+export declare const resolveTurnDetectionConfig: (config?: VoiceTurnDetectionConfig) => VoiceResolvedTurnDetectionConfig;