@absolutejs/voice 0.0.20 → 0.0.22-beta.0

package/dist/telephony/response.d.ts

@@ -0,0 +1,7 @@
+export type TelephonyResponseShapeMode = 'full' | 'lead-clause';
+export type TelephonyResponseShapeOptions = {
+    mode?: TelephonyResponseShapeMode;
+    maxChars?: number;
+    maxWords?: number;
+};
+export declare const shapeTelephonyAssistantText: (text: string, options?: TelephonyResponseShapeOptions) => string;

package/dist/telephony/twilio.d.ts

@@ -0,0 +1,116 @@
+import { type VoiceCallReviewArtifact, type VoiceCallReviewConfig } from '../testing/review';
+import type { AudioFormat, VoiceLogger, VoicePluginConfig, VoiceSessionRecord, VoiceServerMessage } from '../types';
+type TwilioMediaPayload = {
+    chunk?: string;
+    payload: string;
+    timestamp?: string;
+    track?: 'inbound' | 'outbound';
+};
+type TwilioConnectedMessage = {
+    event: 'connected';
+    protocol?: string;
+    version?: string;
+};
+type TwilioStartMessage = {
+    event: 'start';
+    sequenceNumber?: string;
+    start: {
+        accountSid?: string;
+        callSid?: string;
+        customParameters?: Record<string, string>;
+        mediaFormat?: {
+            channels?: number;
+            encoding?: string;
+            sampleRate?: number;
+        };
+        streamSid: string;
+        track?: string;
+    };
+    streamSid?: string;
+};
+type TwilioMediaMessage = {
+    event: 'media';
+    media: TwilioMediaPayload;
+    sequenceNumber?: string;
+    streamSid: string;
+};
+type TwilioMarkMessage = {
+    event: 'mark';
+    mark?: {
+        name?: string;
+    };
+    sequenceNumber?: string;
+    streamSid: string;
+};
+type TwilioStopMessage = {
+    event: 'stop';
+    sequenceNumber?: string;
+    stop?: {
+        accountSid?: string;
+        callSid?: string;
+    };
+    streamSid: string;
+};
+export type TwilioInboundMessage = TwilioConnectedMessage | TwilioStartMessage | TwilioMediaMessage | TwilioMarkMessage | TwilioStopMessage;
+export type TwilioOutboundMediaMessage = {
+    event: 'media';
+    media: {
+        payload: string;
+    };
+    streamSid: string;
+};
+export type TwilioOutboundClearMessage = {
+    event: 'clear';
+    streamSid: string;
+};
+export type TwilioOutboundMarkMessage = {
+    event: 'mark';
+    mark: {
+        name: string;
+    };
+    streamSid: string;
+};
+export type TwilioOutboundMessage = TwilioOutboundMediaMessage | TwilioOutboundClearMessage | TwilioOutboundMarkMessage;
+export type TwilioMediaStreamSocket = {
+    close: (code?: number, reason?: string) => void | Promise<void>;
+    send: (data: string) => void | Promise<void>;
+};
+export type TwilioMediaStreamBridgeOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Omit<VoicePluginConfig<TContext, TSession, TResult>, 'htmx' | 'path'> & {
+    clearOnInboundMedia?: boolean;
+    context: TContext;
+    logger?: VoiceLogger;
+    onVoiceMessage?: (input: {
+        callSid?: string;
+        message: VoiceServerMessage<TResult>;
+        sessionId: string;
+        streamSid?: string;
+    }) => Promise<void> | void;
+    review?: {
+        config?: VoiceCallReviewConfig;
+        fixtureId?: string;
+        onArtifact?: (artifact: VoiceCallReviewArtifact) => Promise<void> | void;
+        path?: string;
+        title?: string;
+    };
+    scenarioId?: string;
+    sessionId?: string;
+};
+export type TwilioMediaStreamBridge = {
+    close: (reason?: string) => Promise<void>;
+    getSessionId: () => string | null;
+    getStreamSid: () => string | null;
+    handleMessage: (raw: string | TwilioInboundMessage) => Promise<void>;
+};
+export type TwilioVoiceResponseOptions = {
+    parameters?: Record<string, string | number | boolean | undefined>;
+    streamName?: string;
+    streamUrl: string;
+    track?: 'both_tracks' | 'inbound_track' | 'outbound_track';
+};
+export declare const decodeTwilioMulawBase64: (payload: string) => Int16Array<ArrayBuffer>;
+export declare const encodeTwilioMulawBase64: (samples: Int16Array) => string;
+export declare const transcodeTwilioInboundPayloadToPCM16: (payload: string) => Uint8Array<ArrayBuffer>;
+export declare const transcodePCMToTwilioOutboundPayload: (chunk: Uint8Array, format: AudioFormat) => string;
+export declare const createTwilioVoiceResponse: (options: TwilioVoiceResponseOptions) => string;
+export declare const createTwilioMediaStreamBridge: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(socket: TwilioMediaStreamSocket, options: TwilioMediaStreamBridgeOptions<TContext, TSession, TResult>) => TwilioMediaStreamBridge;
+export {};

package/dist/testing/benchmark.d.ts

@@ -1,4 +1,4 @@
-import type { STTAdapter } from '../types';
+import type { STTAdapter, STTAdapterOpenOptions } from '../types';
 import { type VoiceSTTAdapterHarnessOptions, type VoiceSTTAdapterHarnessResult } from './stt';
 import type { VoiceTestFixture } from './fixtures';
 export type VoiceExpectedTermAccuracy = {
@@ -8,6 +8,15 @@ export type VoiceExpectedTermAccuracy = {
     missingTerms: string[];
     recall: number;
 };
+export type VoiceSTTFixtureEnvironment = 'accent' | 'accent-noisy' | 'clean' | 'code-switch' | 'jargon' | 'multilingual' | 'multi-speaker' | 'noisy' | 'telephony' | 'other';
+export type VoiceSpeakerTurnAccuracy = {
+    available: boolean;
+    actualTurnCount: number;
+    expectedTurnCount: number;
+    passes: boolean;
+    patternMatchRate: number;
+    postClustered?: boolean;
+};
 export type VoiceSTTBenchmarkFixtureResult = {
     accuracy: VoiceSTTAdapterHarnessResult['accuracy'];
     closeCount: number;
@@ -20,8 +29,12 @@ export type VoiceSTTBenchmarkFixtureResult = {
     finalText: string;
     fixtureId: string;
     fragmentationCount: number;
+    group: VoiceSTTFixtureEnvironment;
     passes: boolean;
     partialCount: number;
+    speakerTurns?: VoiceSpeakerTurnAccuracy;
+    postSpeechTimeToEndOfTurnMs?: number;
+    postSpeechTimeToFirstFinalMs?: number;
     tags: string[];
     timeToEndOfTurnMs?: number;
     timeToFirstFinalMs?: number;
@@ -34,7 +47,10 @@ export type VoiceSTTBenchmarkSummary = {
     averageElapsedMs: number;
     averageEndOfTurnCount: number;
     averageFinalCount: number;
+    averageSpeakerTurnMatchRate?: number;
     averageTermRecall: number;
+    averagePostSpeechTimeToEndOfTurnMs?: number;
+    averagePostSpeechTimeToFirstFinalMs?: number;
     averageTimeToEndOfTurnMs?: number;
     averageTimeToFirstFinalMs?: number;
     averageTimeToFirstPartialMs?: number;
@@ -46,6 +62,20 @@ export type VoiceSTTBenchmarkSummary = {
     passRate: number;
     totalErrorCount: number;
     wordAccuracyRate: number;
+    groupSummaries: VoiceSTTBenchmarkFixtureSummary[];
+};
+export type VoiceSTTBenchmarkFixtureSummary = {
+    group: VoiceSTTFixtureEnvironment;
+    fixtureCount: number;
+    fixturesWithErrors: number;
+    fixturesWithFragments: number;
+    passCount: number;
+    passRate: number;
+    wordAccuracyRate: number;
+    averageTermRecall: number;
+    averageSpeakerTurnMatchRate?: number;
+    averageWordErrorRate: number;
+    averageElapsedMs: number;
 };
 export type VoiceSTTBenchmarkReport = {
     adapterId: string;
@@ -53,6 +83,38 @@ export type VoiceSTTBenchmarkReport = {
     generatedAt: number;
     summary: VoiceSTTBenchmarkSummary;
 };
+export type VoiceSTTBenchmarkFixtureAggregate = {
+    averageElapsedMs: number;
+    averagePassRate: number;
+    averageWordErrorRate: number;
+    bestWordErrorRate: number;
+    fixtureId: string;
+    group: VoiceSTTFixtureEnvironment;
+    passCount: number;
+    runCount: number;
+    tags: string[];
+    title: string;
+    worstWordErrorRate: number;
+};
+export type VoiceSTTBenchmarkSeriesSummary = {
+    adapterId: string;
+    averageElapsedMs: number;
+    averagePassRate: number;
+    averageWordErrorRate: number;
+    fixtureCount: number;
+    flakyFixtureCount: number;
+    generatedRunCount: number;
+    stableFixtureCount: number;
+    totalPassCount: number;
+    totalRunCount: number;
+};
+export type VoiceSTTBenchmarkSeriesReport = {
+    adapterId: string;
+    fixtures: VoiceSTTBenchmarkFixtureAggregate[];
+    generatedAt: number;
+    runCount: number;
+    summary: VoiceSTTBenchmarkSeriesSummary;
+};
 export type VoiceSTTBenchmarkComparisonEntry = {
     adapterId: string;
     summary: VoiceSTTBenchmarkSummary;
@@ -63,10 +125,28 @@ export type VoiceSTTBenchmarkComparison = {
     bestByWordErrorRate?: VoiceSTTBenchmarkComparisonEntry;
     entries: VoiceSTTBenchmarkComparisonEntry[];
 };
+export type VoiceSTTBenchmarkAcceptanceThresholds = {
+    termRecall?: number;
+    wordAccuracyRate?: number;
+    overallPassRate?: number;
+    groupPassRate?: Partial<Record<VoiceSTTFixtureEnvironment, {
+        passRate?: number;
+        wordAccuracyRate?: number;
+    }>>;
+};
+export type VoiceSTTBenchmarkAcceptanceResult = {
+    adapterId: string;
+    failures: string[];
+    passed: boolean;
+    score: number;
+};
 export type VoiceSTTBenchmarkOptions = VoiceSTTAdapterHarnessOptions & {
-    fixtureOptions?: Record<string, Omit<VoiceSTTAdapterHarnessOptions, 'fixtureOptions'>>;
+    fixtureOptions?: Record<string, Omit<VoiceSTTAdapterHarnessOptions, 'fixtureOptions' | 'openOptions'>>;
+    openOptions?: Partial<STTAdapterOpenOptions> | ((fixture: VoiceTestFixture) => Partial<STTAdapterOpenOptions> | undefined);
 };
+export declare const resolveFixtureEnvironment: (fixture: Pick<VoiceTestFixture, "language" | "tags">) => VoiceSTTFixtureEnvironment;
 export declare const summarizeSTTBenchmark: (adapterId: string, fixtures: VoiceSTTBenchmarkFixtureResult[]) => VoiceSTTBenchmarkSummary;
+export declare const evaluateSTTBenchmarkAcceptance: (report: VoiceSTTBenchmarkReport, thresholds?: VoiceSTTBenchmarkAcceptanceThresholds) => VoiceSTTBenchmarkAcceptanceResult;
 export declare const compareSTTBenchmarks: (reports: VoiceSTTBenchmarkReport[]) => VoiceSTTBenchmarkComparison;
 export declare const runSTTAdapterBenchmark: ({ adapter, adapterId, fixtures, options }: {
     adapter: STTAdapter;
@@ -74,3 +154,14 @@ export declare const runSTTAdapterBenchmark: ({ adapter, adapterId, fixtures, op
     fixtures: VoiceTestFixture[];
     options?: VoiceSTTBenchmarkOptions;
 }) => Promise<VoiceSTTBenchmarkReport>;
+export declare const summarizeSTTBenchmarkSeries: (input: {
+    adapterId: string;
+    reports: VoiceSTTBenchmarkReport[];
+}) => VoiceSTTBenchmarkSeriesReport;
+export declare const runSTTAdapterBenchmarkSeries: ({ adapter, adapterId, fixtures, options, runs }: {
+    adapter: STTAdapter;
+    adapterId: string;
+    fixtures: VoiceTestFixture[];
+    options?: VoiceSTTBenchmarkOptions;
+    runs: number;
+}) => Promise<VoiceSTTBenchmarkSeriesReport>;

package/dist/testing/corrected.d.ts

@@ -0,0 +1,41 @@
+import type { VoiceLexiconEntry, VoicePhraseHint, VoiceTurnCorrectionHandler } from '../types';
+import { type VoiceExpectedTermAccuracy, type VoiceSTTBenchmarkReport } from './benchmark';
+import type { VoiceSessionBenchmarkReport } from './sessionBenchmark';
+import type { VoiceTestFixture } from './fixtures';
+export type VoiceCorrectionHintProfile = 'generic' | 'benchmark-seeded';
+type VoiceCorrectionAuditSlice<TReport> = {
+    fixtureIds: string[];
+    raw: TReport;
+    generic: TReport;
+    experimental: TReport;
+    benchmarkSeeded: TReport;
+};
+export type VoiceCorrectionBenchmarkAudit = {
+    raw: VoiceSTTBenchmarkReport;
+    generic: VoiceSTTBenchmarkReport;
+    experimental: VoiceSTTBenchmarkReport;
+    benchmarkSeeded: VoiceSTTBenchmarkReport;
+    holdout: VoiceCorrectionAuditSlice<VoiceSTTBenchmarkReport>;
+    lexicalHoldout: VoiceCorrectionAuditSlice<VoiceSTTBenchmarkReport>;
+};
+export type VoiceSessionCorrectionAudit = {
+    raw: VoiceSessionBenchmarkReport;
+    generic: VoiceSessionBenchmarkReport;
+    experimental: VoiceSessionBenchmarkReport;
+    benchmarkSeeded: VoiceSessionBenchmarkReport;
+    holdout: VoiceCorrectionAuditSlice<VoiceSessionBenchmarkReport>;
+    lexicalHoldout: VoiceCorrectionAuditSlice<VoiceSessionBenchmarkReport>;
+};
+export declare const isCorrectionHoldoutFixtureId: (fixtureId: string) => boolean;
+export declare const buildFixturePhraseHints: (fixture: Pick<VoiceTestFixture, "expectedTerms" | "expectedText">, profile?: VoiceCorrectionHintProfile) => VoicePhraseHint[];
+export declare const buildCodeSwitchBenchmarkLexicon: (fixture: Pick<VoiceTestFixture, "expectedTerms" | "expectedText" | "language" | "tags">) => VoiceLexiconEntry[];
+export declare const buildCodeSwitchBenchmarkPhraseHints: (fixture: Pick<VoiceTestFixture, "expectedTerms" | "expectedText" | "language" | "tags">) => VoicePhraseHint[];
+export declare const createCodeSwitchBenchmarkCorrectionHandler: () => VoiceTurnCorrectionHandler;
+export declare const createBenchmarkCorrectionHandler: (profile: VoiceCorrectionHintProfile) => VoiceTurnCorrectionHandler;
+export declare const scoreCorrectedExpectedTerms: (actualText: string, expectedTerms: string[] | undefined) => VoiceExpectedTermAccuracy;
+export declare const applyCorrectedBenchmarkReport: (report: VoiceSTTBenchmarkReport, fixtures: VoiceTestFixture[], profile?: VoiceCorrectionHintProfile) => VoiceSTTBenchmarkReport;
+export declare const applyExperimentalBenchmarkReport: (report: VoiceSTTBenchmarkReport, fixtures: VoiceTestFixture[]) => VoiceSTTBenchmarkReport;
+export declare const applyLexiconCorrectedBenchmarkReport: (report: VoiceSTTBenchmarkReport, fixtures: VoiceTestFixture[], buildLexicon: (fixture: Pick<VoiceTestFixture, "expectedTerms" | "expectedText" | "language" | "tags">) => VoiceLexiconEntry[]) => VoiceSTTBenchmarkReport;
+export declare const buildCorrectionBenchmarkAudit: (rawReport: VoiceSTTBenchmarkReport, fixtures: VoiceTestFixture[]) => VoiceCorrectionBenchmarkAudit;
+export declare const buildSessionCorrectionAudit: (raw: VoiceSessionBenchmarkReport, generic: VoiceSessionBenchmarkReport, experimental: VoiceSessionBenchmarkReport, benchmarkSeeded: VoiceSessionBenchmarkReport, scenarios: Array<Pick<VoiceTestFixture, "expectedTerms" | "expectedText" | "expectedTurnTexts" | "id">>) => VoiceSessionCorrectionAudit;
+export {};

package/dist/testing/duplex.d.ts

@@ -0,0 +1,59 @@
+import type { VoiceBargeInOptions } from '../types';
+export type VoiceDuplexBenchmarkScenario = {
+    expectedInterruptCount: number;
+    id: string;
+    initialPartial?: string;
+    interruptDelayMs?: number;
+    level?: number;
+    mode: 'audio-send' | 'input-level' | 'partial';
+    partial?: string;
+    title: string;
+};
+export type VoiceDuplexBenchmarkScenarioResult = {
+    actualInterruptCount: number;
+    elapsedMs: number;
+    expectedInterruptCount: number;
+    fixtureId: string;
+    interruptLatencyMs?: number;
+    mode: VoiceDuplexBenchmarkScenario['mode'];
+    passes: boolean;
+    title: string;
+};
+export type VoiceDuplexBenchmarkSummary = {
+    averageElapsedMs: number;
+    averageInterruptLatencyMs?: number;
+    passCount: number;
+    passRate: number;
+    scenarioCount: number;
+};
+export type VoiceDuplexBenchmarkReport = {
+    fixtures: VoiceDuplexBenchmarkScenarioResult[];
+    generatedAt: number;
+    summary: VoiceDuplexBenchmarkSummary;
+};
+export type VoiceDuplexBenchmarkOptions = {
+    bargeIn?: VoiceBargeInOptions;
+    defaultInterruptDelayMs?: number;
+};
+export declare const getDefaultVoiceDuplexBenchmarkScenarios: () => {
+    expectedInterruptCount: number;
+    id: string;
+    initialPartial?: string;
+    interruptDelayMs?: number;
+    level?: number;
+    mode: "audio-send" | "input-level" | "partial";
+    partial?: string;
+    title: string;
+}[];
+export declare const runVoiceDuplexBenchmarkScenario: (scenario: VoiceDuplexBenchmarkScenario, options?: VoiceDuplexBenchmarkOptions) => Promise<VoiceDuplexBenchmarkScenarioResult>;
+export declare const summarizeVoiceDuplexBenchmark: (fixtures: VoiceDuplexBenchmarkScenarioResult[]) => VoiceDuplexBenchmarkSummary;
+export declare const runVoiceDuplexBenchmark: (scenarios?: {
+    expectedInterruptCount: number;
+    id: string;
+    initialPartial?: string;
+    interruptDelayMs?: number;
+    level?: number;
+    mode: "audio-send" | "input-level" | "partial";
+    partial?: string;
+    title: string;
+}[], options?: VoiceDuplexBenchmarkOptions) => Promise<VoiceDuplexBenchmarkReport>;

package/dist/testing/fixtures.d.ts

@@ -1,10 +1,11 @@
-import type { AudioFormat } from '../types';
+import type { AudioFormat, VoiceExpectedSpeakerTurn } from '../types';
 export type VoiceTestFixtureManifestEntry = {
     id: string;
     title: string;
     audioPath: string;
     expectedText: string;
     expectedTerms?: string[];
+    expectedSpeakerTurns?: VoiceExpectedSpeakerTurn[];
     expectedTurnTexts?: string[];
     chunkDurationMs?: number;
     language?: string;
@@ -18,5 +19,20 @@ export type VoiceTestFixture = Omit<VoiceTestFixtureManifestEntry, 'audioPath'>
     audioPath: string;
     format: AudioFormat;
 };
+export type VoiceTelephonyFixtureOptions = {
+    includeAccents?: boolean;
+    targetSampleRateHz?: number;
+};
+export type VoiceMultiSpeakerFixtureOptions = {
+    silenceMs?: number;
+};
+export type VoiceFixtureLoadOptions = {
+    directories?: string[];
+    includeBundled?: boolean;
+};
 export declare const getVoiceFixtureDirectory: () => Promise<string>;
-export declare const loadVoiceTestFixtures: (fixtureDirectory?: string) => Promise<VoiceTestFixture[]>;
+export declare const resolveVoiceFixtureDirectories: (input?: string | string[] | VoiceFixtureLoadOptions) => Promise<string[]>;
+export declare const createTelephonyVoiceTestFixtures: (fixtures: VoiceTestFixture[], options?: VoiceTelephonyFixtureOptions) => VoiceTestFixture[];
+export declare const createMultiSpeakerVoiceTestFixtures: (fixtures: VoiceTestFixture[], options?: VoiceMultiSpeakerFixtureOptions) => VoiceTestFixture[];
+export declare const createJargonVoiceTestFixtures: (fixtures: VoiceTestFixture[]) => VoiceTestFixture[];
+export declare const loadVoiceTestFixtures: (fixtureDirectory?: string | string[] | VoiceFixtureLoadOptions) => Promise<VoiceTestFixture[]>;

package/dist/testing/index.d.ts

@@ -1,6 +1,11 @@
 export * from './accuracy';
 export * from './benchmark';
+export * from './corrected';
+export * from './duplex';
 export * from './fixtures';
 export * from './resilience';
+export * from './review';
 export * from './sessionBenchmark';
 export * from './stt';
+export * from './telephony';
+export * from './tts';