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

package/dist/services/voice/voice-state-machine.d.ts

@@ -0,0 +1,364 @@
+/**
+ * Voice state machine — explicit state-machine wrapper that drives the
+ * optimistic-rollback path the C1 checkpoint enables.
+ *
+ * This is the thin layer the brief calls for: the existing
+ * `OptimisticRollbackController` already covers the pre-draft / draft-response
+ * path; this module adds the SPEAKING state and the barge-in restore path on
+ * top, exposed as a single state-machine surface (`getState`, `dispatch`)
+ * that the voice loop drives from VAD events + scheduler events.
+ *
+ *   IDLE
+ *     │ speech-start
+ *     ▼
+ *   LISTENING ────────────── speech-pause ────────────▶ PAUSE_TENTATIVE
+ *     ▲                                                       │
+ *     │ speech-active (within 2× hangover)                    │
+ *     │ ──── discard C1 ──────────────────────────────────────┤
+ *     │                                                       │
+ *     │                                                       │ speech-end
+ *     │                                                       ▼
+ *     │                                                  SPEAKING
+ *     │                                                       │
+ *     │ ◀──── restore C1, re-enter LISTENING ───── barge-in ──┘
+ *
+ * Key transitions (all wired to a `CheckpointManagerLike`):
+ *
+ *   - `speech-pause` (LISTENING → PAUSE_TENTATIVE)
+ *       Save checkpoint named "pre-draft" (C1). Kick the drafter on the
+ *       current partial transcript via the caller-supplied `startDrafter`.
+ *
+ *   - `speech-active` within 2× hangover (PAUSE_TENTATIVE → LISTENING)
+ *       Discard C1. Abort the speculative drafter. No rollback is required
+ *       because the drafter's KV writes were speculative against a snapshot
+ *       we never committed.
+ *
+ *   - `speech-end` (PAUSE_TENTATIVE → SPEAKING)
+ *       Commit the ASR final. The drafter's output is promoted: callers
+ *       wire the verifier on top via `onCommit`. **Retain** C1 — a barge-in
+ *       while the agent is speaking must roll the KV cache back to the
+ *       pre-draft point so the next user turn doesn't see the agent's own
+ *       half-spoken response in the prompt.
+ *
+ *   - `barge-in` (SPEAKING → LISTENING)
+ *       Restore C1. Hand the new user speech to the next LISTENING turn.
+ *       The same C1 may be restored multiple times — useful when two
+ *       consecutive barge-ins land before the next checkpoint is taken
+ *       (the test suite covers this).
+ *
+ * No fallback sludge: a checkpoint failure surfaces via `onError`. The
+ * state machine never silently downgrades to a non-checkpointed path —
+ * callers turn the feature off via the constructor option.
+ */
+import type { CheckpointHandle, CheckpointManagerLike } from "./checkpoint-manager";
+import type { ContextPartial } from "./eager-context-builder";
+import { type EotClassifier } from "./eot-classifier";
+import type { OptimisticGenerationPolicy } from "./optimistic-policy";
+import { type PrefillOptimisticOptions, type PrefillOptimisticResult } from "./prefill-client";
+/** Public state. Closed union — exhaustive switches catch new variants. */
+export type VoiceState = "IDLE" | "LISTENING" | "PAUSE_TENTATIVE" | "SPEAKING";
+/**
+ * Events that drive the state machine. Wall-clock timestamps are caller-
+ * supplied so the machine is testable without a fake clock.
+ */
+export type VoiceStateEvent = {
+    type: "speech-start";
+    timestampMs: number;
+} | {
+    type: "speech-pause";
+    timestampMs: number;
+    partialTranscript: string;
+} | {
+    type: "speech-active";
+    timestampMs: number;
+} | {
+    type: "speech-end";
+    timestampMs: number;
+    finalTranscript: string;
+} | {
+    type: "barge-in";
+    timestampMs: number;
+}
+/**
+ * Tier-3 — streamed partial transcript chunk from the ASR. When an
+ * `eotClassifier` is configured the machine will run `checkEot()` and may
+ * transition to PAUSE_TENTATIVE early or commit immediately depending on
+ * the returned probability and the elapsed silence since the last speech
+ * audio frame (provided by the caller via `silenceSinceMs`).
+ */
+ | {
+    type: "partial-transcript";
+    timestampMs: number;
+    text: string;
+    /** Milliseconds of silence elapsed since the last speech audio frame. */
+    silenceSinceMs: number;
+};
+/**
+ * Reason a speculative drafter handle was aborted by the state machine.
+ *
+ *   - `resumed` — `speech-active` re-entered LISTENING; the draft was
+ *                 speculative against a transcript that turned out to be
+ *                 still provisional.
+ *   - `barge-in` — the user interrupted while the agent was speaking; the
+ *                  draft's downstream TTS has already been hard-stopped.
+ *   - `shutdown` — `dispose()` was called.
+ */
+export type DrafterAbortReason = "resumed" | "barge-in" | "shutdown";
+/**
+ * Handle returned by `startDrafter`. The state machine calls `abort()`
+ * (idempotent) when the draft must be cancelled.
+ */
+export interface DrafterHandle {
+    abort(reason: DrafterAbortReason): void;
+}
+/**
+ * Caller-supplied drafter starter. Receives the partial transcript at the
+ * `speech-pause` instant and a turn id. Must return synchronously; the
+ * draft itself runs in the background until the state machine calls
+ * `abort()` or the draft completes (which is observed via `onCommit`).
+ */
+export type StartDrafterFn = (args: {
+    partialTranscript: string;
+    turnId: string;
+    /** Aborted when the drafter must be cancelled. */
+    signal: AbortSignal;
+}) => DrafterHandle;
+export interface VoiceStateMachineEvents {
+    /** State transition occurred. Called AFTER the new state is set. */
+    onStateChange?(prev: VoiceState, next: VoiceState, turnId: string): void;
+    /** Speculative drafter was started on `speech-pause`. */
+    onDrafterStart?(turnId: string, partialTranscript: string): void;
+    /** Speculative drafter was aborted (resumed / barge-in / shutdown). */
+    onDrafterAbort?(turnId: string, reason: DrafterAbortReason): void;
+    /**
+     * `speech-end` reached SPEAKING. The verifier should now run on top of
+     * the speculative drafter output against the final transcript.
+     *
+     * `prefillResult` is present when the C7 optimistic prefill completed
+     * before `speech-end` arrived. The verifier can resume generation from
+     * `prefillResult.checkpointHandle` to skip one full prefill RTT.
+     */
+    onCommit?(turnId: string, finalTranscript: string, prefillResult?: PrefillOptimisticResult): void;
+    /**
+     * A barge-in restored C1. The voice loop should drop any in-flight TTS
+     * (separate concern owned by the barge-in controller) and begin a new
+     * LISTENING turn with the new user audio.
+     */
+    onRollback?(turnId: string, restoredFrom: CheckpointHandle): void;
+    /**
+     * Surfaced when `CheckpointManager.{save,restore,discard}` rejects.
+     * The state machine continues — checkpoint failures must not break the
+     * voice loop — but the operator can flip the feature flag off in
+     * response.
+     */
+    onError?(op: "save" | "restore" | "discard", error: unknown, turnId: string): void;
+    /**
+     * Fired when the Tier-3 EOT classifier scores a partial transcript.
+     * Useful for telemetry and debugging — P values are emitted before the
+     * state machine decides whether to act on them.
+     */
+    onEotScore?(turnId: string, text: string, pDone: number): void;
+    /**
+     * Fired when the C7 optimistic prefill completes (either successfully or
+     * with an error). On success `result` is set; on error `error` is set.
+     * The state machine never blocks on the prefill result — it resolves or
+     * rejects in the background while PAUSE_TENTATIVE is active.
+     */
+    onPrefill?(turnId: string, result: PrefillOptimisticResult | null, error: unknown | null): void;
+}
+export interface VoiceStateMachineOptions {
+    /** Slot identifier for the conversation pinning. */
+    slotId: string;
+    /**
+     * Whether to actually call into the `CheckpointManager`. When `false`,
+     * the state machine still transitions through the same states but
+     * never saves/restores. Default `true` — callers turn the feature off
+     * here when upstream `--ctx-checkpoints` is unavailable.
+     */
+    enableCheckpoints?: boolean;
+    /**
+     * VAD pause hangover (ms). The rollback window is `2 × hangoverMs`. If
+     * a `speech-active` arrives later than this after a `speech-pause`, the
+     * machine treats the pause as a real speech-end equivalent (it commits
+     * instead of discarding).
+     */
+    pauseHangoverMs?: number;
+    checkpointManager: CheckpointManagerLike;
+    /** Drafter starter — see `StartDrafterFn`. */
+    startDrafter: StartDrafterFn;
+    /** Events sink. */
+    events?: VoiceStateMachineEvents;
+    /**
+     * Tier-3 semantic EOT classifier. When provided, partial transcripts are
+     * scored on each `partial-transcript` dispatch:
+     *
+     *   P ≥ 0.9 AND silence ≥ 50 ms  → commit immediately (skip remaining hangover)
+     *   P ≥ 0.6 AND silence ≥ 20 ms  → enter PAUSE_TENTATIVE early (start drafter)
+     *   P < 0.4                        → extend hangover by 50 ms (user is mid-clause)
+     *
+     * When absent the machine behaves as before (tiers 1 + 2 only).
+     */
+    eotClassifier?: EotClassifier;
+    /**
+     * C7 — optimistic prefill configuration. When provided the machine fires
+     * `prefillOptimistic` on `PAUSE_TENTATIVE` entry (fire-and-forget) so the
+     * KV cache is pre-warmed with the partial transcript by the time ASR
+     * finalizes. The prefill result is passed to `onCommit` via `prefillResult`.
+     *
+     * Omit to disable the prefill path entirely.
+     */
+    prefillConfig?: {
+        /** Base URL of the llama-server (`http://host:port`). */
+        baseUrl: string;
+        /** `CheckpointManager` options forwarded to `prefillOptimistic`. */
+        checkpointOptions?: Omit<PrefillOptimisticOptions, "checkpointManager">;
+        /**
+         * Optional deterministic context from `EagerContextBuilder` (C3).
+         * When supplied, the prefill `/completion` call includes the system
+         * prompt + conversation history so the KV cache is maximally warm.
+         */
+        getContext?: () => ContextPartial | null;
+    };
+    /**
+     * W3-9 / F1 — optional optimistic-generation policy. When provided, the
+     * machine consults `policy.shouldStartOptimisticLm(eotProb)` at the
+     * `firePrefill` site before kicking off the speculative prefill. When
+     * the policy says no (e.g. on battery, or below the configured EOT
+     * threshold) `firePrefill` is a no-op and `handleSpeechEnd` falls back
+     * to a regular (non-prefilled) verifier pass. Omit to keep the prior
+     * behaviour (fire on every PAUSE_TENTATIVE entry regardless of EOT
+     * probability).
+     */
+    optimisticPolicy?: OptimisticGenerationPolicy;
+}
+/**
+ * Explicit state-machine implementation. Stateful (state + active
+ * checkpoint + drafter handle); methods are NOT thread-safe — call them
+ * from a single event loop.
+ */
+export declare class VoiceStateMachine {
+    private readonly slotId;
+    private readonly enabled;
+    private readonly pauseHangoverMs;
+    private readonly mgr;
+    private readonly startDrafterFn;
+    private readonly events;
+    /** Tier-3 semantic EOT classifier. Optional — omit for tiers 1+2 only. */
+    private readonly eotClassifier;
+    private state;
+    private turnCounter;
+    /** Most recent C1 handle. Retained across `speech-end` until barge-in or next IDLE. */
+    private checkpoint;
+    private activeDraft;
+    private pauseTimestampMs;
+    private disposed;
+    /**
+     * Accumulated hangover extension from EOT mid-clause detections (ms).
+     * Reset on each new turn (speech-start). Added to the effective hangover
+     * so that consecutive mid-clause detections stack.
+     */
+    private eotHangoverExtensionMs;
+    /**
+     * C7 — in-flight prefill promise. Set on PAUSE_TENTATIVE entry; awaited
+     * (or discarded) on SPEECH_END / SPEECH_ACTIVE_REBOUND. Fire-and-forget
+     * from the perspective of the state machine — the result is surfaced via
+     * `onPrefill` and `onCommit(prefillResult)`.
+     */
+    private prefillPromise;
+    private readonly prefillConfig;
+    /** W3-9 / F1 — optimistic-generation policy gate for `firePrefill`. */
+    private readonly optimisticPolicy;
+    /**
+     * Most recently observed EOT probability from the Tier-3 classifier.
+     * Used as the `eotProb` argument to `prefillOptimistic` when PAUSE_TENTATIVE
+     * is entered. Starts at 0.5 (uncertain). Updated on each `partial-transcript`
+     * event when an EOT classifier is wired.
+     */
+    private latestEotProb;
+    constructor(opts: VoiceStateMachineOptions);
+    /** Current state — read-only view for tests / telemetry. */
+    getState(): VoiceState;
+    /** Internal turn id for the current turn. Stable across pause/active. */
+    getTurnId(): string;
+    /**
+     * Active checkpoint handle, if any. Exposed for tests; production code
+     * should use `onCommit` / `onRollback` events instead.
+     */
+    getActiveCheckpoint(): CheckpointHandle | null;
+    /**
+     * Accumulated EOT hangover extension (ms). The `VadDetector` (Tier 2)
+     * should add this to its effective pause hangover so mid-clause pauses
+     * are not committed prematurely. Resets to 0 on each `speech-start`.
+     */
+    getEotHangoverExtensionMs(): number;
+    /**
+     * Drive the machine. Returns a promise that resolves after any async
+     * checkpoint work for this event finishes (await it in tests for
+     * deterministic assertions). Callers in production may ignore the
+     * returned promise — events fire synchronously regardless.
+     */
+    dispatch(event: VoiceStateEvent): Promise<void>;
+    /**
+     * Tear down: abort any in-flight drafter, discard the live checkpoint.
+     * Safe to call multiple times. After `dispose` the machine ignores
+     * further events.
+     */
+    dispose(): Promise<void>;
+    private handleSpeechStart;
+    private handleSpeechPause;
+    private handleSpeechActive;
+    private handleSpeechEnd;
+    private handleBargeIn;
+    /**
+     * Handle a partial transcript chunk from streaming ASR.
+     *
+     * When an `eotClassifier` is configured, scores the text and applies:
+     *
+     *   P ≥ EOT_COMMIT_THRESHOLD  AND silence ≥ EOT_COMMIT_SILENCE_MS
+     *     → behave as `speech-end` (commit immediately, skip remaining hangover)
+     *
+     *   P ≥ EOT_TENTATIVE_THRESHOLD AND silence ≥ EOT_TENTATIVE_SILENCE_MS
+     *     AND state is LISTENING
+     *     → behave as `speech-pause` (enter PAUSE_TENTATIVE, start drafter)
+     *
+     *   P < EOT_MID_CLAUSE_THRESHOLD
+     *     → accumulate EOT_HANGOVER_EXTENSION_MS into the hangover extension
+     *       (the VadDetector reads this via `getEotHangoverExtensionMs()`)
+     *
+     * No-ops when `eotClassifier` is not set, or when the machine is not in
+     * LISTENING or PAUSE_TENTATIVE.
+     */
+    private handlePartialTranscript;
+    /**
+     * Score the partial transcript with the Tier-3 EOT classifier.
+     * Returns 0.5 when no classifier is configured (uncertain — let tiers 1+2 decide).
+     */
+    private checkEot;
+    /**
+     * C7 — fire the optimistic prefill in the background and store the
+     * promise so `handleSpeechEnd` can await it. The machine never awaits
+     * here — it stays in PAUSE_TENTATIVE whether or not the prefill has
+     * finished. On `SPEECH_ACTIVE_REBOUND` the promise is discarded; on
+     * `SPEECH_END` it is awaited (or its cached result used) and passed
+     * through `onCommit(prefillResult)`.
+     *
+     * W3-9 / F1 — when an `optimisticPolicy` is configured, this is gated on
+     * `policy.shouldStartOptimisticLm(eotProb)`. The policy folds the
+     * device's power source (plugged-in / battery / unknown), the user's
+     * explicit override, and the EOT threshold into a single decision; when
+     * it returns false the prefill is suppressed and `handleSpeechEnd`
+     * runs a regular (non-prefilled) verifier pass.
+     */
+    private firePrefill;
+    private startSpeculativeDrafter;
+    private abortActiveDraft;
+    private setState;
+    /**
+     * Returns `this.state` as the wider `VoiceState` union. Used in
+     * post-`await` re-checks where the entry-guard narrowing would
+     * otherwise convince TS the state can't have changed (it doesn't track
+     * mutations through `setState`).
+     */
+    private currentState;
+}
+//# sourceMappingURL=voice-state-machine.d.ts.map

package/dist/services/voice/voice-state-machine.d.ts.map

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

package/dist/services/voice/voice-workbench-report.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Voice Workbench benchmark report (#8785).
+ *
+ * Rolls a matrix of per-scenario scorer results into one machine-readable
+ * report + a Markdown rendering, mirroring `voicebench`'s p95/p99 output and the
+ * `summarizeVoiceE2e` verdict shape. Pure: it consumes already-scored
+ * `VoiceE2eCaseResult`s (the runners — headless services / headful frontend —
+ * produce those), so it can be unit-tested without audio, models, or a browser.
+ *
+ * Honesty contract: a scenario whose corpus/backend artifacts are absent is
+ * `skipped`, never `pass`. `overall` is `skipped` only when *every* scenario was
+ * skipped; one ran-and-failed scenario makes the whole report `fail`.
+ */
+import type { VoiceE2eCaseResult } from "./e2e-harness";
+import type { VoiceScenarioClass } from "./voice-scenario";
+export type VoiceWorkbenchStatus = "ran" | "skipped";
+export type VoiceWorkbenchVerdict = "pass" | "fail" | "skipped";
+/**
+ * A `.wav` artifact written for one scenario run when a capture sink is active.
+ * `path` is RELATIVE to the run dir the headless runner was told to write under,
+ * so the scenario run viewer (served from that dir) can reference it directly.
+ */
+export interface VoiceAudioArtifact {
+    /** Turn index this artifact belongs to; the full corpus uses turn 0. */
+    turnIndex: number;
+    /** `generated` = the full synthesized corpus; `consumed` = a per-turn slice. */
+    kind: "generated" | "consumed";
+    /** Path to the `.wav`, relative to the run dir (forward-slash separated). */
+    path: string;
+    sampleRate: number;
+    durationMs?: number;
+    /** Diarization ground-truth speaker label for a consumed per-turn slice. */
+    speakerLabel?: string;
+}
+/** One scenario's outcome in a workbench run. */
+export interface VoiceWorkbenchScenarioRun {
+    scenarioId: string;
+    classes: VoiceScenarioClass[];
+    /** `skipped` when corpus/backend artifacts were absent (never scored). */
+    status: VoiceWorkbenchStatus;
+    /** Scored cases for this scenario (empty when skipped). */
+    cases: VoiceE2eCaseResult[];
+    /** Why the scenario was skipped (artifact/backend absence), if it was. */
+    skipReason?: string;
+    /** `.wav` artifacts written when a capture sink was active (else absent). */
+    audioArtifacts?: VoiceAudioArtifact[];
+}
+export interface VoiceWorkbenchScenarioReport {
+    scenarioId: string;
+    classes: VoiceScenarioClass[];
+    status: VoiceWorkbenchStatus;
+    verdict: VoiceWorkbenchVerdict;
+    caseCount: number;
+    failedCaseKinds: string[];
+    skipReason?: string;
+}
+/** Mean + worst + sample-count for one metric across all ran scenarios. */
+export interface MetricRollup {
+    count: number;
+    mean: number | null;
+    worst: number | null;
+}
+export interface VoiceWorkbenchMetrics {
+    /** Transcription word-error-rate (`worst` = max). */
+    wer: MetricRollup;
+    /** EOT false-trigger rate (`worst` = max) + latency percentiles. */
+    eotFalseTriggerRate: MetricRollup;
+    eotLatencyP50Ms: number | null;
+    eotLatencyP95Ms: number | null;
+    /** Diarization error rate (`worst` = max). */
+    der: MetricRollup;
+    /** Respond-decision accuracy (`worst` = min). */
+    respondAccuracy: MetricRollup;
+    /** Entity-extraction F1 (`worst` = min). */
+    entityF1: MetricRollup;
+    /** Voice→entity match rate (`worst` = min). */
+    voiceEntityMatchRate: MetricRollup;
+    /** First-audio latency ms (`worst` = max). */
+    firstAudioMs: MetricRollup;
+    /** Self-echo rejection rate (`worst` = min). */
+    echoRejectionRate: MetricRollup;
+    /** Owner-vs-intruder accuracy (`worst` = min). */
+    ownerAccuracy: MetricRollup;
+    /** Impostor-accept rate (`worst` = max) — non-owner accepted as owner. */
+    impostorAcceptRate: MetricRollup;
+}
+export interface VoiceWorkbenchReport {
+    schemaVersion: 1;
+    overall: VoiceWorkbenchVerdict;
+    scenariosTotal: number;
+    scenariosRan: number;
+    scenariosSkipped: number;
+    scenarios: VoiceWorkbenchScenarioReport[];
+    metrics: VoiceWorkbenchMetrics;
+}
+/**
+ * Aggregate per-scenario scorer results into one gating report. `overall` is
+ * `fail` if any scenario ran and failed, else `pass` if any scenario ran and
+ * passed, else `skipped`.
+ */
+export declare function buildVoiceWorkbenchReport(runs: ReadonlyArray<VoiceWorkbenchScenarioRun>): VoiceWorkbenchReport;
+/** Render a workbench report as Markdown (one metric table + a scenario table). */
+export declare function formatVoiceWorkbenchMarkdown(report: VoiceWorkbenchReport): string;
+export interface MetricRegression {
+    metric: string;
+    baseline: number;
+    current: number;
+    delta: number;
+}
+/**
+ * Compare two reports and flag metrics that regressed beyond `tolerance`.
+ * "Lower is better" metrics (WER, EOT FTR, DER, latencies) regress when they
+ * rise; "higher is better" metrics (accuracies, F1, match rate) regress when
+ * they fall. Only metrics present (non-null mean) in both reports are compared.
+ */
+export declare function regressionsAgainstBaseline(current: VoiceWorkbenchReport, baseline: VoiceWorkbenchReport, tolerance?: number): MetricRegression[];
+//# sourceMappingURL=voice-workbench-report.d.ts.map

package/dist/services/voice/voice-workbench-report.d.ts.map

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

package/dist/services/voice/wake-word-ggml.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Wake-word detection — native runtime binding.
+ *
+ * Loads the standalone `packages/native/plugins/wakeword-cpp/`
+ * library directly via `bun:ffi` and exposes the `WakeWordModel`
+ * interface as `OpenWakeWordGgmlModel`. The sibling `./wake-word.ts`
+ * is the fused-`libelizainference` path (`GgmlWakeWordModel`, the
+ * `eliza_inference_wakeword_*` FFI surface) and selects between the two
+ * native backends; both implement the same interface so the voice
+ * lifecycle can swap them without changing anything upstream. There is
+ * NO ONNX path on either — `onnxruntime-node` was removed.
+ *
+ * This binding is the standalone-library backend, used when the
+ * `libwakeword.{so,dylib,dll}` shared library and three converted
+ * GGUFs are present. The C runtime is a pure-fp32 reference
+ * implementation of the openWakeWord three-stage pipeline (melspec
+ * → embedding CNN → classifier head) — no ggml link, no SIMD; a
+ * laptop CPU runs it under 1 % of real time. ABI parity with the
+ * upstream openWakeWord ONNX graphs is gated by
+ * `packages/native/plugins/wakeword-cpp/test/wakeword_parity_test.py`.
+ *
+ * Three GGUFs back one session, mirroring openWakeWord's three ONNX
+ * graphs (the C library is the single source of truth on shapes —
+ * see `packages/native/plugins/wakeword-cpp/include/wakeword/wakeword.h`):
+ *
+ *   1. melspec    — 16 kHz PCM → 32-bin log-mel frames.
+ *   2. embedding  — 20-Conv2D CNN over a 76-mel-frame sliding window
+ *                   → 96-dim embedding.
+ *   3. classifier — 4-layer MLP over a 16-embedding window → P(wake)
+ *                   ∈ [0, 1].
+ */
+import type { WakeWordModel } from "./types";
+/** Three GGUF paths that back one session. */
+export interface WakeWordGgmlPaths {
+    /** Frozen Hann window + mel filter bank + STFT params metadata. */
+    melspec: string;
+    /** Embedding-CNN weights (fp16) + architecture metadata. */
+    embedding: string;
+    /** Classifier-head weights (fp16) + (1, 16, 96) input shape. */
+    classifier: string;
+}
+export interface WakeWordGgmlConfig {
+    /** Detection threshold ∈ [0, 1]. Default 0.5 (matches upstream openWakeWord). */
+    threshold?: number;
+}
+/**
+ * Thrown when the native ggml backend cannot be used. Distinct from
+ * `WakeWordUnavailableError` in `./wake-word.ts` so callers that fall
+ * back to the legacy ONNX path can tell the two failure modes apart
+ * during the migration.
+ */
+export declare class WakeWordGgmlUnavailableError extends Error {
+    readonly code: "not-bun" | "library-load-failed" | "model-load-failed" | "abi-error";
+    constructor(code: WakeWordGgmlUnavailableError["code"], message: string);
+}
+/**
+ * Streaming wake-word detector backed by `libwakeword`.
+ *
+ * Implements the same `WakeWordModel` interface as `OpenWakeWordModel`
+ * in `./wake-word.ts` so the voice lifecycle can swap implementations
+ * without changing anything upstream.
+ */
+export declare class OpenWakeWordGgmlModel implements WakeWordModel {
+    private readonly lib;
+    private readonly handle;
+    readonly frameSamples = 1280;
+    readonly sampleRate = 16000;
+    private constructor();
+    /**
+     * Load a wake-word model from its three GGUFs and the
+     * `libwakeword` shared library. Returns a ready-to-use detector
+     * with a fresh streaming session. Throws
+     * `WakeWordGgmlUnavailableError` on dlopen / ABI / GGUF failure.
+     */
+    static load(args: {
+        libraryPath: string;
+        paths: WakeWordGgmlPaths;
+        config?: WakeWordGgmlConfig;
+    }): Promise<OpenWakeWordGgmlModel>;
+    /**
+     * Score one 1280-sample (80 ms @ 16 kHz) fp32 mono frame and
+     * return the most recent classifier probability ∈ [0, 1]. Early
+     * frames (before enough mel + embedding context has accumulated)
+     * return 0.
+     */
+    scoreFrame(frame: Float32Array): Promise<number>;
+    /**
+     * Streaming state lives on the native side. The C ABI does not
+     * expose a separate `reset` entry point yet (Phase 2 will add one
+     * if the ggml-backed implementation needs it); for now, reset is
+     * a no-op on the JS side. Callers that need a hard state clear
+     * close + reopen the session.
+     */
+    reset(): void;
+    /** Release the native session and the dlopen handle. */
+    close(): void;
+    /** Diagnostics: `"native-cpu"` on this build (pure-fp32 reference). */
+    activeBackend(): string;
+}
+//# sourceMappingURL=wake-word-ggml.d.ts.map

package/dist/services/voice/wake-word-ggml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake-word-ggml.d.ts","sourceRoot":"","sources":["../../../src/services/voice/wake-word-ggml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAM7C,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IACjC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IAClC,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,EACV,SAAS,GACT,qBAAqB,GACrB,mBAAmB,GACnB,WAAW,CAAC;gBACH,IAAI,EAAE,4BAA4B,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAKvE;AAkID;;;;;;GAMG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IAKzD,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALxB,QAAQ,CAAC,YAAY,QAAiB;IACtC,QAAQ,CAAC,UAAU,SAAe;IAElC,OAAO;IAKP;;;;;OAKG;WACU,IAAI,CAAC,IAAI,EAAE;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,iBAAiB,CAAC;QACzB,MAAM,CAAC,EAAE,kBAAkB,CAAC;KAC5B,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAyClC;;;;;OAKG;IACG,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBtD;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAIb,wDAAwD;IACxD,KAAK,IAAI,IAAI;IAKb,uEAAuE;IACvE,aAAa,IAAI,MAAM;CAIvB"}