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

package/dist/services/voice/echo-reference-buffer.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Echo-reference alignment buffer (#9583, follow-up to #9455/#9586).
+ *
+ * The NLMS echo canceller's `process(nearEnd, farEnd)` needs the far-end
+ * (the agent's TTS playback) **time-aligned** to the current mic frame: the
+ * echo in `nearEnd[t]` is the room-filtered playback from `t − delay`, where
+ * `delay` is the bulk playback→mic transport delay (estimated by
+ * {@link estimateEchoDelaySamples} in `echo-delay.ts`).
+ *
+ * The caller renders playback PCM in real time and `push()`es it here as it goes;
+ * per mic frame it then asks for the aligned far-end slice. This is the
+ * "caller must supply the reference" primitive the consumer seam was missing —
+ * a fixed-capacity delay line, pure logic (no FFI, no device, no audio I/O).
+ * Samples not yet rendered, or already evicted past capacity, are zero-filled
+ * (no echo reference ⇒ the adaptive filter simply has nothing to cancel there).
+ */
+export interface EchoReferenceBufferOptions {
+    /**
+     * Ring-buffer capacity in samples. Must comfortably exceed
+     * `maxDelaySamples + frameLength`. Default 24000 (1.5 s @ 16 kHz).
+     */
+    capacitySamples?: number;
+    /** Sample rate for timestamp-based push/read helpers. Default 16000. */
+    sampleRateHz?: number;
+}
+export declare class EchoReferenceBuffer {
+    private readonly buffer;
+    private readonly valid;
+    private readonly capacity;
+    private readonly sampleRateHz;
+    /** Total samples ever pushed (monotonic); the logical "now" cursor. */
+    private pushed;
+    /** Timestamp mapped to absolute sample 0 for timestamp-aware playback. */
+    private originMs;
+    constructor(options?: EchoReferenceBufferOptions);
+    /** Append rendered playback (far-end) PCM as it is produced. */
+    push(playback: Float32Array): void;
+    /**
+     * Store rendered playback at its capture/render timestamp. This preserves
+     * real gaps between playback bursts instead of treating chunks as contiguous.
+     */
+    pushAt(timestampMs: number, playback: Float32Array): void;
+    /**
+     * The far-end reference frame aligned to a mic frame of `length` samples
+     * captured `delaySamples` after the corresponding playback. Returns the
+     * playback window `[pushed − delaySamples − length, pushed − delaySamples)`.
+     * Indices before the retained window (not yet pushed, or evicted past
+     * capacity) are zero-filled.
+     */
+    referenceFor(length: number, delaySamples: number): Float32Array;
+    /**
+     * Reference aligned to a mic frame starting at `timestampMs`.
+     * Returns playback `[timestampMs - delay, timestampMs - delay + length)`.
+     */
+    referenceAt(timestampMs: number, length: number, delaySamples: number): Float32Array;
+    /** Samples pushed so far (the monotonic stream position). */
+    get position(): number;
+    /** Drop all buffered playback (e.g. on a new turn / barge-in flush). */
+    reset(): void;
+    private sampleIndexFor;
+    private writeAt;
+    private clearRange;
+    private readWindow;
+}
+//# sourceMappingURL=echo-reference-buffer.d.ts.map

package/dist/services/voice/echo-reference-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"echo-reference-buffer.d.ts","sourceRoot":"","sources":["../../../src/services/voice/echo-reference-buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,0BAA0B;IAC1C;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,mBAAmB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,uEAAuE;IACvE,OAAO,CAAC,MAAM,CAAK;IACnB,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAuB;gBAE3B,OAAO,GAAE,0BAA+B;IAOpD,gEAAgE;IAChE,IAAI,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAKlC;;;OAGG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI;IAgBzD;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,YAAY;IAQhE;;;OAGG;IACH,WAAW,CACV,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GAClB,YAAY;IAUf,6DAA6D;IAC7D,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,wEAAwE;IACxE,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,UAAU;CAYlB"}

package/dist/services/voice/eliza1-eot-scorer.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Eliza-1 EOT scorer — reuses the already-loaded text model to compute
+ * P(`<end_of_turn>` next | conversation_so_far) without shipping a separate
+ * detector ONNX.
+ *
+ * The runtime keeps a `LlamaModel` resident for chat generation. Voice
+ * EOT scoring is a single forward pass over the formatted Gemma chat
+ * prompt with the trailing `<end_of_turn>` removed. `capacitor-llama`'s
+ * `LlamaContextSequence.controlledEvaluate()` returns the next-token
+ * probability distribution, so we simply read the entry for the
+ * `<end_of_turn>` token id — no sampling loop, no KV-cache growth on the
+ * chat session.
+ *
+ * A dedicated `LlamaContext` is held just for this scorer so we do not
+ * fight the chat session pool for sequence slots. The context is small
+ * (single sequence, ≤512 tokens) and shares the model weights with the
+ * chat path; only the per-sequence KV cache is duplicated.
+ *
+ * Optionally a LoRA adapter is attached to that context — that is how
+ * a fine-tuned EOT head (trained per
+ * `packages/training/scripts/turn_detector/`) layers onto the same base
+ * weights without a separate GGUF.
+ */
+export interface LlamaModelLike {
+    tokenize(text: string, specialTokens?: boolean): readonly number[];
+    createContext(options: {
+        contextSize?: number;
+        sequences?: number;
+        flashAttention?: boolean;
+        lora?: string | {
+            adapters: Array<{
+                filePath: string;
+                scale?: number;
+            }>;
+        };
+    }): Promise<LlamaContextLike>;
+}
+export interface LlamaContextLike {
+    getSequence(options?: object): LlamaContextSequenceLike;
+    dispose(): Promise<void>;
+}
+export interface LlamaContextSequenceLike {
+    clearHistory(): Promise<void>;
+    controlledEvaluate(input: ControlledEvaluateInputLike[], options?: {
+        evaluationPriority?: number;
+    }): Promise<Array<ControlledEvaluateOutputLike | undefined>>;
+}
+export type ControlledEvaluateInputLike = number | [
+    token: number,
+    options: {
+        generateNext?: {
+            probabilities?: boolean;
+            confidence?: boolean;
+        };
+    }
+];
+export interface ControlledEvaluateOutputLike {
+    next: {
+        token?: number | null;
+        confidence?: number;
+        probabilities?: Map<number, number>;
+    };
+}
+export interface Eliza1EotScorerOptions {
+    /** The already-loaded text model (eliza-1 drafter). */
+    model: LlamaModelLike;
+    /** Optional EOT LoRA adapter path (absolute). When set, applied to the dedicated EOT context. */
+    loraPath?: string;
+    /** Adapter scale (default 1.0). Only meaningful when `loraPath` is set. */
+    loraScale?: number;
+    /** Max history tokens to keep in the prompt window. LiveKit uses 128. */
+    maxHistoryTokens?: number;
+    /** Context size for the dedicated EOT context. Default 512. */
+    contextSize?: number;
+    /** Model label for telemetry. */
+    modelLabel?: string;
+}
+export interface Eliza1EotScoreResult {
+    /** Probability of `<end_of_turn>` as the next token, ∈ [0, 1]. */
+    probability: number;
+    /** Wall-clock model latency for this scoring call. */
+    latencyMs: number;
+    /** Number of prompt tokens evaluated. */
+    promptTokens: number;
+}
+/**
+ * Stateful EOT scorer bound to a single loaded text model. Lazily
+ * allocates its own dedicated `LlamaContext` on first call. Safe to
+ * keep across many voice turns; call `dispose()` on shutdown.
+ */
+export declare class Eliza1EotScorer {
+    private readonly model;
+    private readonly loraPath;
+    private readonly loraScale;
+    private readonly maxHistoryTokens;
+    private readonly contextSize;
+    readonly modelLabel: string;
+    private context;
+    private sequence;
+    private endOfTurnTokenId;
+    private initPromise;
+    /** Serializes concurrent calls — controlledEvaluate is not thread-safe per-sequence. */
+    private inflight;
+    constructor(options: Eliza1EotScorerOptions);
+    score(partialTranscript: string): Promise<Eliza1EotScoreResult>;
+    dispose(): Promise<void>;
+    private ensureReady;
+    private initialize;
+    private tokenizePrompt;
+    private runOnce;
+}
+/**
+ * Format the partial transcript using the Gemma chat template, with the
+ * trailing `<end_of_turn>` removed so the next predicted token *is* the
+ * EOT signal we want to measure.
+ *
+ * Matches the formatting LiveKit's turn-detector uses (single user turn,
+ * no system prompt, no generation prefix). When upstream history is
+ * available we can stack turns here, but the LiveKit recipe truncates
+ * to the last 128 tokens regardless, so a single user turn captures the
+ * relevant context for tier-1 EOT.
+ */
+export declare function formatEotPrompt(transcript: string): string;
+//# sourceMappingURL=eliza1-eot-scorer.d.ts.map

package/dist/services/voice/eliza1-eot-scorer.d.ts.map

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

package/dist/services/voice/embedding-server.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Lazy embedding `llama-server` sidecar for Eliza-1 bundles.
+ *
+ * The route resolver decides which GGUF backs embeddings. This class owns the
+ * process boundary: validate the GGUF at construction, start the sidecar only
+ * on first non-empty `embed()`, and return Matryoshka-truncated vectors.
+ */
+import { type LocalEmbeddingRoute } from "./embedding";
+interface EmbeddingServerConfig {
+    /** GGUF the sidecar mmaps. For the dedicated-region mode this is the `embedding/` file. */
+    modelPath: string;
+    /** Extra `llama-server` flags — the route's `embeddingServerFlags` (`--embeddings --pooling last`). */
+    serverFlags: ReadonlyArray<string>;
+    /** GPU offload: `"auto"` (= all layers) for CPU/Vulkan/CUDA hosts, `0` to force CPU. */
+    gpuLayers?: number | "auto";
+    /** Thread count for the embedding forward pass. Defaults to the host's logical core count. */
+    threads?: number;
+}
+export declare class EmbeddingServer {
+    private readonly config;
+    private child;
+    private baseUrl;
+    private starting;
+    constructor(config: EmbeddingServerConfig);
+    isRunning(): boolean;
+    embed(texts: string[], dim?: number): Promise<number[][]>;
+    private ensureStarted;
+    private start;
+    private waitUntilReady;
+    stop(): Promise<void>;
+}
+export declare function embeddingServerForRoute(route: LocalEmbeddingRoute, opts?: {
+    gpuLayers?: number | "auto";
+    threads?: number;
+}): EmbeddingServer;
+export {};
+//# sourceMappingURL=embedding-server.d.ts.map

package/dist/services/voice/embedding-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-server.d.ts","sourceRoot":"","sources":["../../../src/services/voice/embedding-server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAEN,KAAK,mBAAmB,EAExB,MAAM,aAAa,CAAC;AAGrB,UAAU,qBAAqB;IAC9B,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,uGAAuG;IACvG,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAe;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,KAAK,CAA6B;IAC1C,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,QAAQ,CAA8B;gBAElC,MAAM,EAAE,qBAAqB;IAUzC,SAAS,IAAI,OAAO;IAId,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,SAAO,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAoC/C,aAAa;YAQb,KAAK;YAuCL,cAAc;IAuBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAa3B;AAED,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1D,eAAe,CAWjB"}

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

@@ -0,0 +1,132 @@
+/**
+ * Local embedding wiring for Eliza-1 bundles.
+ *
+ * Per `packages/inference/AGENTS.md` §1:
+ *   - On the `2b` tier (the entry/floor tier) the **embedding model IS the
+ *     text backbone**, served with `--pooling last` — there is no separate
+ *     `embedding/` GGUF and no duplicate parameters on the entry tier.
+ *   - On `4b` and larger tiers, a dedicated
+ *     `embedding/` GGUF region (Apache-2.0,
+ *     1024-dim Matryoshka, 32k ctx) is acquired lazily through the same
+ *     engine / `SharedResourceRegistry`. **Do not collapse it to pooled
+ *     text on the larger tiers** — that breaks the 1024-dim Matryoshka
+ *     contract (B1's verdict).
+ *
+ * This module is a pure resolver: given a bundle root + tier id it
+ * describes *where* embeddings come from (the text GGUF with a pooling
+ * flag, or a separate region file) without doing any I/O beyond an
+ * `existsSync`. The engine consumes the descriptor to mount the region
+ * and the local-embedding route. It also owns the Matryoshka-truncation
+ * helper that callers / the vector store use to trade dimensionality for
+ * storage (see `EMBEDDING_MATRYOSHKA_DIMS` + `truncateMatryoshka`).
+ */
+import type { Eliza1TierId } from "../catalog";
+/** Bundle-relative directory holding a dedicated embedding GGUF (larger tiers). */
+export declare const EMBEDDING_DIR_REL_PATH = "embedding";
+/** Full output dimensionality of the Eliza-1 embedding model. */
+export declare const EMBEDDING_FULL_DIM: 1024;
+/**
+ * Valid Matryoshka truncation points for the Eliza-1 embedding region. The model
+ * is trained so that the leading N components of the 1024-dim vector are
+ * themselves a usable embedding at these widths; quality degrades
+ * gracefully as N shrinks (see the tradeoff table in
+ * `reports/porting/2026-05-11/embedding-model-review.md`).
+ *
+ * 1024 (full) → 768 → 512 → 256 → 128 → 64. Smaller widths than 64 are
+ * not part of the published contract.
+ */
+export declare const EMBEDDING_MATRYOSHKA_DIMS: readonly number[];
+/** Type-narrow guard for `EMBEDDING_MATRYOSHKA_DIMS`. */
+export declare function isValidEmbeddingDim(dim: number): boolean;
+/**
+ * Truncate a full 1024-dim embedding to one of the Matryoshka widths and
+ * L2-renormalize. Renormalization matters: the dedicated embedding outputs are
+ * unit-norm at 1024 dims, but the leading slice is *not* unit-norm, and
+ * downstream cosine-similarity / dot-product retrieval assumes unit
+ * vectors.
+ *
+ * Throws on an invalid `dim` (must be one of `EMBEDDING_MATRYOSHKA_DIMS`)
+ * or when `vec` is shorter than `dim` — no silent truncation-to-whatever
+ * or zero-padding (Commandment 8: don't hide a broken pipeline).
+ */
+export declare function truncateMatryoshka(vec: readonly number[], dim: number): number[];
+export type LocalEmbeddingSource = {
+    /** `2b` (entry tier): reuse the text backbone GGUF; serve with `--pooling last`. */
+    readonly kind: "pooled-text";
+    readonly textModelPath: string;
+    readonly poolingType: "last";
+} | {
+    /** Larger tiers: a dedicated `embedding/<name>.gguf` region. */
+    readonly kind: "dedicated-region";
+    readonly embeddingModelPath: string;
+    /** 1024-dim Matryoshka (the published Eliza-1 embedding contract). */
+    readonly dimensions: typeof EMBEDDING_FULL_DIM;
+    /**
+     * The dedicated model already ships a contrastive `last`-token
+     * pooling head — `--pooling last` is still passed so llama-server
+     * doesn't fall back to the GGUF's metadata default. The model's own
+     * pooling layer dominates; this just pins the read.
+     */
+    readonly poolingType: "last";
+};
+/**
+ * Tiers whose embedding model is the text backbone with `--pooling last`
+ * (no separate GGUF). The default mobile tiers deliberately avoid duplicate
+ * parameters; larger tiers may use a dedicated embedding region.
+ */
+export declare const POOLED_TEXT_EMBEDDING_TIERS: ReadonlySet<Eliza1TierId>;
+/**
+ * Resolve the embedding source for an activated Eliza-1 bundle.
+ *
+ * @param bundleRoot   Bundle directory on disk.
+ * @param tierId       The Eliza-1 tier id (`eliza-1-2b`, ...).
+ * @param textModelPath Absolute path of the activated text GGUF (needed for
+ *                      the `pooled-text` case).
+ *
+ * Hard-fails (AGENTS.md §3) when a larger tier is missing its
+ * `embedding/` region — no silent fallback to pooled text, which would
+ * regress dimensions from 1024 to whatever the text model emits.
+ */
+export declare function resolveLocalEmbeddingSource(args: {
+    bundleRoot: string;
+    tierId: Eliza1TierId;
+    textModelPath: string;
+}): LocalEmbeddingSource;
+/**
+ * Descriptor for the local-embedding route the engine exposes. The
+ * route's job is `text[] → number[dim][]`; the runtime mounts the source
+ * (pooled text or dedicated region) and forwards. Kept as a plain data
+ * shape so both the API layer and tests can assert it without standing up
+ * a server.
+ */
+export interface LocalEmbeddingRoute {
+    readonly tierId: Eliza1TierId;
+    readonly source: LocalEmbeddingSource;
+    /** Full output dimensionality the route produces before truncation. 1024 on every tier. */
+    readonly dimensions: typeof EMBEDDING_FULL_DIM;
+    /**
+     * Default Matryoshka width the route returns when a caller does not ask
+     * for a smaller `dim`. Always 1024 (= `dimensions`) — callers/the vector
+     * store opt into a smaller width for storage savings.
+     */
+    readonly defaultDim: number;
+    /** The Matryoshka widths a caller may request. */
+    readonly matryoshkaDims: readonly number[];
+    /**
+     * `llama-server` flags for the embedding server process — always
+     * `--embeddings --pooling last`. The embedding server is a lazily-started
+     * sidecar over the route's GGUF (the text backbone on the `2b` entry tier,
+     * the `embedding/` GGUF on larger tiers); see `embedding-server.ts`. The
+     * chat `llama-server` is left untouched (completions-only) — these flags
+     * do NOT go on it.
+     */
+    readonly serverFlags: ReadonlyArray<string>;
+}
+export declare function buildLocalEmbeddingRoute(args: {
+    bundleRoot: string;
+    tierId: Eliza1TierId;
+    textModelPath: string;
+    /** Default output width; must be one of `EMBEDDING_MATRYOSHKA_DIMS`. Defaults to 1024. */
+    defaultDim?: number;
+}): LocalEmbeddingRoute;
+//# sourceMappingURL=embedding.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../../src/services/voice/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAElD,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,EAAG,IAAa,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAEtD,CAAC;AAEF,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,SAAS,MAAM,EAAE,EACtB,GAAG,EAAE,MAAM,GACT,MAAM,EAAE,CAiBV;AAYD,MAAM,MAAM,oBAAoB,GAC7B;IACA,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC5B,GACD;IACA,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,OAAO,kBAAkB,CAAC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC5B,CAAC;AAaL;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,YAAY,CAEhE,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACtB,GAAG,oBAAoB,CA4BvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,OAAO,kBAAkB,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC5C;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,mBAAmB,CAoBtB"}

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

@@ -0,0 +1,68 @@
+import { type ExpressiveEmotion } from "./expressive-tags";
+import type { VoiceEmotionClassifierOutput, VoiceEmotionVad } from "./voice-emotion-classifier";
+export type VoiceEmotionAttributionMethod = "none" | "text_tag" | "text_audio_heuristic" | "explicit_asr_metadata" | "acoustic_model" | "acoustic_text_fused";
+export interface VoiceEmotionAudioFeatures {
+    durationMs?: number;
+    rms?: number;
+    zeroCrossingRate?: number;
+    speechRateWpm?: number;
+    meanPitchHz?: number;
+    pitchStdHz?: number;
+}
+export interface VoiceEmotionAsrFeatures {
+    transcript?: string;
+    confidence?: number;
+    /**
+     * Optional structured metadata supplied by an ASR service. The local fused
+     * ASR path does not currently advertise model-native emotion labels, so this
+     * is ignored unless `emotionLabelSupported` is explicitly true.
+     */
+    emotionLabel?: string | null;
+    emotionLabelSupported?: boolean;
+}
+/**
+ * Acoustic-model emotion read fed in as a *fusion* source — the result of
+ * running the Wav2Small student (`VoiceEmotionClassifier.classify()`) over
+ * the utterance window. Pass the raw classifier output directly; the
+ * fusion logic in `attributeVoiceEmotion` is the single place that combines
+ * acoustic + text-side evidence (R3-emotion §3, "Two confidence scores,
+ * no fusion rule" risk).
+ */
+export interface VoiceEmotionModelInput {
+    output: VoiceEmotionClassifierOutput;
+    /** Stable model id recorded on the resulting evidence row. */
+    modelId?: string;
+}
+export interface VoiceEmotionAttributionInput {
+    text?: string;
+    asr?: VoiceEmotionAsrFeatures;
+    audio?: VoiceEmotionAudioFeatures;
+    /**
+     * Acoustic classifier output — the Wav2Small read. Optional; when absent
+     * the attribution falls back to the lexicon + audio-prosody heuristic
+     * (which is what `evidence.source === "audio_prosody"` covers).
+     */
+    model?: VoiceEmotionModelInput;
+}
+export interface VoiceEmotionEvidence {
+    source: "text_expressive_tag" | "text_lexicon" | "audio_prosody" | "asr_transcript" | "asr_emotion_metadata" | "asr_emotion_metadata_ignored" | "acoustic_model";
+    detail: string;
+    confidence: number;
+}
+export interface VoiceEmotionAttribution {
+    emotion: ExpressiveEmotion | null;
+    confidence: number;
+    method: VoiceEmotionAttributionMethod;
+    modelNativeEmotion: false;
+    evidence: VoiceEmotionEvidence[];
+    scores: Record<ExpressiveEmotion, number>;
+    /**
+     * Continuous V-A-D from the acoustic classifier when one was supplied via
+     * `model`. Carried through so downstream consumers (planner provider,
+     * memory tagging, bench) can read the raw continuous signal instead of the
+     * projected discrete label.
+     */
+    vad?: VoiceEmotionVad;
+}
+export declare function attributeVoiceEmotion(input: VoiceEmotionAttributionInput): VoiceEmotionAttribution;
+//# sourceMappingURL=emotion-attribution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emotion-attribution.d.ts","sourceRoot":"","sources":["../../../src/services/voice/emotion-attribution.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,iBAAiB,EAGtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACX,4BAA4B,EAC5B,eAAe,EACf,MAAM,4BAA4B,CAAC;AAEpC,MAAM,MAAM,6BAA6B,GACtC,MAAM,GACN,UAAU,GACV,sBAAsB,GACtB,uBAAuB,GACvB,gBAAgB,GAChB,qBAAqB,CAAC;AAEzB,MAAM,WAAW,yBAAyB;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,4BAA4B,CAAC;IACrC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,uBAAuB,CAAC;IAC9B,KAAK,CAAC,EAAE,yBAAyB,CAAC;IAClC;;;;OAIG;IACH,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACpC,MAAM,EACH,qBAAqB,GACrB,cAAc,GACd,eAAe,GACf,gBAAgB,GAChB,sBAAsB,GACtB,8BAA8B,GAC9B,gBAAgB,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACvC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,6BAA6B,CAAC;IACtC,kBAAkB,EAAE,KAAK,CAAC;IAC1B,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAC;IAC1C;;;;;OAKG;IACH,GAAG,CAAC,EAAE,eAAe,CAAC;CACtB;AAoGD,wBAAgB,qBAAqB,CACpC,KAAK,EAAE,4BAA4B,GACjC,uBAAuB,CAgKzB"}