@absolutejs/voice 0.0.22-beta.33 → 0.0.22-beta.331

package/dist/proofTrends.d.ts

@@ -0,0 +1,133 @@
+import { Elysia } from 'elysia';
+export type VoiceProofTrendStatus = 'empty' | 'fail' | 'pass' | 'stale';
+export type VoiceProofTrendSummary = {
+    cycles?: number;
+    maxLiveP95Ms?: number;
+    maxProviderP95Ms?: number;
+    maxTurnP95Ms?: number;
+};
+export type VoiceProofTrendCycle = {
+    at?: string;
+    cycle?: number;
+    liveLatency?: {
+        p95Ms?: number;
+        samples?: number;
+    };
+    ok?: boolean;
+    opsRecovery?: {
+        issues?: number;
+        status?: string;
+    };
+    productionReadiness?: {
+        status?: string;
+    };
+    providerSlo?: {
+        events?: number;
+        eventsWithLatency?: number;
+        status?: string;
+    };
+    turnLatency?: {
+        p95Ms?: number;
+        samples?: number;
+        status?: string;
+    };
+};
+export type VoiceProofTrendReportInput = {
+    baseUrl?: string;
+    cycles?: VoiceProofTrendCycle[];
+    generatedAt?: string;
+    maxAgeMs?: number;
+    now?: Date | number | string;
+    ok?: boolean;
+    outputDir?: string;
+    runId?: string;
+    source?: string;
+    status?: VoiceProofTrendStatus;
+    summary?: VoiceProofTrendSummary;
+};
+export type VoiceProofTrendReport = {
+    ageMs?: number;
+    baseUrl?: string;
+    cycles: VoiceProofTrendCycle[];
+    freshUntil?: string;
+    generatedAt?: string;
+    maxAgeMs: number;
+    ok: boolean;
+    outputDir?: string;
+    runId?: string;
+    source: string;
+    status: VoiceProofTrendStatus;
+    summary: VoiceProofTrendSummary;
+};
+export type VoiceProofTrendAssertionInput = {
+    maxAgeMs?: number;
+    maxLiveP95Ms?: number;
+    maxProviderP95Ms?: number;
+    maxTurnP95Ms?: number;
+    minCycles?: number;
+    minLiveLatencySamples?: number;
+    minProviderSloEventsWithLatency?: number;
+    minTurnLatencySamples?: number;
+    requireAllCyclesOk?: boolean;
+    requireStatus?: VoiceProofTrendStatus;
+};
+export type VoiceProofTrendAssertionReport = {
+    ageMs?: number;
+    cycles: number;
+    failedCycles: number;
+    issues: string[];
+    maxLiveP95Ms?: number;
+    maxProviderP95Ms?: number;
+    maxTurnP95Ms?: number;
+    ok: boolean;
+    status: VoiceProofTrendStatus;
+};
+export type VoiceProofTrendRoutesOptions = {
+    headers?: HeadersInit;
+    jsonPath?: string;
+    maxAgeMs?: number;
+    name?: string;
+    path?: string;
+    source?: (() => Promise<VoiceProofTrendReport | VoiceProofTrendReportInput> | VoiceProofTrendReport | VoiceProofTrendReportInput) | VoiceProofTrendReport | VoiceProofTrendReportInput;
+};
+export declare const DEFAULT_VOICE_PROOF_TRENDS_MAX_AGE_MS: number;
+export declare const buildVoiceProofTrendReport: (input?: VoiceProofTrendReportInput) => VoiceProofTrendReport;
+export declare const buildEmptyVoiceProofTrendReport: (source?: string, maxAgeMs?: number) => VoiceProofTrendReport;
+export declare const normalizeVoiceProofTrendReport: (value: VoiceProofTrendReport | VoiceProofTrendReportInput, options?: {
+    maxAgeMs?: number;
+    source?: string;
+}) => VoiceProofTrendReport;
+export declare const readVoiceProofTrendReportFile: (path: string, options?: {
+    maxAgeMs?: number;
+}) => Promise<VoiceProofTrendReport>;
+export declare const evaluateVoiceProofTrendEvidence: (report: VoiceProofTrendReport, input?: VoiceProofTrendAssertionInput) => VoiceProofTrendAssertionReport;
+export declare const assertVoiceProofTrendEvidence: (report: VoiceProofTrendReport, input?: VoiceProofTrendAssertionInput) => VoiceProofTrendAssertionReport;
+export declare const createVoiceProofTrendRoutes: (options: VoiceProofTrendRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;
+export declare const formatVoiceProofTrendAge: (ageMs: unknown) => string;

package/dist/providerAdapters.d.ts

@@ -1,5 +1,5 @@
 import type { STTAdapter, STTAdapterOpenOptions, TTSAdapter, TTSAdapterOpenOptions } from './types';
-import type { VoiceProviderRouterProviderProfile } from './modelAdapters';
+import type { VoiceProviderRouterHealthOptions, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceProviderRouterPolicyPreset, VoiceProviderRouterPolicyWeights, VoiceProviderRouterStrategy } from './modelAdapters';
 type MaybePromise<T> = T | Promise<T>;
 type VoiceIOProviderKind = 'stt' | 'tts';
 type VoiceIOProviderStatus = 'error' | 'fallback' | 'success';
@@ -13,15 +13,30 @@ export type VoiceIOProviderRouterEvent<TProvider extends string = string> = {
     latencyBudgetMs?: number;
     operation: 'open' | 'send';
     provider: TProvider;
+    providerHealth?: VoiceProviderRouterProviderHealth<TProvider>;
     selectedProvider: TProvider;
     status: VoiceIOProviderStatus;
+    suppressionRemainingMs?: number;
+    suppressedUntil?: number;
     timedOut?: boolean;
 };
+export type VoiceIOProviderRouterPolicyConfig<TOpenOptions = unknown, TProvider extends string = string> = {
+    allowProviders?: readonly TProvider[] | ((input: TOpenOptions) => MaybePromise<readonly TProvider[]>);
+    maxCost?: number;
+    maxLatencyMs?: number;
+    minQuality?: number;
+    scoreProvider?: (provider: TProvider, profile: VoiceProviderRouterProviderProfile | undefined) => number;
+    strategy?: VoiceProviderRouterStrategy;
+    weights?: VoiceProviderRouterPolicyWeights;
+};
+export type VoiceIOProviderRouterPolicy<TOpenOptions = unknown, TProvider extends string = string> = VoiceProviderRouterStrategy | VoiceProviderRouterPolicyPreset | VoiceIOProviderRouterPolicyConfig<TOpenOptions, TProvider>;
 export type VoiceIOProviderRouterOptions<TProvider extends string, TAdapter, TOpenOptions> = {
     adapters: Partial<Record<TProvider, TAdapter>>;
     fallback?: readonly TProvider[] | ((input: TOpenOptions) => MaybePromise<readonly TProvider[]>);
     isProviderError?: (error: unknown, provider: TProvider) => boolean;
     onProviderEvent?: (event: VoiceIOProviderRouterEvent<TProvider>, input: TOpenOptions) => Promise<void> | void;
+    policy?: VoiceIOProviderRouterPolicy<TOpenOptions, TProvider>;
+    providerHealth?: boolean | VoiceProviderRouterHealthOptions;
     providerProfiles?: Partial<Record<TProvider, VoiceProviderRouterProviderProfile>>;
     selectProvider?: (input: TOpenOptions) => MaybePromise<TProvider | undefined>;
     timeoutMs?: number;

package/dist/providerCapabilities.d.ts

@@ -0,0 +1,92 @@
+import { Elysia } from 'elysia';
+import { type VoiceProviderHealthStatus, type VoiceProviderHealthSummary, type VoiceProviderHealthSummaryOptions } from './providerHealth';
+export type VoiceProviderCapabilityKind = 'llm' | 'stt' | 'tts' | 'custom';
+export type VoiceProviderCapabilityDefinition<TProvider extends string = string> = {
+    configured?: boolean;
+    description?: string;
+    features?: string[];
+    kind: VoiceProviderCapabilityKind;
+    label?: string;
+    model?: string;
+    provider: TProvider;
+    selected?: boolean;
+};
+export type VoiceProviderCapabilitySummary<TProvider extends string = string> = VoiceProviderCapabilityDefinition<TProvider> & {
+    configured: boolean;
+    health?: VoiceProviderHealthSummary<TProvider>;
+    status: VoiceProviderHealthStatus | 'selected' | 'unconfigured';
+};
+export type VoiceProviderCapabilityReport<TProvider extends string = string> = {
+    capabilities: VoiceProviderCapabilitySummary<TProvider>[];
+    checkedAt: number;
+    configured: number;
+    selected: number;
+    total: number;
+    unconfigured: number;
+};
+export type VoiceProviderCapabilityOptions<TProvider extends string = string> = VoiceProviderHealthSummaryOptions<TProvider> & {
+    features?: Partial<Record<TProvider, string[]>>;
+    llmProviders?: readonly TProvider[];
+    models?: Partial<Record<TProvider, string>>;
+    providers?: readonly VoiceProviderCapabilityDefinition<TProvider>[];
+    selected?: Partial<Record<VoiceProviderCapabilityKind, TProvider>>;
+    sttProviders?: readonly TProvider[];
+    ttsProviders?: readonly TProvider[];
+};
+export type VoiceProviderCapabilityHandlerOptions<TProvider extends string = string> = VoiceProviderCapabilityOptions<TProvider>;
+export type VoiceProviderCapabilityHTMLHandlerOptions<TProvider extends string = string> = VoiceProviderCapabilityHandlerOptions<TProvider> & {
+    headers?: HeadersInit;
+    render?: (report: VoiceProviderCapabilityReport<TProvider>) => string | Promise<string>;
+    title?: string;
+};
+export type VoiceProviderCapabilityRoutesOptions<TProvider extends string = string> = VoiceProviderCapabilityHTMLHandlerOptions<TProvider> & {
+    htmlPath?: false | string;
+    name?: string;
+    path?: string;
+};
+export declare const summarizeVoiceProviderCapabilities: <TProvider extends string = string>(options: VoiceProviderCapabilityOptions<TProvider>) => Promise<VoiceProviderCapabilityReport<TProvider>>;
+export declare const renderVoiceProviderCapabilityHTML: <TProvider extends string = string>(report: VoiceProviderCapabilityReport<TProvider>, options?: {
+    title?: string;
+}) => string;
+export declare const createVoiceProviderCapabilityJSONHandler: <TProvider extends string = string>(options: VoiceProviderCapabilityHandlerOptions<TProvider>) => () => Promise<VoiceProviderCapabilityReport<TProvider>>;
+export declare const createVoiceProviderCapabilityHTMLHandler: <TProvider extends string = string>(options: VoiceProviderCapabilityHTMLHandlerOptions<TProvider>) => () => Promise<Response>;
+export declare const createVoiceProviderCapabilityRoutes: <TProvider extends string = string>(options: VoiceProviderCapabilityRoutesOptions<TProvider>) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: VoiceProviderCapabilityReport<TProvider>;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/providerDecisionTraces.d.ts

@@ -0,0 +1,130 @@
+import { Elysia } from 'elysia';
+import { type VoiceRoutingEventKind } from './resilienceRoutes';
+import type { StoredVoiceTraceEvent, VoiceTraceEvent, VoiceTraceEventStore } from './trace';
+export type VoiceProviderDecisionStatus = 'degraded' | 'error' | 'fallback' | 'selected' | 'skipped' | 'success';
+export type VoiceProviderDecisionTrace = {
+    at: number;
+    elapsedMs?: number;
+    error?: string;
+    fallbackProvider?: string;
+    kind?: VoiceRoutingEventKind;
+    latencyBudgetMs?: number;
+    provider: string;
+    reason: string;
+    scenarioId?: string;
+    selectedProvider?: string;
+    sessionId: string;
+    status: VoiceProviderDecisionStatus;
+    surface: string;
+    turnId?: string;
+};
+export type VoiceProviderDecisionTraceInput = Omit<VoiceProviderDecisionTrace, 'at' | 'reason' | 'sessionId' | 'surface'> & {
+    at?: number;
+    reason?: string;
+    sessionId?: string;
+    surface?: string;
+};
+export type VoiceProviderDecisionTraceIssue = {
+    code: string;
+    message: string;
+    status: 'fail' | 'warn';
+    surface?: string;
+};
+export type VoiceProviderDecisionSurfaceReport = {
+    degraded: number;
+    decisions: number;
+    errors: number;
+    fallbacks: number;
+    issues: VoiceProviderDecisionTraceIssue[];
+    latestAt?: number;
+    providers: string[];
+    reasons: string[];
+    selected: number;
+    status: 'fail' | 'pass' | 'warn';
+    surface: string;
+};
+export type VoiceProviderDecisionTraceReport = {
+    checkedAt: number;
+    decisions: VoiceProviderDecisionTrace[];
+    issues: VoiceProviderDecisionTraceIssue[];
+    status: 'fail' | 'pass' | 'warn';
+    summary: {
+        degraded: number;
+        decisions: number;
+        errors: number;
+        fallbacks: number;
+        providers: number;
+        selected: number;
+        surfaces: number;
+    };
+    surfaces: VoiceProviderDecisionSurfaceReport[];
+};
+export type VoiceProviderDecisionTraceReportOptions = {
+    events?: StoredVoiceTraceEvent[] | VoiceProviderDecisionTrace[];
+    maxAgeMs?: number;
+    minDegraded?: number;
+    minDecisions?: number;
+    minFallbacks?: number;
+    now?: number;
+    requiredFallbackProviders?: readonly string[];
+    requiredProviders?: readonly string[];
+    requiredReasonIncludes?: readonly string[];
+    requiredSurfaces?: readonly string[];
+    requiredStatuses?: readonly VoiceProviderDecisionStatus[];
+    sessionId?: string;
+    store?: VoiceTraceEventStore;
+};
+export type VoiceProviderDecisionTraceRoutesOptions = VoiceProviderDecisionTraceReportOptions & {
+    headers?: HeadersInit;
+    htmlPath?: false | string;
+    markdownPath?: false | string;
+    name?: string;
+    path?: string;
+    render?: (report: VoiceProviderDecisionTraceReport) => string | Promise<string>;
+    title?: string;
+};
+export declare const createVoiceProviderDecisionTraceEvent: (input: VoiceProviderDecisionTraceInput) => VoiceTraceEvent;
+export declare const listVoiceProviderDecisionTraces: (events: StoredVoiceTraceEvent[] | VoiceProviderDecisionTrace[]) => VoiceProviderDecisionTrace[];
+export declare const buildVoiceProviderDecisionTraceReport: (options: VoiceProviderDecisionTraceReportOptions) => Promise<VoiceProviderDecisionTraceReport>;
+export declare const renderVoiceProviderDecisionTraceMarkdown: (report: VoiceProviderDecisionTraceReport) => string;
+export declare const renderVoiceProviderDecisionTraceHTML: (report: VoiceProviderDecisionTraceReport, title?: string) => string;
+export declare const createVoiceProviderDecisionTraceRoutes: (options: VoiceProviderDecisionTraceRoutesOptions) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: Response;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/providerOrchestration.d.ts

@@ -0,0 +1,109 @@
+import { Elysia } from 'elysia';
+import type { VoiceProviderOrchestrationProfile, VoiceProviderRouterProviderProfile } from './modelAdapters';
+import type { VoiceSessionRecord } from './types';
+export type VoiceProviderOrchestrationStatus = 'fail' | 'pass' | 'warn';
+export type VoiceProviderOrchestrationRequirement = {
+    minProviders?: number;
+    requireBudgetPolicy?: boolean;
+    requireCircuitBreaker?: boolean;
+    requireFallback?: boolean;
+    requireTimeoutBudget?: boolean;
+};
+export type VoiceProviderOrchestrationIssue = {
+    code: string;
+    message: string;
+    status: Exclude<VoiceProviderOrchestrationStatus, 'pass'>;
+    surface?: string;
+};
+export type VoiceProviderOrchestrationSurfaceReport = {
+    allowProviders: string[];
+    budgetPolicy: {
+        maxCost?: number;
+        maxLatencyMs?: number;
+        minQuality?: number;
+    };
+    circuitBreaker: boolean;
+    fallbackMode?: string;
+    fallbackProviders: string[];
+    issues: VoiceProviderOrchestrationIssue[];
+    providerProfiles: Record<string, VoiceProviderRouterProviderProfile>;
+    providers: string[];
+    status: VoiceProviderOrchestrationStatus;
+    strategy?: string;
+    surface: string;
+    timeoutBudget: boolean;
+    timeoutMs?: number;
+};
+export type VoiceProviderOrchestrationReport = {
+    checkedAt: number;
+    issues: VoiceProviderOrchestrationIssue[];
+    profileId: string;
+    status: VoiceProviderOrchestrationStatus;
+    summary: {
+        failed: number;
+        passed: number;
+        providers: number;
+        surfaces: number;
+        warned: number;
+    };
+    surfaces: VoiceProviderOrchestrationSurfaceReport[];
+};
+export type VoiceProviderOrchestrationReportOptions<TProvider extends string = string, TSurface extends string = string> = {
+    defaultRequirement?: VoiceProviderOrchestrationRequirement;
+    profile: VoiceProviderOrchestrationProfile<unknown, VoiceSessionRecord, TProvider, TSurface>;
+    requirements?: Partial<Record<TSurface, VoiceProviderOrchestrationRequirement>>;
+};
+export type VoiceProviderOrchestrationRoutesOptions<TProvider extends string = string, TSurface extends string = string> = VoiceProviderOrchestrationReportOptions<TProvider, TSurface> & {
+    headers?: HeadersInit;
+    htmlPath?: false | string;
+    markdownPath?: false | string;
+    name?: string;
+    path?: string;
+    render?: (report: VoiceProviderOrchestrationReport) => string | Promise<string>;
+    title?: string;
+};
+export declare const buildVoiceProviderOrchestrationReport: <TProvider extends string = string, TSurface extends string = string>(options: VoiceProviderOrchestrationReportOptions<TProvider, TSurface>) => VoiceProviderOrchestrationReport;
+export declare const renderVoiceProviderOrchestrationMarkdown: (report: VoiceProviderOrchestrationReport) => string;
+export declare const renderVoiceProviderOrchestrationHTML: (report: VoiceProviderOrchestrationReport, options?: {
+    title?: string;
+}) => string;
+export declare const createVoiceProviderOrchestrationRoutes: <TProvider extends string = string, TSurface extends string = string>(options: VoiceProviderOrchestrationRoutesOptions<TProvider, TSurface>) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: VoiceProviderOrchestrationReport;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/providerRoutingContract.d.ts

@@ -0,0 +1,71 @@
+import { type VoiceRoutingEvent, type VoiceRoutingEventKind } from './resilienceRoutes';
+import type { StoredVoiceTraceEvent, VoiceTraceEventStore } from './trace';
+export type VoiceProviderRoutingStatus = 'error' | 'fallback' | 'success';
+export type VoiceProviderRoutingExpectation = {
+    fallbackProvider?: string;
+    kind?: VoiceRoutingEventKind;
+    operation?: string;
+    provider?: string;
+    selectedProvider?: string;
+    status?: VoiceProviderRoutingStatus;
+};
+export type VoiceProviderRoutingContractDefinition = {
+    description?: string;
+    expect: VoiceProviderRoutingExpectation[];
+    id: string;
+    label?: string;
+    scenarioId?: string;
+    sessionId?: string;
+};
+export type VoiceProviderRoutingContractIssue = {
+    code: string;
+    message: string;
+};
+export type VoiceProviderRoutingContractReport = {
+    contractId: string;
+    events: VoiceRoutingEvent[];
+    issues: VoiceProviderRoutingContractIssue[];
+    pass: boolean;
+    scenarioId?: string;
+    sessionId?: string;
+};
+export type VoiceProviderRoutingContractRunOptions = {
+    contract: VoiceProviderRoutingContractDefinition;
+    events?: StoredVoiceTraceEvent[] | VoiceRoutingEvent[];
+    store?: VoiceTraceEventStore;
+};
+export type VoiceProviderRoutingContractAssertionInput = {
+    maxFailed?: number;
+    maxIssues?: number;
+    minContracts?: number;
+    minEvents?: number;
+    requiredContractIds?: string[];
+    requiredFallbackProviders?: string[];
+    requiredKinds?: VoiceRoutingEventKind[];
+    requiredOperations?: string[];
+    requiredProviders?: string[];
+    requiredScenarioIds?: string[];
+    requiredSelectedProviders?: string[];
+    requiredStatuses?: VoiceProviderRoutingStatus[];
+};
+export type VoiceProviderRoutingContractAssertionReport = {
+    contractIds: string[];
+    events: number;
+    failed: number;
+    fallbackProviders: string[];
+    issues: string[];
+    issueCount: number;
+    kinds: VoiceRoutingEventKind[];
+    ok: boolean;
+    operations: string[];
+    passed: number;
+    providers: string[];
+    scenarioIds: string[];
+    selectedProviders: string[];
+    statuses: VoiceProviderRoutingStatus[];
+    total: number;
+};
+export declare const runVoiceProviderRoutingContract: (options: VoiceProviderRoutingContractRunOptions) => Promise<VoiceProviderRoutingContractReport>;
+export declare const assertVoiceProviderRoutingContract: (options: VoiceProviderRoutingContractRunOptions) => Promise<VoiceProviderRoutingContractReport>;
+export declare const evaluateVoiceProviderRoutingContractEvidence: (reports: readonly VoiceProviderRoutingContractReport[], input?: VoiceProviderRoutingContractAssertionInput) => VoiceProviderRoutingContractAssertionReport;
+export declare const assertVoiceProviderRoutingContractEvidence: (reports: readonly VoiceProviderRoutingContractReport[], input?: VoiceProviderRoutingContractAssertionInput) => VoiceProviderRoutingContractAssertionReport;