@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/dist/services/voice/vad.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Voice activity detection — the audio front-end's two-tier gate.
+ *
+ *   Tier 1 — `RmsEnergyGate`. A frame-level RMS threshold with hysteresis.
+ *            Sub-frame latency, no model. Its rising edge is the "wake the
+ *            response pipeline" signal (KV-prefill the response prompt,
+ *            preload the drafter, pre-generate the first filler). It NEVER
+ *            substitutes for the model VAD — it only decides "is there
+ *            acoustic activity right now".
+ *
+ *   Tier 2 — a model VAD provider. Resolver order is an optional injected
+ *            external VAD adapter when supplied, otherwise the fused
+ *            `libelizainference` Silero v5 VAD ABI (`eliza_inference_vad_*`,
+ *            backend id `silero-ggml`). 512-sample windows at 16 kHz (32 ms
+ *            hop), one speech probability per window. This is the
+ *            *authoritative* speech/no-speech signal — it gates ASR and drives
+ *            turn-taking. The fused engine is the sole on-device VAD runtime;
+ *            there is no standalone VAD library.
+ *
+ *   `VadDetector` wires both together and emits the `VadEvent` stream
+ *   (`speech-start` / `speech-active` / `speech-pause` / `speech-end` /
+ *   `blip`) plus the raw `EnergyGateEvent` stream.
+ *
+ * No fallback sludge: if the fused VAD ABI is unavailable (and no injected
+ * adapter is supplied), `createVadDetector()` throws `VadUnavailableError`. The
+ * caller surfaces "VAD unavailable — voice features degrade" — there is no
+ * silent downgrade to the RMS gate, and no standalone-library fallback
+ * (AGENTS.md §3).
+ */
+import type { ElizaInferenceContextHandle, ElizaInferenceFfi } from "./ffi-bindings";
+import type { EnergyGateListener, PcmFrame, VadEventListener } from "./types";
+/** Thrown when the Silero VAD backend cannot be loaded — the native VAD FFI
+ *  is missing or ABI-only, the model file is absent, or the model is corrupt.
+ *  There is no fallback; voice features that depend on VAD must surface
+ *  this. */
+export declare class VadUnavailableError extends Error {
+    readonly code: "ffi-missing" | "model-missing" | "model-load-failed" | "provider-missing";
+    constructor(code: VadUnavailableError["code"], message: string);
+}
+/**
+ * Resolve the fused-libelizainference Silero GGML VAD model on disk. An
+ * explicit `modelPath` is honored exactly — if it is set but missing, the
+ * result is `null` (no silent substitution of a different model). When
+ * `modelPath` is not given the search order is:
+ *   1. `<bundleRoot>/vad/silero-vad-v5.1.2.ggml.bin`
+ *   2. `<bundleRoot>/vad/silero-vad-v5.gguf`
+ *   3. `<state-dir>/local-inference/vad/<same filenames>`
+ *   3. `$ELIZA_VAD_MODEL_PATH`
+ * Returns `null` when none exist.
+ */
+export declare function resolveSileroVadPath(opts: {
+    modelPath?: string;
+    bundleRoot?: string;
+}): string | null;
+/**
+ * Fused libelizainference-backed Silero v5 GGML VAD — the sole on-device VAD
+ * runtime. The model (`silero-vad-v5.1.2.ggml.bin`) is loaded by the shared
+ * ggml context owned by the FFI; `process()` runs one 512-sample 16 kHz window
+ * through the native VAD and returns the speech probability. `reset()` clears
+ * the recurrent state at utterance boundaries.
+ */
+export declare class GgmlSileroVad {
+    private readonly ffi;
+    private readonly handle;
+    readonly sampleRate: number;
+    readonly windowSamples = 512;
+    private closed;
+    private constructor();
+    /** True when the libelizainference build exports the native VAD ABI and
+     *  advertises support. False on ABI-only builds or when the C++ side has
+     *  not been linked against the GGML Silero VAD runtime. */
+    static isSupported(ffi: ElizaInferenceFfi | null | undefined): boolean;
+    static load(opts: {
+        ffi: ElizaInferenceFfi;
+        ctx: ElizaInferenceContextHandle | (() => ElizaInferenceContextHandle);
+        sampleRate?: number;
+    }): Promise<GgmlSileroVad>;
+    process(window: Float32Array): Promise<number>;
+    reset(): void;
+    close(): void;
+}
+/** @deprecated Use `GgmlSileroVad`. Kept as an alias while callers migrate
+ *  off the legacy ONNX-era name. */
+export declare const NativeSileroVad: typeof GgmlSileroVad;
+export type NativeSileroVad = GgmlSileroVad;
+export interface RmsEnergyGateConfig {
+    /** RMS above this counts as activity. Default 0.012 — between the 0.01 the
+     *  vision capture stream uses and the 0.05 Discord uses for speaking. */
+    riseThreshold?: number;
+    /** RMS must drop below this to count as quiet (hysteresis). Default
+     *  `0.6 * riseThreshold`. */
+    fallThreshold?: number;
+    /** Consecutive ms below `fallThreshold` before emitting `energy-fall`.
+     *  Default 200 ms. */
+    fallHoldMs?: number;
+}
+export declare function rms(pcm: Float32Array): number;
+/**
+ * Hysteretic RMS gate. Feed it `PcmFrame`s; it emits `energy-rise` on the
+ * first frame above `riseThreshold` and `energy-fall` after RMS has been
+ * below `fallThreshold` for `fallHoldMs`. This is the fast pre-warm trigger
+ * — not a speech detector.
+ */
+export declare class RmsEnergyGate {
+    private readonly riseThreshold;
+    private readonly fallThreshold;
+    private readonly fallHoldMs;
+    private active;
+    private quietSinceMs;
+    private readonly listeners;
+    constructor(config?: RmsEnergyGateConfig);
+    get isActive(): boolean;
+    onEvent(listener: EnergyGateListener): () => void;
+    /** Returns the frame RMS so callers can reuse it. */
+    push(frame: PcmFrame): number;
+    reset(): void;
+    private emit;
+}
+export interface VadDetectorConfig {
+    /** Mic sample rate (Hz). MUST be 16 000 — Silero v5 is 16 kHz only. */
+    sampleRate?: number;
+    /** Speech probability above this opens a speech segment. Default 0.5. */
+    onsetThreshold?: number;
+    /** Speech probability must drop below this to count toward end-of-speech.
+     *  Default `onsetThreshold - 0.15`. Below the onset to avoid flapping. */
+    offsetThreshold?: number;
+    /** Consecutive ms of speech-prob below `offsetThreshold` before the
+     *  segment is considered *paused* (kick speculative response). Default
+     *  100 ms (lowered from 220ms; further reduction gated on semantic EOT
+     *  classifier V2). Override via `ELIZA_PAUSE_HANGOVER_MS`. */
+    pauseHangoverMs?: number;
+    /**
+     * V1 — "fast endpoint" pause hangover, used when `fastEndpointEnabled`
+     * is true. Default 100 ms — short enough that a clean trailing-off
+     * end-of-utterance hits the speculative path quickly, but long enough
+     * to ride out mid-sentence micro-pauses. Gated by the flag so callers
+     * can opt in once they've validated the false-positive rate on their
+     * hardware. Default 100 ms.
+     */
+    fastPauseHangoverMs?: number;
+    /**
+     * V1 — when true, use `fastPauseHangoverMs` instead of `pauseHangoverMs`.
+     * Default false until the streaming-ASR fast path (V2) ships.
+     */
+    fastEndpointEnabled?: boolean;
+    /** Consecutive ms paused before the segment *ends* (finalize the turn).
+     *  Default 700 ms. Must be ≥ `pauseHangoverMs`. */
+    endHangoverMs?: number;
+    /** A segment shorter than this (from onset to end) is reclassified as a
+     *  `blip` rather than `speech-end`. Default 250 ms. */
+    minSpeechMs?: number;
+    /** Interval between `speech-active` heartbeats while speaking. Default
+     *  200 ms. */
+    activeHeartbeatMs?: number;
+    /**
+     * V4 — adaptive pause hangover. When the windowed RMS is in a sharp
+     * downward trend across the last few frames (the user audibly trailed
+     * off rather than stopping mid-thought), the hangover used to detect a
+     * pause is scaled by this factor (clamped to a minimum). Default 0.5
+     * (halve the hangover); set to 1.0 to disable.
+     */
+    adaptiveHangoverScaleOnDrop?: number;
+    /**
+     * V4 — minimum hangover the adaptive scale is allowed to produce, ms.
+     * Default 50 ms. Prevents a steep drop from collapsing the hangover to
+     * zero and emitting a pause on a single quiet frame.
+     */
+    adaptiveHangoverFloorMs?: number;
+    /**
+     * V4 — energy derivative (ΔRMS over the V4 history window) below this
+     * value, combined with RMS below `offsetThreshold`, counts as "audibly
+     * trailed off". Default -0.02 (negative slope: RMS dropping at least
+     * 0.02 / window).
+     */
+    adaptiveHangoverDropThreshold?: number;
+    /** RMS gate config (tier 1). */
+    energyGate?: RmsEnergyGateConfig;
+}
+export type { VadLike } from "./types.js";
+import type { VadLike } from "./types.js";
+export type VadProviderId = "external-vad" | "silero-ggml";
+export type VadProviderPreference = "auto" | VadProviderId;
+export interface ExternalVadAdapter {
+    isAvailable?(): boolean | Promise<boolean>;
+    loadVad(opts: {
+        sampleRate: number;
+    }): Promise<VadLike>;
+}
+export interface ResolvedVadProvider {
+    id: VadProviderId;
+    vad: VadLike;
+}
+export interface CreateVadDetectorOptions {
+    modelPath?: string;
+    bundleRoot?: string;
+    ffi?: ElizaInferenceFfi | null;
+    ctx?: ElizaInferenceContextHandle | (() => ElizaInferenceContextHandle);
+    externalVad?: ExternalVadAdapter | null;
+    config?: VadDetectorConfig;
+    prefer?: VadProviderPreference;
+}
+export declare function vadProviderOrder(prefer?: VadProviderPreference): VadProviderId[];
+export declare function resolveVadProvider(opts?: CreateVadDetectorOptions): Promise<ResolvedVadProvider>;
+/**
+ * The authoritative VAD. Owns a model VAD provider (or any `VadLike` for tests),
+ * an `RmsEnergyGate`, and the speech state machine. `pushFrame()` accepts
+ * mic frames of any length ≥ 1 sample; internally it re-windows to the
+ * provider's fixed sample window. Emits `VadEvent`s on the VAD timeline and
+ * `EnergyGateEvent`s on the fast timeline.
+ *
+ * Frame ingestion is serialized (`pushFrame` awaits the model forward pass)
+ * so events stay in order; callers that can't await may fire-and-forget — a
+ * dropped-frame counter (`droppedFrames`) records overruns.
+ */
+export declare class VadDetector {
+    readonly silero: VadLike;
+    readonly energyGate: RmsEnergyGate;
+    private readonly sampleRate;
+    private readonly onsetThreshold;
+    private readonly offsetThreshold;
+    private readonly pauseHangoverMs;
+    private readonly fastPauseHangoverMs;
+    private readonly fastEndpointEnabled;
+    private readonly endHangoverMs;
+    private readonly minSpeechMs;
+    private readonly activeHeartbeatMs;
+    private readonly adaptiveHangoverScaleOnDrop;
+    private readonly adaptiveHangoverFloorMs;
+    private readonly adaptiveHangoverDropThreshold;
+    private readonly recentRms;
+    private static readonly RECENT_RMS_HISTORY;
+    private readonly vadListeners;
+    private pending;
+    private windowDurationMs;
+    private clockMs;
+    private busy;
+    droppedFrames: number;
+    private phase;
+    private speechStartMs;
+    private lastSpeechMs;
+    private pauseStartedMs;
+    private lastHeartbeatMs;
+    private peakRmsInSegment;
+    constructor(silero: VadLike, config?: VadDetectorConfig);
+    /**
+     * Effective pause hangover for this window. Starts from
+     * `fastPauseHangoverMs` or `pauseHangoverMs` (V1: gated on
+     * `fastEndpointEnabled`), then optionally scales it down when the RMS
+     * trajectory shows an audible trail-off (V4).
+     */
+    private effectivePauseHangoverMs;
+    onVadEvent(listener: VadEventListener): () => void;
+    onEnergyEvent(listener: EnergyGateListener): () => void;
+    /** True while a speech segment (incl. its pause hangover) is open. */
+    get inSpeech(): boolean;
+    /**
+     * Feed a mic frame. Returns a promise that resolves once every full
+     * Silero window contained in (the accumulated buffer up to) this frame
+     * has been processed and its events emitted. The fast RMS gate fires
+     * synchronously before the await.
+     */
+    pushFrame(frame: PcmFrame): Promise<void>;
+    /** Flush any partial trailing samples (zero-padded to a full window) and
+     *  finalize an open segment. Call at end-of-stream. */
+    flush(): Promise<void>;
+    reset(): void;
+    private drainWindows;
+    private processWindow;
+    private endSegment;
+    private emit;
+}
+/**
+ * Back-compat wrapper for callers that still use the legacy
+ * `createSileroVadDetector` name. It now goes through the full provider
+ * resolver — same as `createVadDetector`.
+ */
+export declare function createSileroVadDetector(opts?: CreateVadDetectorOptions): Promise<VadDetector>;
+/**
+ * Convenience: resolve the best available model VAD provider and wrap it in a
+ * `VadDetector`.
+ */
+export declare function createVadDetector(opts?: CreateVadDetectorOptions): Promise<VadDetector>;
+//# sourceMappingURL=vad.d.ts.map

package/dist/services/voice/vad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vad.d.ts","sourceRoot":"","sources":["../../../src/services/voice/vad.ts"],"names":[],"mappings":"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"}

package/dist/services/voice/voice-budget.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Voice-budget allocator — single arbiter of the co-resident memory budget
+ * for the whole voice + text bundle (text LM, drafter, ASR, TTS, embedding,
+ * VAD, wake-word, turn-detector, emotion classifier, speaker encoder).
+ *
+ * Today's `ram-budget.ts` is per-tier: it decides whether ONE text bundle
+ * fits a host. `voice-budget.ts` is the cross-model layer the brief
+ * mandated in `.swarm/VOICE_WAVE_2.md` §H4 and R9 §4 — every model loader
+ * calls `reserve()` before it loads weights, releases on unload, and
+ * `reserve()` walks the residents under contention by eviction priority
+ * (cold → warm → hot) until the requested amount fits.
+ *
+ * Priorities (from R9 §4.1, mapped to `ResidentModelRole`):
+ *
+ *   - **hot**  (priority ≥ 40): `text-target`, `tts`, `asr` — never load
+ *     on demand, never evicted before pressure-of-last-resort.
+ *   - **warm** (priority 25–35): `vad`, `embedding` — may be evicted but
+ *     reload is expensive.
+ *   - **cold** (priority ≤ 20): `speaker-id` (18), `emotion` (15),
+ *     `vision` (20), `drafter` (10) — load-on-demand; first to evict.
+ *
+ * Eviction policy: walk ascending priority (cheapest first) until enough
+ * memory has been reclaimed. The text target evicts only when it is
+ * literally the only resident role and pressure persists (matches
+ * `SharedResourceRegistry.evictLowestPriorityRole` semantics).
+ *
+ * The allocator is **memory-only** — it does not load weights. The caller
+ * (TTS engine, ASR loader, etc.) holds the typed reservation and runs
+ * `release()` on unload.
+ *
+ * Wire-up plan (handed to follow-up commits, NOT done by I9):
+ *   - `ffi-streaming-backend.ts`     → `reserve(role="text-target")` + `reserve(role="drafter")` at spawn.
+ *   - `voice/pipeline.ts`    → `reserve(role="tts", bytes=transientPeakMb*MB)` per synth.
+ *   - `voice/wake-word.ts`, `vad.ts`, `eot-classifier.ts` → reserve at session arm.
+ *   - I2/I3 add `emotion` + `speaker-id` reservations when those models register.
+ *
+ * NOTE: the wire-up is intentionally separate from the allocator
+ * implementation because the in-flight I-agents (I1/I2/I3/I5) own those
+ * loader files and we must not race their edits. The allocator + the
+ * `evictionPriority` hooks are in place; the loaders adopt it as they
+ * land.
+ */
+import { type DeviceTier, type DeviceTierAssessment } from "../device-tier";
+import type { HardwareProbe } from "../types";
+import { type ResidentModelRole } from "./shared-resources";
+/** Coarse priority class consumed by `reserve()`. Internally we map this
+ *  back to the per-role priority number in `RESIDENT_ROLE_PRIORITY`. */
+export type AllocationPriority = "hot" | "warm" | "cold";
+export declare function priorityClassForRole(role: ResidentModelRole): AllocationPriority;
+export interface BudgetReservation {
+    readonly id: string;
+    readonly role: ResidentModelRole;
+    readonly bytes: number;
+    readonly priority: AllocationPriority;
+    /** Per-role priority number (R9 §4.1 / `RESIDENT_ROLE_PRIORITY`). */
+    readonly priorityRank: number;
+    /** Idempotent. Multi-release is a no-op (release happens from teardown
+     *  paths that may race). */
+    release(): void;
+}
+/** Diagnostic snapshot row for `VoiceBudget.snapshot()`. */
+export interface ReservationSnapshot {
+    id: string;
+    role: ResidentModelRole;
+    bytes: number;
+    priority: AllocationPriority;
+    priorityRank: number;
+}
+export declare class BudgetExhaustedError extends Error {
+    readonly code = "voice-budget-exhausted";
+    readonly details: {
+        requestedBytes: number;
+        freeBytes: number;
+        totalBytes: number;
+        role: ResidentModelRole;
+        priority: AllocationPriority;
+        evictedRoles: ReadonlyArray<ResidentModelRole>;
+        evictionCandidate: ResidentModelRole | null;
+    };
+    constructor(details: BudgetExhaustedError["details"]);
+}
+export interface VoiceBudget {
+    /**
+     * Reserve `bytes` for `modelId` with `priority`. Returns a handle the
+     * caller MUST `.release()` to give the memory back. Throws
+     * `BudgetExhaustedError` when the requested amount cannot fit even after
+     * evicting every available lower-priority reservation.
+     *
+     * `evictHook` is optional: when present, the allocator will call it for
+     * each role that needs to be evicted (one at a time, ascending priority)
+     * before recording the new reservation. When omitted, the allocator just
+     * walks its own internal table — the caller is expected to drive the
+     * actual weight unload (the loader/eviction path lives in the model's
+     * own service, not here).
+     */
+    reserve(args: {
+        modelId: string;
+        role: ResidentModelRole;
+        bytes: number;
+        /** Optional; defaults to `priorityClassForRole(role)`. */
+        priority?: AllocationPriority;
+        /** Optional eviction callback. When provided, called once per evicted
+         *  role in ascending-priority order before the new reservation is
+         *  recorded. The callback should drop the weights and return the
+         *  bytes actually reclaimed (must be >= the reservation's recorded
+         *  bytes). When omitted, the allocator only drops the internal
+         *  reservation entry (eviction-by-accounting). */
+        evictHook?: (role: ResidentModelRole, id: string) => Promise<number>;
+    }): Promise<BudgetReservation>;
+    /** Best-effort current free budget, in bytes. */
+    freeBytes(): number;
+    /** Total budget on this device, in bytes. */
+    totalBytes(): number;
+    /** All current reservations, ordered by priority ascending. */
+    snapshot(): ReadonlyArray<ReservationSnapshot>;
+    /** The tier this budget was sized to. */
+    tier(): DeviceTier;
+    /** The original assessment. */
+    assessment(): DeviceTierAssessment;
+}
+/**
+ * Co-resident voice-ensemble RSS estimate in MB. Sourced from R9 §2.3,
+ * keyed off the LM-tier slot (the text model that anchors the bundle).
+ *
+ * Each row is the steady-state weights + KV at default context for the
+ * whole voice + text bundle running at once:
+ *
+ *   LM + LM KV + drafter + TTS (omnivoice base + tokenizer or kokoro-q8) +
+ *   ASR + ASR mmproj + embedding + VAD + wake-word + turn-detector +
+ *   emotion classifier + speaker encoder.
+ *
+ * The `transientTtsBufferMb` field is the OmniVoice MaskGIT decode peak
+ * (~1.17 GB measured on Metal). Backends that don't run OmniVoice locally
+ * (kokoro-only, cloud TTS) have a much smaller transient — kept at 100 MB
+ * to leave room for kokoro's ONNX compute path. Mobile defaults to no
+ * local TTS, so transient = 0.
+ *
+ * The figures are MEASURED on-disk (Q4_K_M GGUFs in
+ * `<stateDir>/local-inference/models/eliza-1-2b.bundle/`) plus
+ * model-card sizes for VAD, wake-word, turn-detector, emotion, speaker-id.
+ * See R9 §2.1 + §2.2 + §2.3 for the per-component breakdown.
+ */
+export interface VoiceEnsembleBudget {
+    readonly tierSlot: VoiceTierSlot;
+    readonly lmMb: number;
+    readonly lmKvMb: number;
+    readonly drafterMb: number;
+    readonly ttsMb: number;
+    readonly asrMb: number;
+    readonly asrMmprojMb: number;
+    readonly embeddingMb: number;
+    readonly vadMb: number;
+    readonly wakeWordMb: number;
+    readonly turnDetectorMb: number;
+    readonly emotionMb: number;
+    readonly speakerEncoderMb: number;
+    readonly transientTtsBufferMb: number;
+    /** Sum of weights + KV (steady-state). Excludes transient TTS buffer. */
+    readonly steadyStateMb: number;
+    /** Sum of steady-state + transient TTS peak. */
+    readonly peakMb: number;
+}
+/**
+ * The voice ensemble's LM tier slot. We key the table off the LM size +
+ * the surrounding voice profile (mobile-cloud vs desktop-omnivoice) since
+ * the largest co-resident knob is the LM itself.
+ */
+export type VoiceTierSlot = "mobile-2b" | "desktop-2b" | "desktop-4b" | "workstation-9b" | "workstation-27b";
+/** R9 §2.3 — measured co-resident bundle for every supported tier slot. */
+export declare const VOICE_ENSEMBLE_BUDGETS: Readonly<Record<VoiceTierSlot, VoiceEnsembleBudget>>;
+/**
+ * Estimate the full voice ensemble's peak resident MB for a tier slot.
+ * `assertVoiceBundleFitsHost` consults this against the device's host RAM.
+ */
+export declare function voiceEnsemblePeakMb(slot: VoiceTierSlot): number;
+/** Sum of weights + KV (steady-state, excludes transient TTS buffer). */
+export declare function voiceEnsembleSteadyStateMb(slot: VoiceTierSlot): number;
+/**
+ * Pick the canonical voice-tier slot for an installed text model + device
+ * tier. The LM size anchors the slot (`eliza-1-2b` → `2b` (entry tier),
+ * `4b` → `4b`, …) and the device tier picks `mobile-` vs `desktop-` vs
+ * `workstation-` for the voice surrounding it. Mobile always pulls the
+ * `mobile-2b` slot because the brief defaults mobile to cloud TTS+ASR; only
+ * the 2B entry-tier local LM stays available there.
+ */
+export declare function pickVoiceTierSlot(args: {
+    textModelId: string;
+    deviceTier: DeviceTier;
+    mobile?: boolean;
+}): VoiceTierSlot;
+/**
+ * Decision returned by `assertVoiceBundleFitsHost`. Mirrors the shape of
+ * `RamFitDecision` in `ram-budget.ts` but at the bundle level.
+ */
+export interface VoiceBundleFitDecision {
+    tierSlot: VoiceTierSlot;
+    deviceTier: DeviceTier;
+    /** Steady-state weights + KV, MB. */
+    steadyStateMb: number;
+    /** Steady-state + transient TTS peak, MB. */
+    peakMb: number;
+    /** RAM available to the bundle (host MB - OS reserve). */
+    usableMb: number;
+    /** True iff `peakMb <= usableMb` AND `steadyStateMb <= usableMb`. */
+    fits: boolean;
+    /** "fits" when peak fits, "tight" when only steady-state fits, "wontfit"
+     *  when not even steady-state fits. */
+    level: "fits" | "tight" | "wontfit";
+}
+/** Default OS reserve subtracted from the host before the bundle check. */
+export declare const DEFAULT_VOICE_BUNDLE_RESERVE_MB = 1536;
+/**
+ * Decide whether the whole voice ensemble fits a host. Used by the runtime
+ * at voice-session-start to refuse local-voice entry rather than start it
+ * and watch `MemoryMonitor` evict the loaders mid-session.
+ *
+ * `assertVoiceBundleFitsHost` (in `active-model.ts`) wraps this with a
+ * typed error. This function returns the raw decision so callers that want
+ * to degrade silently can do so. R9 §1.4 spec.
+ */
+export declare function assessVoiceBundleFits(args: {
+    tierSlot: VoiceTierSlot;
+    deviceTier: DeviceTier;
+    hostRamMb: number;
+    reserveMb?: number;
+}): VoiceBundleFitDecision;
+/** Public factory. */
+export declare function createVoiceBudget(args: {
+    probe: HardwareProbe;
+    /** Optional user override for the budget cap, in MB. Default: tier
+     *  natural total. Clamped to the device's effective model memory. */
+    maxRamMb?: number;
+    /** Optional pre-computed assessment (avoid double classification). */
+    assessment?: DeviceTierAssessment;
+}): VoiceBudget;
+/** Test seam — construct a budget with explicit total bytes + assessment. */
+export declare function createVoiceBudgetForTest(args: {
+    totalBytes: number;
+    assessment: DeviceTierAssessment;
+}): VoiceBudget;
+//# sourceMappingURL=voice-budget.d.ts.map

package/dist/services/voice/voice-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-budget.d.ts","sourceRoot":"","sources":["../../../src/services/voice/voice-budget.ts"],"names":[],"mappings":"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"}

package/dist/services/voice/voice-emotion-classifier.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Voice-emotion types and pure projection functions — consumed by the
+ * attribution pipeline (`emotion-attribution.ts`).
+ *
+ * The ONNX-backed `VoiceEmotionClassifier` class was removed when
+ * `onnxruntime-node` was dropped. No resident voice-emotion classifier
+ * remains; only the pure types and projection helpers below are kept.
+ *
+ * Pure exports here:
+ *   - Model id constants (`WAV2SMALL_INT8_MODEL_ID`, etc.)
+ *   - Sample rate / window constants
+ *   - `VoiceEmotionVad`, `VoiceEmotionClassifierOutput` interfaces
+ *   - `VoiceEmotionHead` type
+ *   - `VoiceEmotionClassifierError` error class
+ *   - `projectVadToExpressiveEmotion` — V-A-D → ExpressiveEmotion projection
+ *   - `interpretCls7Output` — 7-class logit → structured output
+ */
+import { type ExpressiveEmotion } from "./expressive-tags";
+/** Stable identifier for the Wav2Small student head we ship. */
+export declare const WAV2SMALL_INT8_MODEL_ID: "wav2small-msp-dim-int8";
+/** Stable identifier for the floating-point parent we use in eval. */
+export declare const WAV2SMALL_FP32_MODEL_ID: "wav2small-msp-dim-fp32";
+export type VoiceEmotionModelId = typeof WAV2SMALL_INT8_MODEL_ID | typeof WAV2SMALL_FP32_MODEL_ID;
+/** Required sample rate for the Wav2Small log-mel front-end. */
+export declare const WAV2SMALL_SAMPLE_RATE = 16000;
+/** Hard minimum window: anything shorter is rejected. */
+export declare const WAV2SMALL_MIN_SAMPLES = 16000;
+/** Soft maximum window: longer inputs are truncated to the trailing window. */
+export declare const WAV2SMALL_MAX_SAMPLES: number;
+/** Raised when the bundled model file can not be loaded or run. */
+export declare class VoiceEmotionClassifierError extends Error {
+    constructor(message: string);
+}
+/** Continuous V-A-D output. All three are in [0, 1]. */
+export interface VoiceEmotionVad {
+    valence: number;
+    arousal: number;
+    dominance: number;
+}
+/** One classifier inference output. */
+export interface VoiceEmotionClassifierOutput {
+    vad: VoiceEmotionVad;
+    /** Projected discrete label, or null when no projection is confident. */
+    emotion: ExpressiveEmotion | null;
+    /** Confidence in the projected discrete label, [0, 1]. */
+    confidence: number;
+    /** Per-class soft scores aligned with `EXPRESSIVE_EMOTION_TAGS`. */
+    scores: Record<ExpressiveEmotion, number>;
+    /** Model id used for this inference (for the attribution evidence row). */
+    modelId: VoiceEmotionModelId;
+    /** Inference wall-time in ms (CPU side; useful for the bench harness). */
+    latencyMs: number;
+}
+/**
+ * Project a continuous V-A-D triple into the 7-class
+ * `ExpressiveEmotion` tag set. Returns soft scores per tag and the best
+ * discrete pick with a confidence score.
+ *
+ * The projection is Plutchik-aligned and deterministic. The thresholds
+ * are tuned against the MSP-Podcast V-A-D mean/std reported in the
+ * audeering model card and Wav2Small paper; small enough to be stable but
+ * wide enough to give every class some mass on conversational speech.
+ *
+ * Sign convention (audeering teacher, mirrored by Wav2Small):
+ *   valence    — high = positive affect (happy, calm), low = negative (sad, angry).
+ *   arousal    — high = energetic (excited, angry), low = subdued (calm, sad).
+ *   dominance  — high = assertive (angry), low = submissive (nervous, whisper).
+ */
+export declare function projectVadToExpressiveEmotion(vad: VoiceEmotionVad): {
+    emotion: ExpressiveEmotion | null;
+    confidence: number;
+    scores: Record<ExpressiveEmotion, number>;
+};
+/**
+ * Stable model-head identifier — declares whether the model emits
+ * V-A-D triples or 7-class logits. `vad` = continuous [valence, arousal,
+ * dominance]; `cls7` = 7-class logits in `EXPRESSIVE_EMOTION_TAGS` order.
+ */
+export type VoiceEmotionHead = "vad" | "cls7";
+/**
+ * Convert the 7-class logits from the `cls7` head into a structured
+ * emotion read. Applies a numerically-stable softmax (max-subtraction)
+ * over `EXPRESSIVE_EMOTION_TAGS` and selects the argmax.
+ *
+ * Confidence is the softmax probability of the picked class (in [0, 1]),
+ * which gives downstream consumers a calibrated mass to compare against
+ * the V-A-D-projection path's 0.35 abstain floor.
+ *
+ * The `vad` field is synthesised at the neutral midpoint (0.5, 0.5, 0.5).
+ * The cls7 head is the ground truth for the picked emotion — the V-A-D
+ * triple is left at neutral because we no longer regress to a V-A-D
+ * target. Consumers that need real V-A-D must use a `head=vad` model.
+ */
+export declare function interpretCls7Output(logits: Float32Array, modelId: VoiceEmotionModelId, latencyMs: number): VoiceEmotionClassifierOutput;
+//# sourceMappingURL=voice-emotion-classifier.d.ts.map

package/dist/services/voice/voice-emotion-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-emotion-classifier.d.ts","sourceRoot":"","sources":["../../../src/services/voice/voice-emotion-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEN,KAAK,iBAAiB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,EAAG,wBAAiC,CAAC;AACzE,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAG,wBAAiC,CAAC;AACzE,MAAM,MAAM,mBAAmB,GAC5B,OAAO,uBAAuB,GAC9B,OAAO,uBAAuB,CAAC;AAElC,gEAAgE;AAChE,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAC5C,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,QAAwB,CAAC;AAC3D,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,QAA6B,CAAC;AAEhE,mEAAmE;AACnE,qBAAa,2BAA4B,SAAQ,KAAK;gBACzC,OAAO,EAAE,MAAM;CAI3B;AAED,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,uCAAuC;AACvC,MAAM,WAAW,4BAA4B;IAC5C,GAAG,EAAE,eAAe,CAAC;IACrB,yEAAyE;IACzE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IAC1C,2EAA2E;IAC3E,OAAO,EAAE,mBAAmB,CAAC;IAC7B,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;CAClB;AAaD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,eAAe,GAAG;IACpE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;CAC1C,CA6EA;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,MAAM,GACf,4BAA4B,CA0D9B"}