@voice-kit/core 0.1.2 → 0.1.3

package/dist/index.d.ts

@@ -1,4 +1,1466 @@
-export { a as CallMemory, C as CallMemoryConfig, d as CallMetricsSummary, j as CallPurpose, c as ConsentRecord, D as DNCCheckParams, b as DNCCheckResult, E as ErrorSeverity, h as STTConfig, S as STTProvider, i as STTResult, T as TRAIConfig, f as TTSConfig, e as TTSProvider, V as VADConfig, g as VoiceFrame, k as VoiceKitErrorContext, W as WordTimestamp, l as createCallMemory, m as createSTT, n as createTTS } from './index-D3KfRXMP.js';
-export { AgentError, AgentHandoffError, CallingHoursError, ComplianceError, ConsentMissingError, DNCBlockedError, InngestError, STTConnectionError, STTError, STTLanguageNotSupportedError, STTStreamError, TTSConnectionError, TTSError, TTSStreamError, TTSVoiceNotFoundError, TurnTransitionError } from './errors.js';
-export { A as AudioTransportError, C as CallConnectionError, a as CallNotFoundError, T as TelephonyError, V as VoiceKitError } from './telephony.errors-C0-nScrF.js';
-import 'ai';
+import * as ai from 'ai';
+import { PassThrough } from 'node:stream';
+import { EventEmitter } from 'node:events';
+
+/**
+ * @voice-kit/core — Type definitions
+ */
+/**
+ * A single word with timing information from an STT provider.
+ */
+interface WordTimestamp {
+    word: string;
+    startMs: number;
+    endMs: number;
+    confidence: number;
+}
+/**
+ * The result of a speech-to-text transcription, either streaming partial
+ * or final. `isFinal` distinguishes the two.
+ *
+ * @example
+ * ```ts
+ * for await (const result of stt.transcribeStream(audioIterable)) {
+ *   if (result.isFinal) console.log('Final:', result.transcript)
+ * }
+ * ```
+ */
+interface STTResult {
+    /** The transcribed text. May be a partial result if `isFinal` is false. */
+    transcript: string;
+    /** Whether this is the final result for this utterance. */
+    isFinal: boolean;
+    /** Confidence score from the provider, 0–1. */
+    confidence: number;
+    /** BCP-47 language tag, e.g. 'hi-IN', 'en-IN'. */
+    language: string;
+    /** True if a mid-sentence language switch was detected (e.g. Hinglish). */
+    languageSwitchDetected: boolean;
+    /** Word-level timestamps if supported by the provider. */
+    words?: WordTimestamp[];
+    /** Time from audio start to this result being emitted, in ms. */
+    latencyMs: number;
+}
+/**
+ * Configuration for STT provider instantiation.
+ */
+interface STTConfig {
+    /** BCP-47 language code. Defaults to 'en-IN'. */
+    language?: string;
+    /** Additional languages to detect for code-switching. */
+    alternateLanguages?: string[];
+    /** API key. Falls back to provider-specific env var if omitted. */
+    apiKey?: string;
+    /** Custom model name. Provider-specific. */
+    model?: string;
+    /** Enable word-level timestamps. Default false. */
+    wordTimestamps?: boolean;
+    /** Enable interim / partial results. Default true. */
+    interimResults?: boolean;
+    /** Deepgram-specific: smart formatting. Default true. */
+    smartFormat?: boolean;
+    /** Sarvam-specific: region hint. */
+    region?: string;
+}
+/**
+ * The STTProvider interface. Obtained via `createSTT()` — never instantiate
+ * provider classes directly.
+ *
+ * @example
+ * ```ts
+ * const stt = createSTT('deepgram', { language: 'en-IN' })
+ * for await (const result of stt.transcribeStream(audioStream)) {
+ *   console.log(result.transcript)
+ * }
+ * ```
+ */
+interface STTProvider {
+    /** Stream audio in, stream STTResults out. Primary realtime path. */
+    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
+    /** Batch transcription for recordings. Returns single final result. */
+    transcribeBatch(audio: Buffer): Promise<STTResult>;
+    /** Whether this provider supports streaming (all except Whisper). */
+    readonly supportsStreaming: boolean;
+    /** BCP-47 codes this provider can handle. */
+    readonly supportedLanguages: string[];
+    /** Human-readable provider name for logging. */
+    readonly name: string;
+}
+/**
+ * Configuration for TTS provider instantiation.
+ */
+interface TTSConfig {
+    /** Voice identifier. Provider-specific. */
+    voiceId?: string;
+    /** Output sample rate. Defaults to provider native rate. */
+    sampleRate?: number;
+    /** Speaking speed multiplier. Default 1.0. */
+    speed?: number;
+    /** Pitch adjustment. Provider-specific. */
+    pitch?: number;
+    /** API key. Falls back to provider-specific env var if omitted. */
+    apiKey?: string;
+    /** ElevenLabs-specific: model ID. */
+    modelId?: string;
+    /** Cartesia-specific: emotion control. */
+    emotion?: string;
+    /** Sarvam-specific: target language for Indic voices. */
+    targetLanguage?: string;
+}
+/**
+ * The TTSProvider interface. Obtained via `createTTS()` — never instantiate
+ * provider classes directly.
+ *
+ * @example
+ * ```ts
+ * const tts = createTTS('elevenlabs', { voiceId: 'your-voice-id' })
+ * for await (const chunk of tts.synthesizeStream('Hello, how can I help?')) {
+ *   socket.write(chunk)
+ * }
+ * ```
+ */
+interface TTSProvider {
+    /** Stream synthesis — preferred for realtime. First chunk < 300ms. */
+    synthesizeStream(text: string, config?: TTSConfig): AsyncIterable<Buffer>;
+    /** Synthesize full audio — for pre-recorded prompts or caching. */
+    synthesizeFull(text: string, config?: TTSConfig): Promise<Buffer>;
+    /** Native output sample rate of this provider in Hz. */
+    readonly outputSampleRate: number;
+    /** Native output format before any resampling. */
+    readonly outputFormat: 'pcm' | 'mulaw' | 'opus' | 'mp3';
+    /** Human-readable provider name for logging. */
+    readonly name: string;
+}
+/**
+ * A frame of audio classified by the VAD engine.
+ * Developers subscribe to these events — never to raw VAD API.
+ */
+interface VoiceFrame {
+    /** Event type. */
+    type: 'speech_start' | 'speech_end' | 'speech';
+    /** VAD confidence 0–1. */
+    confidence: number;
+    /** Raw PCM audio bytes for this frame. */
+    audioBuffer: Buffer;
+    /** Duration of audio in this frame, in ms. */
+    durationMs: number;
+}
+/**
+ * Configuration for the VAD engine.
+ */
+interface VADConfig {
+    /** Activation threshold 0–1. Default 0.6. */
+    threshold?: number;
+    /** Consecutive positive frames before speech_start. Default 3. */
+    positiveSpeechFrames?: number;
+    /** Consecutive negative frames before speech_end. Default 5. */
+    negativeSpeechFrames?: number;
+    /** Debounce window in ms to prevent rapid flip-flop. Default 150. */
+    debounceMs?: number;
+    /** Input sample rate. Auto-set by AudioPipeline — do not override. */
+    sampleRate?: number;
+}
+/**
+ * Configuration for call memory (LRU-backed sliding window of turns).
+ */
+interface CallMemoryConfig {
+    /** Maximum number of turns to retain. Default 20. */
+    maxTurns?: number;
+    /** Maximum bytes of conversation history to retain. Default 512KB. */
+    maxBytes?: number;
+    /** TTL for the entire call memory entry in ms. Default 30 minutes. */
+    ttlMs?: number;
+}
+/**
+ * In-process LRU-backed call memory. Obtained via `createCallMemory()`.
+ *
+ * @example
+ * ```ts
+ * const memory = createCallMemory({ maxTurns: 20 })
+ * memory.addTurn(callId, { role: 'user', content: 'Hello' })
+ * const history = memory.getTurns(callId)
+ * ```
+ */
+interface CallMemory {
+    addTurn(callId: string, message: ai.ModelMessage): void;
+    getTurns(callId: string): ai.ModelMessage[];
+    clearCall(callId: string): void;
+    getTokenEstimate(callId: string): number;
+    /** Truncate oldest turns to stay within budget. */
+    trimToTokenBudget(callId: string, maxTokens: number): void;
+}
+/**
+ * Type of call for TRAI DND classification.
+ */
+type CallPurpose = 'TRANSACTIONAL' | 'PROMOTIONAL' | 'SERVICE' | 'EMERGENCY';
+/**
+ * TRAI DNC check parameters.
+ */
+interface DNCCheckParams {
+    /** E.164 format phone number, validated via libphonenumber-js. */
+    to: string;
+    /** Purpose category for TRAI classification. */
+    purpose: CallPurpose;
+    /** Scheduled call time. Defaults to now. */
+    scheduledAt?: Date;
+}
+/**
+ * Result of a TRAI DNC check.
+ */
+interface DNCCheckResult {
+    /** Whether the call is permitted. */
+    allowed: boolean;
+    /** Human-readable reason if not allowed. */
+    reason?: string;
+    /** When this result was fetched (from LRU cache). */
+    cachedAt?: Date;
+    /** Whether result came from local LRU cache. */
+    fromCache: boolean;
+}
+/**
+ * Consent record stored for TRAI compliance.
+ */
+interface ConsentRecord {
+    phoneNumber: string;
+    consentedAt: Date;
+    /** Channel through which consent was obtained. */
+    channel: 'voice' | 'sms' | 'web' | 'ivr';
+    /** Call purpose consent was given for. */
+    purpose: CallPurpose;
+    /** Optional reference ID (e.g. recording URL). */
+    referenceId?: string;
+}
+/**
+ * TRAI compliance configuration.
+ */
+interface TRAIConfig {
+    /** Disable TRAI checks entirely. Default false. */
+    disabled?: boolean;
+    /** Calling timezone override. Default 'Asia/Kolkata'. */
+    timezone?: string;
+    /** Override calling hours start (24h). Default 9. */
+    callingHoursStart?: number;
+    /** Override calling hours end (24h). Default 21. */
+    callingHoursEnd?: number;
+    /** Custom DNC API endpoint. Default: mock endpoint (must be replaced in production). */
+    dncApiEndpoint?: string;
+}
+/**
+ * Aggregated metrics for a completed or in-progress call.
+ */
+interface CallMetricsSummary {
+    callId: string;
+    sttFirstByteMs: number[];
+    ttsFirstByteMs: number[];
+    llmFirstTokenMs: number[];
+    turnLatencyMs: number[];
+    interruptionCount: number;
+    interruptionPositions: number[];
+    tokenCost: {
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+        estimatedUsdCost: number;
+    }[];
+    avgTurnLatencyMs: number;
+    p95TurnLatencyMs: number;
+}
+/**
+ * Error severity level.
+ */
+type ErrorSeverity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Base error context shared by all VoiceKit errors.
+ */
+interface VoiceKitErrorContext {
+    /** Error code for programmatic handling. */
+    code: string;
+    /** Associated call ID if applicable. */
+    callId?: string;
+    /** The provider that threw (e.g. 'deepgram', 'elevenlabs'). */
+    provider?: string;
+    /** Whether this error is safe to retry. */
+    retryable: boolean;
+    /** Severity for alerting/logging. */
+    severity: ErrorSeverity;
+    /** Original upstream error if wrapping. */
+    cause?: unknown;
+}
+
+/**
+ * @voice-kit/core — Typed error hierarchy
+ *
+ * All VoiceKit errors extend VoiceKitError. Never throw raw Error.
+ * Every error carries: code, message, provider, callId, retryable, severity.
+ */
+
+/**
+ * Base class for all VoiceKit errors. Provides structured context for
+ * logging, alerting, and programmatic error handling.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await stt.transcribeBatch(audio)
+ * } catch (err) {
+ *   if (err instanceof STTError) {
+ *     console.error(err.code, err.provider, err.retryable)
+ *   }
+ * }
+ * ```
+ */
+declare class VoiceKitError extends Error {
+    readonly code: string;
+    readonly callId?: string;
+    readonly provider?: string;
+    readonly retryable: boolean;
+    readonly severity: ErrorSeverity;
+    readonly cause?: unknown;
+    constructor(params: {
+        code: string;
+        message: string;
+        callId?: string;
+        provider?: string;
+        retryable?: boolean;
+        severity?: ErrorSeverity;
+        cause?: unknown;
+    });
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        callId: string | undefined;
+        provider: string | undefined;
+        retryable: boolean;
+        severity: ErrorSeverity;
+    };
+}
+
+/**
+ * Errors from agent orchestration (turn engine, handoff, injection).
+ */
+declare class AgentError extends VoiceKitError {
+}
+declare class TurnTransitionError extends AgentError {
+    readonly fromState: string;
+    readonly event: string;
+    constructor(fromState: string, toEvent: string, callId?: string);
+}
+declare class AgentHandoffError extends AgentError {
+    constructor(capability: string, cause?: unknown, callId?: string);
+}
+
+/**
+ * Errors from compliance checks (TRAI DNC, calling hours, consent).
+ */
+declare class ComplianceError extends VoiceKitError {
+    readonly phoneNumber?: string;
+    constructor(params: {
+        code: string;
+        message: string;
+        callId?: string;
+        phoneNumber?: string;
+        retryable?: boolean;
+        severity?: ErrorSeverity;
+        cause?: unknown;
+    });
+}
+declare class DNCBlockedError extends ComplianceError {
+    constructor(phoneNumber: string, callId?: string);
+}
+declare class CallingHoursError extends ComplianceError {
+    constructor(phoneNumber: string, currentTime: string, callId?: string);
+}
+declare class ConsentMissingError extends ComplianceError {
+    constructor(phoneNumber: string, callId?: string);
+}
+
+/**
+ * Errors from Inngest background task dispatch.
+ */
+declare class InngestError extends VoiceKitError {
+    readonly taskName?: string;
+    constructor(params: {
+        code: string;
+        message: string;
+        callId?: string;
+        taskName?: string;
+        cause?: unknown;
+    });
+}
+
+/**
+ * Errors from speech-to-text providers.
+ */
+declare class STTError extends VoiceKitError {
+    readonly languageCode?: string;
+    constructor(params: {
+        code: string;
+        message: string;
+        callId?: string;
+        provider?: string;
+        retryable?: boolean;
+        severity?: ErrorSeverity;
+        cause?: unknown;
+        languageCode?: string;
+    });
+}
+declare class STTConnectionError extends STTError {
+    constructor(provider: string, cause?: unknown, callId?: string);
+}
+declare class STTStreamError extends STTError {
+    constructor(provider: string, cause?: unknown, callId?: string);
+}
+declare class STTLanguageNotSupportedError extends STTError {
+    constructor(provider: string, language: string);
+}
+
+/**
+ * Errors from telephony providers.
+ */
+declare class TelephonyError extends VoiceKitError {
+    readonly to?: string;
+    readonly from?: string;
+    constructor(params: {
+        code: string;
+        message: string;
+        callId?: string;
+        provider?: string;
+        retryable?: boolean;
+        severity?: ErrorSeverity;
+        cause?: unknown;
+        to?: string;
+        from?: string;
+    });
+}
+declare class CallConnectionError extends TelephonyError {
+    constructor(provider: string, to: string, cause?: unknown);
+}
+declare class CallNotFoundError extends TelephonyError {
+    constructor(callId: string, provider: string);
+}
+declare class AudioTransportError extends TelephonyError {
+    constructor(provider: string, cause?: unknown, callId?: string);
+}
+
+/**
+ * Errors from text-to-speech providers.
+ */
+declare class TTSError extends VoiceKitError {
+}
+declare class TTSConnectionError extends TTSError {
+    constructor(provider: string, cause?: unknown, callId?: string);
+}
+declare class TTSStreamError extends TTSError {
+    constructor(provider: string, cause?: unknown, callId?: string);
+}
+declare class TTSVoiceNotFoundError extends TTSError {
+    constructor(provider: string, voiceId: string);
+}
+
+/**
+ * @voice-kit/core — G.711 µ-law codec
+ *
+ * Pure TypeScript implementation of G.711 µ-law (mu-law) encode/decode.
+ * No external codec library needed for µ-law. This is 100% internal —
+ * never exported from the public API.
+ *
+ * Used by AudioPipeline to convert Twilio/Exotel µ-law audio ↔ PCM.
+ */
+/**
+ * Convert a single µ-law encoded byte (0–255) to a 16-bit linear PCM sample.
+ * Algorithm: ITU-T G.711 Section 3.
+ *
+ * @internal
+ */
+declare function mulawToLinear(sample: number): number;
+/**
+ * Convert a 16-bit linear PCM sample to a µ-law encoded byte.
+ * Algorithm: ITU-T G.711 Section 3.
+ *
+ * @internal
+ */
+declare function linearToMulaw(sample: number): number;
+/**
+ * Convert a Buffer of µ-law encoded bytes to 16-bit little-endian PCM.
+ * Each µ-law byte expands to 2 PCM bytes (16-bit LE signed).
+ *
+ * Input:  N bytes  (µ-law, 8kHz mono as sent by Twilio/Exotel)
+ * Output: N*2 bytes (PCM 16-bit LE, same sample rate)
+ *
+ * @internal
+ */
+declare function mulawBufferToPcm(buf: Buffer): Buffer;
+/**
+ * Convert a Buffer of 16-bit little-endian PCM to µ-law bytes.
+ * Each pair of PCM bytes compresses to 1 µ-law byte.
+ *
+ * Input:  N bytes (PCM 16-bit LE)
+ * Output: N/2 bytes (µ-law)
+ *
+ * @internal
+ */
+declare function pcmBufferToMulaw(buf: Buffer): Buffer;
+/**
+ * Convert a base64-encoded µ-law string (as sent by Twilio Media Streams)
+ * directly to PCM Buffer. Convenience wrapper used in TwilioProvider.
+ *
+ * @internal
+ */
+declare function base64MulawToPcm(base64: string): Buffer;
+/**
+ * Convert a PCM Buffer to a base64-encoded µ-law string (for sending
+ * back to Twilio Media Streams).
+ *
+ * @internal
+ */
+declare function pcmToBase64Mulaw(pcm: Buffer): string;
+
+/**
+ * @voice-kit/core — AudioPipeline
+ *
+ * Automatically selects codec, sample rate, and VAD config based on the
+ * telephony provider. Developers never configure codecs — the pipeline
+ * handles all conversions transparently.
+ *
+ * Provider audio formats:
+ *   Twilio / Exotel → 8kHz µ-law → decode → 8kHz PCM → upsample → 16kHz PCM (for STT)
+ *   Plivo / Telnyx  → 8kHz µ-law (same as Twilio)
+ *   LiveKit         → 48kHz Opus → decode → 48kHz PCM → downsample → 16kHz PCM (for STT)
+ *   SIP (generic)   → 8kHz G.711 (same as Twilio)
+ *
+ * TTS output path (reverse):
+ *   STT/LLM → TTS PCM (provider-native rate) → resample → telephony-native rate → encode
+ */
+
+/** Telephony providers handled by the pipeline. */
+type TelephonyProviderName = 'twilio' | 'exotel' | 'plivo' | 'telnyx' | 'livekit' | 'sip';
+/**
+ * AudioPipeline: auto-wires codec → resample → VAD for a specific telephony provider.
+ *
+ * Developers never call this directly — it is instantiated by TelephonyProvider
+ * implementations and consumed by VoiceAgent.
+ *
+ * @internal
+ */
+declare class AudioPipeline {
+    private readonly profile;
+    readonly provider: TelephonyProviderName;
+    constructor(provider: TelephonyProviderName);
+    /**
+     * Transform incoming telephony audio to 16kHz PCM for STT.
+     * Handles µ-law decode + resampling automatically.
+     *
+     * @param raw  Raw audio bytes as received from telephony provider
+     * @returns    Async iterable of 16kHz PCM buffers for STT
+     *
+     * @internal
+     */
+    inboundForSTT(raw: AsyncIterable<Buffer>): AsyncIterable<Buffer>;
+    /**
+     * Transform TTS output PCM to telephony-native format for sending to caller.
+     * Handles resampling + µ-law encode automatically.
+     *
+     * @param ttsAudio  Raw PCM from TTS provider (at TTS provider's native rate)
+     * @param ttsSampleRate  Native sample rate of the TTS provider
+     * @returns  Async iterable of audio bytes ready to send to telephony provider
+     *
+     * @internal
+     */
+    outboundFromTTS(ttsAudio: AsyncIterable<Buffer>, ttsSampleRate: number): AsyncIterable<Buffer>;
+    /** Get the VAD config tuned for this provider's audio quality. @internal */
+    get vadConfig(): Required<VADConfig>;
+    /** Sample rate that STT expects (post-pipeline). @internal */
+    get sttSampleRate(): number;
+    /** Async generator: decode µ-law stream to PCM. @internal */
+    private decodeMulaw;
+}
+/**
+ * Factory: create an AudioPipeline pre-configured for the given telephony provider.
+ *
+ * @internal — used by TelephonyProvider implementations
+ */
+declare function createAudioPipeline(provider: TelephonyProviderName): AudioPipeline;
+
+/**
+ * @voice-kit/core — PCM audio resampler
+ *
+ * Resamples raw PCM audio between sample rates using fluent-ffmpeg.
+ * 100% internal — never exported from the public API.
+ * Used by AudioPipeline to convert provider-native rates to STT-required rates.
+ */
+
+/**
+ * Resample a PCM Buffer from one sample rate to another.
+ * Both input and output are signed 16-bit little-endian PCM, mono.
+ *
+ * Common conversions:
+ *   8kHz → 16kHz  (Twilio/Exotel µ-law decoded → Deepgram input)
+ *   48kHz → 16kHz (LiveKit Opus decoded → Deepgram input)
+ *   24kHz → 8kHz  (ElevenLabs output → Twilio send)
+ *
+ * @param buf     Raw PCM bytes (s16le mono)
+ * @param fromHz  Source sample rate in Hz
+ * @param toHz    Target sample rate in Hz
+ * @returns       Resampled PCM bytes (s16le mono)
+ *
+ * @internal
+ */
+declare function resample(buf: Buffer, fromHz: number, toHz: number): Promise<Buffer>;
+/**
+ * Create a streaming resampler Transform stream.
+ * More efficient than buffering for large audio chunks.
+ *
+ * @param fromHz  Source sample rate in Hz
+ * @param toHz    Target sample rate in Hz
+ * @returns       Node.js Transform stream: PCM in, resampled PCM out
+ *
+ * @internal
+ */
+declare function createResamplerStream(fromHz: number, toHz: number): PassThrough;
+/**
+ * Async generator that resamples chunks from an audio iterable on the fly.
+ * Used by AudioPipeline for realtime streaming paths.
+ *
+ * @param audio   Async iterable of raw PCM buffers at fromHz
+ * @param fromHz  Source sample rate
+ * @param toHz    Target sample rate
+ *
+ * @internal
+ */
+declare function resampleStream(audio: AsyncIterable<Buffer>, fromHz: number, toHz: number): AsyncIterable<Buffer>;
+
+/**
+ * @voice-kit/core — Voice Activity Detection engine
+ *
+ * Wraps @ricky0123/vad-web and emits strongly-typed VoiceFrame events.
+ * Developers subscribe to VoiceFrame events — they never touch the raw VAD API.
+ *
+ * @example
+ * ```ts
+ * const vad = createVAD({ threshold: 0.6 })
+ * vad.on('frame', (frame) => {
+ *   if (frame.type === 'speech_start') startRecording()
+ *   if (frame.type === 'speech_end') stopRecording()
+ * })
+ * await vad.processStream(audioStream)
+ * ```
+ */
+
+type VADEventMap = {
+    frame: [VoiceFrame];
+    error: [AudioTransportError];
+};
+/**
+ * Internal VAD engine. Processes a 16kHz PCM stream and emits VoiceFrame events.
+ * Automatically debounces rapid speech_start/speech_end transitions.
+ *
+ * Input: 16kHz, 16-bit little-endian PCM, mono.
+ * Output: VoiceFrame events on the emitter.
+ */
+declare class VADEngine extends EventEmitter<VADEventMap> {
+    private readonly config;
+    private isSpeaking;
+    private positiveFrameCount;
+    private negativeFrameCount;
+    private debounceTimer;
+    private frameBuffer;
+    private vadModel;
+    constructor(config?: VADConfig);
+    /**
+     * Process an async stream of PCM audio frames.
+     * Automatically frames the input into 30ms chunks for VAD processing.
+     *
+     * @param audio  Async iterable of PCM buffers (16kHz, s16le, mono)
+     */
+    processStream(audio: AsyncIterable<Buffer>): Promise<void>;
+    /**
+     * Process a single 30ms PCM frame through the VAD model.
+     *
+     * @internal
+     */
+    private processFrame;
+    /**
+     * Run Silero VAD model inference on a single frame.
+     * Returns confidence score 0–1.
+     *
+     * @internal
+     */
+    private runVADInference;
+    private emitFrame;
+    private scheduleDebounce;
+    private clearDebounce;
+    /**
+     * Load the Silero VAD model if not already loaded.
+     * @internal
+     */
+    private ensureModelLoaded;
+    /** Clean up resources. Call when the call ends. */
+    destroy(): void;
+}
+/**
+ * Create a configured VAD engine instance.
+ * Input must be 16kHz, 16-bit LE, mono PCM (handled automatically by AudioPipeline).
+ *
+ * @example
+ * ```ts
+ * const vad = createVAD({ threshold: 0.7, debounceMs: 200 })
+ * vad.on('frame', (frame) => handleFrame(frame))
+ * await vad.processStream(audioStream)
+ * ```
+ */
+declare function createVAD(config?: VADConfig): VADEngine;
+
+/**
+ * @voice-kit/core — Call audit log
+ *
+ * Immutable append-only audit log for compliance and debugging.
+ * In-memory (LRU) + optional file sink. Once written, entries cannot be modified.
+ */
+type AuditEventType = 'call.started' | 'call.ended' | 'compliance.checked' | 'compliance.blocked' | 'consent.recorded' | 'consent.verified' | 'turn.started' | 'turn.ended' | 'interruption' | 'agent.handoff' | 'tool.called' | 'error';
+interface AuditEntry {
+    readonly id: string;
+    readonly callId: string;
+    readonly type: AuditEventType;
+    readonly timestamp: Date;
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/**
+ * Immutable append-only call audit log.
+ *
+ * Entries are written to LRU in-process memory and optionally to a JSONL file.
+ * Once written, entries are frozen — no modification is possible.
+ *
+ * @example
+ * ```ts
+ * const audit = new CallAuditLog({ filePath: '/var/log/voice-kit/audit.jsonl' })
+ * audit.append(callId, 'call.started', { from: '+91...', to: '+91...' })
+ * const entries = audit.getEntries(callId)
+ * ```
+ */
+declare class CallAuditLog {
+    /** LRU: up to 10,000 calls × 200 entries each = 2M entries max */
+    private readonly cache;
+    private readonly filePath?;
+    constructor(options?: {
+        filePath?: string;
+        maxCalls?: number;
+    });
+    /**
+     * Append an immutable audit entry for a call.
+     *
+     * @param callId  The call identifier
+     * @param type    Audit event type
+     * @param data    Additional structured data
+     */
+    append(callId: string, type: AuditEventType, data?: Record<string, unknown>): AuditEntry;
+    /**
+     * Get all audit entries for a call, in insertion order.
+     *
+     * @param callId  The call identifier
+     */
+    getEntries(callId: string): ReadonlyArray<AuditEntry>;
+    /**
+     * Get entries of a specific type for a call.
+     */
+    getEntriesByType(callId: string, type: AuditEventType): ReadonlyArray<AuditEntry>;
+    /** Write entry to JSONL file. @internal */
+    private writeToFile;
+}
+
+/**
+ * @voice-kit/core — TRAI Compliance
+ *
+ * TRAI (Telecom Regulatory Authority of India) compliance utilities:
+ * - DNC (Do Not Call) registry check with 24h LRU cache
+ * - Calling hours enforcement (9 AM – 9 PM IST)
+ * - Consent tracking (180-day validity)
+ *
+ * Auto-enabled for +91 numbers. Opt-out, not opt-in.
+ */
+
+/**
+ * TRAI compliance engine.
+ *
+ * Enforces DNC registry, calling hours, and consent rules for Indian numbers.
+ * Results are cached in LRU to minimize API round-trips.
+ *
+ * @example
+ * ```ts
+ * const trai = new TRAICompliance()
+ *
+ * const result = await trai.checkCallPermission({
+ *   to: '+919876543210',
+ *   purpose: 'TRANSACTIONAL',
+ * })
+ *
+ * if (!result.allowed) throw new Error(result.reason)
+ * ```
+ */
+declare class TRAICompliance {
+    private readonly config;
+    private readonly http;
+    /** DNC check results cached for 24 hours per number. */
+    private readonly dncCache;
+    /** Consent records cached for 180 days. */
+    private readonly consentCache;
+    constructor(config?: TRAIConfig);
+    /**
+     * Check whether a call is permitted under TRAI rules.
+     * Checks: valid E.164, DNC registry, calling hours.
+     *
+     * @param params  Call permission check parameters
+     * @throws  DNCBlockedError if number is on DNC registry
+     * @throws  CallingHoursError if outside allowed calling hours
+     * @throws  ComplianceError if phone number is invalid
+     *
+     * @example
+     * ```ts
+     * const result = await trai.checkCallPermission({
+     *   to: '+919876543210',
+     *   purpose: 'TRANSACTIONAL',
+     * })
+     * if (!result.allowed) console.log(result.reason)
+     * ```
+     */
+    checkCallPermission(params: DNCCheckParams): Promise<DNCCheckResult>;
+    /**
+     * Check if the current time (or a given time) is within TRAI calling hours.
+     * Allowed: 9:00 AM – 9:00 PM IST.
+     * Uses Intl.DateTimeFormat only — no date-fns or dayjs dependency.
+     *
+     * @param at        Time to check. Defaults to now.
+     * @param timezone  IANA timezone. Defaults to 'Asia/Kolkata'.
+     *
+     * @example
+     * ```ts
+     * trai.isWithinCallingHours()            // Check now
+     * trai.isWithinCallingHours(new Date())  // Explicit time
+     * ```
+     */
+    isWithinCallingHours(at?: Date, timezone?: string): boolean;
+    /**
+     * Record explicit consent from a user for future calls.
+     * Consent is valid for 180 days per TRAI guidelines.
+     *
+     * @param params  Consent record details
+     *
+     * @example
+     * ```ts
+     * await trai.recordConsent({
+     *   phoneNumber: '+919876543210',
+     *   consentedAt: new Date(),
+     *   channel: 'ivr',
+     *   purpose: 'PROMOTIONAL',
+     * })
+     * ```
+     */
+    recordConsent(params: ConsentRecord): Promise<void>;
+    /**
+     * Check if a number has valid (non-expired) consent on record.
+     *
+     * @param phoneNumber  E.164 phone number
+     * @returns            True if valid consent exists
+     */
+    hasValidConsent(phoneNumber: string): Promise<boolean>;
+    /**
+     * Fetch DNC status from TRAI DND API.
+     * @internal
+     */
+    private fetchDNCStatus;
+}
+
+/**
+ * @voice-kit/core — LRU-backed call memory
+ *
+ * Provides a sliding window of conversation turns per call.
+ * Uses lru-cache for bounded in-process storage — no Redis, no DB.
+ * Every cache has explicit max size and TTL to prevent unbounded growth.
+ */
+
+/**
+ * Create an LRU-backed call memory instance.
+ * This is the ONLY in-process memory system in the SDK.
+ *
+ * @param config  Memory configuration
+ *
+ * @example
+ * ```ts
+ * // Default: 20 turns, 512KB, 30min TTL
+ * const memory = createCallMemory()
+ *
+ * // Custom
+ * const memory = createCallMemory({ maxTurns: 30, maxBytes: 1_000_000 })
+ * ```
+ */
+declare function createCallMemory(config?: CallMemoryConfig): CallMemory;
+
+/**
+ * @voice-kit/core — CallMetrics
+ *
+ * Records per-call performance metrics: TTFB, turn latency, token cost, interruption rate.
+ * In-process LRU storage — exported via getCallSummary().
+ */
+
+/**
+ * Per-call performance metrics recorder.
+ *
+ * @example
+ * ```ts
+ * const metrics = new CallMetrics()
+ * metrics.recordSTTFirstByte(callId, 180)
+ * metrics.recordTurnLatency(callId, 340)
+ * const summary = metrics.getCallSummary(callId)
+ * console.log(summary.avgTurnLatencyMs) // 340
+ * ```
+ */
+declare class CallMetrics {
+    private readonly store;
+    constructor();
+    private getOrCreate;
+    /** Record time from audio start to first STT partial result. */
+    recordSTTFirstByte(callId: string, ms: number): void;
+    /** Record time from TTS request to first audio chunk. */
+    recordTTSFirstByte(callId: string, ms: number): void;
+    /** Record time from LLM request to first token. */
+    recordLLMFirstToken(callId: string, ms: number): void;
+    /**
+     * Record end-to-end turn latency: speech_end → first TTS audio byte.
+     * This is the primary latency metric for voice agent quality.
+     */
+    recordTurnLatency(callId: string, ms: number): void;
+    /**
+     * Record an interruption event.
+     *
+     * @param callId       Call identifier
+     * @param positionPct  0–1, how far through the TTS stream the interruption occurred
+     */
+    recordInterruption(callId: string, positionPct: number): void;
+    /** Record token usage and estimated cost for a model call. */
+    recordTokenCost(callId: string, model: string, inputTokens: number, outputTokens: number): void;
+    /**
+     * Get a full summary of metrics for a call.
+     *
+     * @param callId  The call identifier
+     * @returns       Aggregated metrics summary
+     */
+    getCallSummary(callId: string): CallMetricsSummary;
+    /** Remove metrics for a call. Call on call.ended to free memory. */
+    clearCall(callId: string): void;
+}
+
+/**
+ * @voice-kit/core — OpenTelemetry tracing
+ *
+ * VoiceSDKTracer: wraps every external provider call with OTel spans.
+ * Auto-exports to OTLP endpoint if OTEL_EXPORTER_OTLP_ENDPOINT is set.
+ */
+/**
+ * OpenTelemetry tracer for VoiceKit. Wraps every external I/O with spans.
+ *
+ * @example
+ * ```ts
+ * const tracer = new VoiceSDKTracer()
+ * const result = await tracer.traceSTT(
+ *   () => stt.transcribeBatch(audio),
+ *   { provider: 'deepgram', language: 'en-IN' }
+ * )
+ * ```
+ */
+declare class VoiceSDKTracer {
+    private readonly tracer;
+    constructor();
+    /**
+     * Trace an STT operation with provider + language attributes.
+     */
+    traceSTT<T>(fn: () => Promise<T>, attrs: {
+        provider: string;
+        language: string;
+        callId?: string;
+    }): Promise<T>;
+    /**
+     * Trace a TTS synthesis operation.
+     */
+    traceTTS<T>(fn: () => Promise<T>, attrs: {
+        provider: string;
+        voice: string;
+        chars: number;
+        callId?: string;
+    }): Promise<T>;
+    /**
+     * Trace an LLM generation call.
+     */
+    traceLLM<T>(fn: () => Promise<T>, attrs: {
+        model: string;
+        inputTokens: number;
+        callId?: string;
+    }): Promise<T>;
+    /**
+     * Trace a full call lifecycle.
+     */
+    traceCall<T>(fn: () => Promise<T>, attrs: {
+        callId: string;
+        direction: 'inbound' | 'outbound';
+    }): Promise<T>;
+    /**
+     * Trace a single conversation turn.
+     */
+    traceTurn<T>(fn: () => Promise<T>, attrs: {
+        turnIndex: number;
+        callId: string;
+    }): Promise<T>;
+    /** Generic span wrapper. @internal */
+    private withSpan;
+}
+
+/**
+ * @voice-kit/core — AssemblyAI STT Provider
+ *
+ * Async long-form transcription using AssemblyAI SDK.
+ * Best for post-call recordings, meeting notes, long interviews.
+ * Does not support realtime streaming — use Deepgram for live calls.
+ */
+
+/**
+ * AssemblyAI async transcription provider.
+ * @internal — obtained via createSTT('assemblyai', config)
+ */
+declare class AssemblyAISTTProvider implements STTProvider {
+    readonly name = "assemblyai";
+    readonly supportsStreaming = false;
+    readonly supportedLanguages: string[];
+    private readonly client;
+    private readonly config;
+    constructor(config: STTConfig);
+    /**
+     * Batch-transcribes collected audio. AssemblyAI has no realtime streaming.
+     * Collects all audio from the iterable, uploads, then polls for result.
+     *
+     * @param audio  Async iterable of PCM buffers
+     */
+    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
+    /**
+     * Upload audio to AssemblyAI and wait for async transcription.
+     * Suitable for call recordings. Average latency: 15–45s per minute of audio.
+     *
+     * @param audio  Raw WAV/PCM/MP3 buffer
+     *
+     * @example
+     * ```ts
+     * const stt = createSTT('assemblyai', { wordTimestamps: true })
+     * const result = await stt.transcribeBatch(recordingBuffer)
+     * console.log(result.words) // Word-level timestamps
+     * ```
+     */
+    transcribeBatch(audio: Buffer): Promise<STTResult>;
+}
+
+/**
+ * @voice-kit/core — Deepgram Nova-3 STT Provider
+ *
+ * Streaming STT using Deepgram Nova-3. Handles WebSocket reconnect with
+ * exponential backoff, interim + final results, language detection.
+ * Never instantiate directly — use createSTT('deepgram', config).
+ *
+ * SDK: @deepgram/sdk v5 (beta) — https://github.com/deepgram/deepgram-js-sdk
+ */
+
+/**
+ * Deepgram Nova-3 streaming STT provider.
+ * @internal — obtained via createSTT('deepgram', config)
+ */
+declare class DeepgramSTTProvider implements STTProvider {
+    readonly name = "deepgram";
+    readonly supportsStreaming = true;
+    readonly supportedLanguages: string[];
+    private readonly client;
+    private readonly config;
+    constructor(config: STTConfig);
+    /**
+     * Stream audio to Deepgram and receive interim + final transcription results.
+     * Handles reconnection transparently with exponential backoff.
+     *
+     * @param audio  Async iterable of 16kHz PCM buffers from AudioPipeline
+     *
+     * @example
+     * ```ts
+     * const stt = createSTT('deepgram', { language: 'hi-IN' })
+     * for await (const result of stt.transcribeStream(audioIterable)) {
+     *   if (result.isFinal) console.log('User said:', result.transcript)
+     * }
+     * ```
+     */
+    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
+    /**
+     * Transcribe a complete audio buffer (non-streaming).
+     * Uses Deepgram pre-recorded API.
+     *
+     * @param audio  Raw PCM or WAV buffer
+     */
+    transcribeBatch(audio: Buffer): Promise<STTResult>;
+    /**
+     * Create and open a live WebSocket connection to Deepgram.
+     *
+     * v5 connection lifecycle (3 explicit steps):
+     *   1. await listen.v1.connect(options)  — constructs the connection object
+     *   2. connection.connect()              — initiates the WebSocket handshake
+     *   3. await connection.waitForOpen()    — resolves once the socket is ready
+     *
+     * @internal
+     */
+    private connectWithRetry;
+}
+
+/**
+ * @voice-kit/core — Sarvam AI Indic STT Provider
+ *
+ * Sarvam AI provides state-of-the-art STT for Indian languages:
+ * hi-IN, kn-IN, ta-IN, te-IN, mr-IN, bn-IN, gu-IN, pa-IN, or-IN
+ *
+ * Uses axios for HTTP calls. No official JS SDK — we use the REST API directly.
+ */
+
+/**
+ * Sarvam AI Indic STT provider.
+ * @internal — obtained via createSTT('sarvam', config)
+ */
+declare class SarvamSTTProvider implements STTProvider {
+    readonly name = "sarvam";
+    readonly supportsStreaming = false;
+    readonly supportedLanguages: string[];
+    private readonly http;
+    private readonly config;
+    constructor(config: STTConfig);
+    /**
+     * Collects audio and transcribes via Sarvam batch API.
+     * Sarvam doesn't support realtime streaming.
+     *
+     * @param audio  Async iterable of 16kHz PCM buffers
+     */
+    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
+    /**
+     * Transcribe a WAV/PCM audio buffer in an Indic language.
+     *
+     * @param audio  16kHz PCM or WAV buffer
+     *
+     * @example
+     * ```ts
+     * const stt = createSTT('sarvam', { language: 'ta-IN' })
+     * const result = await stt.transcribeBatch(tamilAudioBuffer)
+     * console.log(result.transcript) // Tamil text
+     * ```
+     */
+    transcribeBatch(audio: Buffer): Promise<STTResult>;
+}
+
+/**
+ * @voice-kit/core — Hinglish language switch detector
+ *
+ * Detects mid-sentence Hindi↔English (Hinglish) code-switching in realtime STT output.
+ * Pure algorithmic detection — no external API calls, no latency overhead.
+ *
+ * Detection signals:
+ *   1. Devanagari Unicode range (U+0900–U+097F) for Hindi
+ *   2. Latin character runs for English
+ *   3. Common Hinglish transition patterns (e.g. "main think karta hun")
+ *   4. Script boundary crossing mid-sentence
+ */
+
+type LanguageCode = 'hi-IN' | 'en-IN' | 'unknown';
+interface LanguageSwitchEvent {
+    /** Language switched from. */
+    from: LanguageCode;
+    /** Language switched to. */
+    to: LanguageCode;
+    /** Position in transcript where switch occurred (word index). */
+    position: number;
+    /** Confidence of the detection 0–1. */
+    confidence: number;
+    /** Full transcript at time of detection. */
+    transcript: string;
+    /** Timestamp of detection. */
+    detectedAt: Date;
+}
+type LanguageDetectorEventMap = {
+    'language.switched': [LanguageSwitchEvent];
+};
+/**
+ * Hinglish language switch detector.
+ *
+ * Analyzes STT transcripts word-by-word in realtime.
+ * Emits 'language.switched' events when a significant script change is detected.
+ *
+ * @example
+ * ```ts
+ * const detector = new LanguageSwitchDetector('en-IN')
+ * detector.on('language.switched', ({ from, to, transcript }) => {
+ *   console.log(`Language switched: ${from} → ${to} in: "${transcript}"`)
+ * })
+ *
+ * // Call on every STT final result
+ * detector.analyze('main yeh kaam kal karonga I promise')
+ * ```
+ */
+declare class LanguageSwitchDetector extends EventEmitter<LanguageDetectorEventMap> {
+    private currentLanguage;
+    private readonly primaryLanguage;
+    /** Rolling window of recent language classifications for smoothing. */
+    private recentClassifications;
+    private readonly windowSize;
+    constructor(primaryLanguage?: LanguageCode);
+    /**
+     * Analyze a transcript for language switches.
+     * Should be called on every STT final result.
+     *
+     * @param transcript  The transcribed text to analyze
+     * @returns           Detected language of the transcript
+     */
+    analyze(transcript: string): LanguageCode;
+    /**
+     * Analyze a transcript and return per-word language classification.
+     * Useful for word-level Hinglish mixing visualization.
+     *
+     * @param transcript  Text to analyze
+     * @returns           Array of { word, language } pairs
+     */
+    analyzeWords(transcript: string): Array<{
+        word: string;
+        language: LanguageCode;
+    }>;
+    /** Reset to primary language (e.g., on new call). */
+    reset(): void;
+    /** Current detected language. */
+    get language(): LanguageCode;
+    private tokenize;
+    private classifyWord;
+    private classifySegment;
+    private computeConfidence;
+    private smoothedLanguage;
+}
+/**
+ * Detect whether a transcript contains mixed Hindi+English (Hinglish).
+ * Stateless convenience function for one-shot analysis.
+ *
+ * @param transcript  Text to analyze
+ * @returns           True if both Devanagari and Latin characters are present
+ *
+ * @example
+ * ```ts
+ * isHinglish('main kal office jaaunga') // true
+ * isHinglish('I will go to the office')  // false
+ * isHinglish('मैं कल ऑफिस जाऊंगा')       // false (pure Hindi)
+ * ```
+ */
+declare function isInglish(transcript: string): boolean;
+
+/**
+ * @voice-kit/core — STT factory
+ *
+ * createSTT() is the ONLY public API for speech-to-text.
+ * Never instantiate provider classes directly.
+ */
+
+/**
+ * Create an STT provider instance. This is the ONLY public API for STT.
+ *
+ * Provider selection guide:
+ * - 'deepgram'   → Default. Realtime streaming, best latency, supports en-IN + Indic
+ * - 'sarvam'     → Best accuracy for pure Indic languages (hi-IN, ta-IN, kn-IN, te-IN, mr-IN)
+ * - 'assemblyai' → Best for long-form recordings (post-call analysis)
+ * - 'whisper'    → Fallback batch transcription, broad language support
+ *
+ * @example
+ * ```ts
+ * // Realtime English (India) — default
+ * const stt = createSTT('deepgram', { language: 'en-IN' })
+ *
+ * // Realtime Hindi
+ * const stt = createSTT('deepgram', { language: 'hi-IN' })
+ *
+ * // Best Indic accuracy
+ * const stt = createSTT('sarvam', { language: 'ta-IN' })
+ *
+ * // Post-call recording
+ * const stt = createSTT('assemblyai', { wordTimestamps: true })
+ * ```
+ */
+declare function createSTT(provider: 'deepgram' | 'whisper' | 'assemblyai' | 'sarvam', config?: STTConfig): STTProvider;
+
+/**
+ * @voice-kit/core — OpenAI Whisper STT Provider (batch fallback)
+ *
+ * Uses @ai-sdk/openai for batch transcription. Does not support streaming.
+ * Use as fallback for long-form audio or when Deepgram is unavailable.
+ */
+
+/**
+ * OpenAI Whisper STT provider. Batch-only — does not support streaming.
+ * @internal — obtained via createSTT('whisper', config)
+ */
+declare class WhisperSTTProvider implements STTProvider {
+    readonly name = "whisper";
+    readonly supportsStreaming = false;
+    readonly supportedLanguages: string[];
+    private readonly config;
+    constructor(config: STTConfig);
+    /**
+     * Streaming not supported by Whisper. Collects all audio then transcribes.
+     * For realtime use, use createSTT('deepgram') instead.
+     */
+    transcribeStream(audio: AsyncIterable<Buffer>): AsyncIterable<STTResult>;
+    /**
+     * Transcribe a complete audio buffer via Whisper.
+     *
+     * @param audio  WAV or PCM buffer
+     */
+    transcribeBatch(audio: Buffer): Promise<STTResult>;
+}
+
+/**
+ * @voice-kit/core — Cartesia TTS Provider
+ *
+ * Ultra-low-latency streaming TTS via @cartesia/cartesia-js.
+ * Target first chunk: < 90ms. Best for latency-critical applications.
+ */
+
+/**
+ * Cartesia ultra-low-latency TTS provider.
+ * @internal — obtained via createTTS('cartesia', config)
+ */
+declare class CartesiaTTSProvider implements TTSProvider {
+    readonly name = "cartesia";
+    readonly outputSampleRate = 22050;
+    readonly outputFormat: "pcm";
+    private readonly client;
+    private readonly config;
+    constructor(config: TTSConfig);
+    /**
+     * Stream audio from Cartesia. Typically delivers first chunk in < 90ms.
+     *
+     * @example
+     * ```ts
+     * const tts = createTTS('cartesia', { voiceId: 'your-voice-id' })
+     * for await (const chunk of tts.synthesizeStream('Hello!')) {
+     *   sendToTelephony(chunk)
+     * }
+     * ```
+     */
+    synthesizeStream(text: string, config?: TTSConfig): AsyncIterable<Buffer>;
+    /** Synthesize complete audio. */
+    synthesizeFull(text: string, config?: TTSConfig): Promise<Buffer>;
+}
+
+/**
+ * @voice-kit/core — ElevenLabs TTS Provider
+ *
+ * Streaming TTS using ElevenLabs SDK. Features:
+ * - 100ms lookahead jitter buffer to smooth burst delivery
+ * - Voice clone support
+ * - Sub-300ms first chunk target
+ */
+
+/**
+ * ElevenLabs streaming TTS provider.
+ * @internal — obtained via createTTS('elevenlabs', config)
+ */
+declare class ElevenLabsTTSProvider implements TTSProvider {
+    readonly name = "elevenlabs";
+    readonly outputSampleRate = 24000;
+    readonly outputFormat: "pcm";
+    private readonly client;
+    private readonly config;
+    constructor(config: TTSConfig);
+    /**
+     * Stream synthesized audio from ElevenLabs.
+     * First chunk target: < 300ms. Uses streaming API endpoint.
+     *
+     * A 100ms jitter buffer smooths burst packet delivery without adding
+     * perceptible latency.
+     *
+     * @param text    Text to synthesize (should be a sentence boundary chunk)
+     * @param config  Per-call config overrides
+     *
+     * @example
+     * ```ts
+     * const tts = createTTS('elevenlabs', { voiceId: 'your-voice-id' })
+     * for await (const chunk of tts.synthesizeStream('Hello, how can I help?')) {
+     *   telephony.sendAudio(chunk)
+     * }
+     * ```
+     */
+    synthesizeStream(text: string, config?: TTSConfig): AsyncIterable<Buffer>;
+    /**
+     * Synthesize full audio (for pre-caching greetings, IVR prompts).
+     * Collects all streaming chunks into a single buffer.
+     *
+     * @param text    Text to synthesize
+     * @param config  Per-call config overrides
+     */
+    synthesizeFull(text: string, config?: TTSConfig): Promise<Buffer>;
+}
+
+/**
+ * @voice-kit/core — Sarvam AI TTS Provider
+ *
+ * Sarvam AI TTS for Hindi/Hinglish and regional Indian languages.
+ * Supports natural-sounding Indian voices with regional accents.
+ */
+
+/**
+ * Sarvam AI TTS provider for Indic languages.
+ * @internal — obtained via createTTS('sarvam', config)
+ */
+declare class SarvamTTSProvider implements TTSProvider {
+    readonly name = "sarvam";
+    readonly outputSampleRate = 22050;
+    readonly outputFormat: "mp3";
+    private readonly http;
+    private readonly config;
+    constructor(config: TTSConfig);
+    /**
+     * Synthesize text in an Indic language and stream audio chunks.
+     * Sarvam returns full audio segments — we chunk them for streaming compatibility.
+     *
+     * @example
+     * ```ts
+     * const tts = createTTS('sarvam', { targetLanguage: 'hi-IN' })
+     * for await (const chunk of tts.synthesizeStream('नमस्ते, मैं आपकी कैसे मदद कर सकता हूँ?')) {
+     *   telephony.sendAudio(chunk)
+     * }
+     * ```
+     */
+    synthesizeStream(text: string, config?: TTSConfig): AsyncIterable<Buffer>;
+    /** Synthesize complete audio buffer. */
+    synthesizeFull(text: string, config?: TTSConfig): Promise<Buffer>;
+}
+
+/**
+ * @voice-kit/core — TTS factory
+ *
+ * createTTS() is the ONLY public API for text-to-speech.
+ * Never instantiate provider classes directly.
+ */
+
+/**
+ * Create a TTS provider instance.
+ *
+ * Provider selection guide:
+ * - 'elevenlabs'  → Best voice quality, cloning support, en-IN
+ * - 'cartesia'    → Lowest latency (< 90ms TTFB), good for fast-paced agents
+ * - 'sarvam'      → Best for Indic languages (hi-IN, ta-IN, kn-IN, te-IN, mr-IN)
+ *
+ * @example
+ * ```ts
+ * // English with voice cloning
+ * const tts = createTTS('elevenlabs', { voiceId: 'your-cloned-voice-id' })
+ *
+ * // Ultra-low latency English
+ * const tts = createTTS('cartesia', { voiceId: 'your-voice-id' })
+ *
+ * // Hindi
+ * const tts = createTTS('sarvam', { targetLanguage: 'hi-IN', voiceId: 'meera' })
+ * ```
+ */
+declare function createTTS(provider: 'elevenlabs' | 'cartesia' | 'sarvam', config?: TTSConfig): TTSProvider;
+
+export { AgentError, AgentHandoffError, AssemblyAISTTProvider, AudioPipeline, AudioTransportError, type AuditEntry, type AuditEventType, CallAuditLog, CallConnectionError, type CallMemory, type CallMemoryConfig, CallMetrics, type CallMetricsSummary, CallNotFoundError, type CallPurpose, CallingHoursError, CartesiaTTSProvider, ComplianceError, ConsentMissingError, type ConsentRecord, DNCBlockedError, type DNCCheckParams, type DNCCheckResult, DeepgramSTTProvider, ElevenLabsTTSProvider, type ErrorSeverity, InngestError, type LanguageCode, LanguageSwitchDetector, type LanguageSwitchEvent, type STTConfig, STTConnectionError, STTError, STTLanguageNotSupportedError, type STTProvider, type STTResult, STTStreamError, SarvamSTTProvider, SarvamTTSProvider, TRAICompliance, type TRAIConfig, type TTSConfig, TTSConnectionError, TTSError, type TTSProvider, TTSStreamError, TTSVoiceNotFoundError, TelephonyError, type TelephonyProviderName, TurnTransitionError, type VADConfig, VADEngine, type VoiceFrame, VoiceKitError, type VoiceKitErrorContext, VoiceSDKTracer, WhisperSTTProvider, type WordTimestamp, base64MulawToPcm, createAudioPipeline, createCallMemory, createResamplerStream, createSTT, createTTS, createVAD, isInglish, linearToMulaw, mulawBufferToPcm, mulawToLinear, pcmBufferToMulaw, pcmToBase64Mulaw, resample, resampleStream };