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

package/src/services/voice/speaker/encoder-ggml.ts

@@ -0,0 +1,79 @@
+/**
+ * Speaker-embedding encoder — shared constants, error class, and the
+ * embedding-distance helper.
+ *
+ * The speaker encoder runs EXCLUSIVELY through the fused `libelizainference`
+ * `eliza_inference_speaker_*` ABI (`FusedSpeakerEncoder` in `encoder-fused.ts`).
+ * The standalone `libvoice_classifier` binding that previously lived here has
+ * been removed — there is one on-device voice runtime.
+ *
+ * This module retains the pieces the fused path shares:
+ *   - the canonical dims (`SPEAKER_GGML_*`), pinned at 256 to match the C-side
+ *     `VOICE_SPEAKER_EMBEDDING_DIM` and the WeSpeaker ResNet34-LM head,
+ *   - the structured `SpeakerEncoderGgmlUnavailableError` the fused encoder
+ *     throws (no synthetic embedding fallback),
+ *   - the pure `voiceSpeakerDistance` cosine-distance helper.
+ */
+
+/** Output embedding dim. Matches `VOICE_SPEAKER_EMBEDDING_DIM`. */
+export const SPEAKER_GGML_EMBEDDING_DIM = 256;
+
+/** Required input sample rate. */
+export const SPEAKER_GGML_SAMPLE_RATE = 16_000;
+
+/** Minimum useful audio window (~1.0 s). */
+export const SPEAKER_GGML_MIN_SAMPLES = 16_000;
+
+export class SpeakerEncoderGgmlUnavailableError extends Error {
+	readonly code:
+		| "native-missing"
+		| "library-missing"
+		| "model-missing"
+		| "model-load-failed"
+		| "model-shape-mismatch"
+		| "forward-not-implemented"
+		| "invalid-input";
+	constructor(
+		code: SpeakerEncoderGgmlUnavailableError["code"],
+		message: string,
+	) {
+		super(message);
+		this.name = "SpeakerEncoderGgmlUnavailableError";
+		this.code = code;
+	}
+}
+
+/**
+ * Cosine distance between two 256-dim speaker embeddings. Defined as
+ * `1 - cos_similarity(a, b)`, range [0, 2]. Mirrors the C-side
+ * `voice_speaker_distance` helper exactly.
+ */
+export function voiceSpeakerDistance(a: Float32Array, b: Float32Array): number {
+	if (a.length !== SPEAKER_GGML_EMBEDDING_DIM) {
+		throw new SpeakerEncoderGgmlUnavailableError(
+			"invalid-input",
+			`[speaker] left embedding has dim ${a.length}, expected ${SPEAKER_GGML_EMBEDDING_DIM}`,
+		);
+	}
+	if (b.length !== SPEAKER_GGML_EMBEDDING_DIM) {
+		throw new SpeakerEncoderGgmlUnavailableError(
+			"invalid-input",
+			`[speaker] right embedding has dim ${b.length}, expected ${SPEAKER_GGML_EMBEDDING_DIM}`,
+		);
+	}
+	let dot = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let i = 0; i < SPEAKER_GGML_EMBEDDING_DIM; i += 1) {
+		const av = a[i];
+		const bv = b[i];
+		dot += av * bv;
+		normA += av * av;
+		normB += bv * bv;
+	}
+	if (normA <= 0 || normB <= 0) return 1;
+	let cosine = dot / (Math.sqrt(normA) * Math.sqrt(normB));
+	if (cosine > 1) cosine = 1;
+	if (cosine < -1) cosine = -1;
+	return 1 - cosine;
+}

package/src/services/voice/speaker/encoder.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Speaker-embedding encoder — shared contract, model-id constants, and the
+ * `averageEmbeddings` centroid helper.
+ *
+ * The speaker encoder runs EXCLUSIVELY through the fused `libelizainference`
+ * `eliza_inference_speaker_*` ABI (`FusedSpeakerEncoder` in `encoder-fused.ts`).
+ * The standalone `WespeakerEncoder` (`libvoice_classifier`) binding has been
+ * removed — there is one on-device voice runtime.
+ *
+ * This module retains the cross-cutting pieces every encoder caller shares:
+ *   - the `SpeakerEncoder` interface the fused encoder implements,
+ *   - the stored model-id strings (kept stable so existing voice profiles in
+ *     the database stay valid),
+ *   - the canonical dims (re-exported from `encoder-ggml`),
+ *   - the `SpeakerEncoderUnavailableError` the enrollment routes raise,
+ *   - the pure `averageEmbeddings` centroid helper.
+ */
+export declare const WESPEAKER_RESNET34_LM_INT8_MODEL_ID: "wespeaker-resnet34-lm-int8";
+export declare const WESPEAKER_RESNET34_LM_FP32_MODEL_ID: "wespeaker-resnet34-lm-fp32";
+export type WespeakerModelId = typeof WESPEAKER_RESNET34_LM_INT8_MODEL_ID | typeof WESPEAKER_RESNET34_LM_FP32_MODEL_ID;
+export declare const WESPEAKER_EMBEDDING_DIM = 256;
+export declare const WESPEAKER_SAMPLE_RATE = 16000;
+export declare const WESPEAKER_MIN_SAMPLES = 16000;
+export declare class SpeakerEncoderUnavailableError extends Error {
+    readonly code: "native-missing" | "library-missing" | "model-missing" | "model-load-failed" | "model-shape-mismatch" | "forward-not-implemented" | "invalid-input";
+    constructor(code: SpeakerEncoderUnavailableError["code"], message: string);
+}
+/** The minimal contract every speaker encoder honors. */
+export interface SpeakerEncoder {
+    readonly embeddingDim: number;
+    readonly sampleRate: number;
+    readonly modelId?: string;
+    encode(pcm: Float32Array): Promise<Float32Array>;
+    dispose(): Promise<void>;
+}
+export declare function averageEmbeddings(embeddings: readonly Float32Array[]): Float32Array;
+//# sourceMappingURL=encoder.d.ts.map

package/src/services/voice/speaker/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["encoder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAeH,eAAO,MAAM,mCAAmC,EAC/C,4BAAqC,CAAC;AACvC,eAAO,MAAM,mCAAmC,EAC/C,4BAAqC,CAAC;AACvC,MAAM,MAAM,gBAAgB,GACzB,OAAO,mCAAmC,GAC1C,OAAO,mCAAmC,CAAC;AAE9C,eAAO,MAAM,uBAAuB,MAA6B,CAAC;AAClE,eAAO,MAAM,qBAAqB,QAA2B,CAAC;AAC9D,eAAO,MAAM,qBAAqB,QAA2B,CAAC;AAM9D,qBAAa,8BAA+B,SAAQ,KAAK;IACxD,QAAQ,CAAC,IAAI,EACV,gBAAgB,GAChB,iBAAiB,GACjB,eAAe,GACf,mBAAmB,GACnB,sBAAsB,GACtB,yBAAyB,GACzB,eAAe,CAAC;gBACP,IAAI,EAAE,8BAA8B,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM;CAKzE;AAMD,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACjD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAMD,wBAAgB,iBAAiB,CAChC,UAAU,EAAE,SAAS,YAAY,EAAE,GACjC,YAAY,CAsBd"}

package/src/services/voice/speaker/encoder.ts

@@ -0,0 +1,105 @@
+/**
+ * Speaker-embedding encoder — shared contract, model-id constants, and the
+ * `averageEmbeddings` centroid helper.
+ *
+ * The speaker encoder runs EXCLUSIVELY through the fused `libelizainference`
+ * `eliza_inference_speaker_*` ABI (`FusedSpeakerEncoder` in `encoder-fused.ts`).
+ * The standalone `WespeakerEncoder` (`libvoice_classifier`) binding has been
+ * removed — there is one on-device voice runtime.
+ *
+ * This module retains the cross-cutting pieces every encoder caller shares:
+ *   - the `SpeakerEncoder` interface the fused encoder implements,
+ *   - the stored model-id strings (kept stable so existing voice profiles in
+ *     the database stay valid),
+ *   - the canonical dims (re-exported from `encoder-ggml`),
+ *   - the `SpeakerEncoderUnavailableError` the enrollment routes raise,
+ *   - the pure `averageEmbeddings` centroid helper.
+ */
+
+import { normalizeVoiceEmbedding } from "../speaker-imprint";
+import {
+	SPEAKER_GGML_EMBEDDING_DIM,
+	SPEAKER_GGML_MIN_SAMPLES,
+	SPEAKER_GGML_SAMPLE_RATE,
+} from "./encoder-ggml";
+
+// ---------------------------------------------------------------------------
+// Stored model id constants.
+// The model id strings are kept stable for compatibility with stored profiles
+// (changing them would invalidate any existing voice profiles in the database).
+// ---------------------------------------------------------------------------
+
+export const WESPEAKER_RESNET34_LM_INT8_MODEL_ID =
+	"wespeaker-resnet34-lm-int8" as const;
+export const WESPEAKER_RESNET34_LM_FP32_MODEL_ID =
+	"wespeaker-resnet34-lm-fp32" as const;
+export type WespeakerModelId =
+	| typeof WESPEAKER_RESNET34_LM_INT8_MODEL_ID
+	| typeof WESPEAKER_RESNET34_LM_FP32_MODEL_ID;
+
+export const WESPEAKER_EMBEDDING_DIM = SPEAKER_GGML_EMBEDDING_DIM;
+export const WESPEAKER_SAMPLE_RATE = SPEAKER_GGML_SAMPLE_RATE;
+export const WESPEAKER_MIN_SAMPLES = SPEAKER_GGML_MIN_SAMPLES;
+
+// ---------------------------------------------------------------------------
+// Structured error.
+// ---------------------------------------------------------------------------
+
+export class SpeakerEncoderUnavailableError extends Error {
+	readonly code:
+		| "native-missing"
+		| "library-missing"
+		| "model-missing"
+		| "model-load-failed"
+		| "model-shape-mismatch"
+		| "forward-not-implemented"
+		| "invalid-input";
+	constructor(code: SpeakerEncoderUnavailableError["code"], message: string) {
+		super(message);
+		this.name = "SpeakerEncoderUnavailableError";
+		this.code = code;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// SpeakerEncoder interface.
+// ---------------------------------------------------------------------------
+
+/** The minimal contract every speaker encoder honors. */
+export interface SpeakerEncoder {
+	readonly embeddingDim: number;
+	readonly sampleRate: number;
+	readonly modelId?: string;
+	encode(pcm: Float32Array): Promise<Float32Array>;
+	dispose(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// averageEmbeddings — pure centroid helper.
+// ---------------------------------------------------------------------------
+
+export function averageEmbeddings(
+	embeddings: readonly Float32Array[],
+): Float32Array {
+	if (embeddings.length === 0) {
+		throw new SpeakerEncoderUnavailableError(
+			"invalid-input",
+			"[wespeaker] averageEmbeddings called with no inputs",
+		);
+	}
+	const dim = embeddings[0].length;
+	const sum = new Float64Array(dim);
+	for (const emb of embeddings) {
+		if (emb.length !== dim) {
+			throw new SpeakerEncoderUnavailableError(
+				"invalid-input",
+				`[wespeaker] embedding dim mismatch: ${emb.length} vs ${dim}`,
+			);
+		}
+		for (let i = 0; i < dim; i += 1) sum[i] += emb[i];
+	}
+	const out = new Float32Array(dim);
+	for (let i = 0; i < dim; i += 1) out[i] = sum[i] / embeddings.length;
+	const normalized = normalizeVoiceEmbedding(out);
+	return Float32Array.from(normalized);
+}

package/src/services/voice/speaker-imprint.d.ts

@@ -0,0 +1,83 @@
+import type { VoiceInputSource, VoiceSegment, VoiceSpeaker } from "./types";
+export declare const DEFAULT_VOICE_IMPRINT_MATCH_THRESHOLD = 0.78;
+export interface VoiceImprintProfile {
+    id: string;
+    centroidEmbedding: ArrayLike<number> | null | undefined;
+    embeddingModel?: string | null;
+    sampleCount?: number | null;
+    confidence?: number | null;
+    label?: string | null;
+    displayName?: string | null;
+    entityId?: string | null;
+    sourceKind?: string | null;
+    sourceScopeId?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface VoiceImprintMatch {
+    profile: VoiceImprintProfile;
+    similarity: number;
+    confidence: number;
+}
+export interface VoiceImprintCentroidUpdate {
+    centroidEmbedding: number[];
+    sampleCount: number;
+    confidence: number;
+}
+export interface VoiceImprintObservationInput {
+    id: string;
+    segmentId?: string;
+    text: string;
+    startMs: number;
+    endMs: number;
+    embedding: ArrayLike<number>;
+    embeddingModel?: string | null;
+    confidence?: number | null;
+    source?: VoiceInputSource;
+    metadata?: Record<string, unknown> | null;
+}
+export interface AttributedVoiceObservation {
+    observation: VoiceImprintObservationInput;
+    match: VoiceImprintMatch | null;
+    speaker: VoiceSpeaker | null;
+    segment: VoiceSegment;
+}
+export interface SpeakerAttributionResult {
+    observations: AttributedVoiceObservation[];
+    segments: VoiceSegment[];
+    primarySpeaker?: VoiceSpeaker;
+    summary: {
+        totalObservations: number;
+        matchedObservations: number;
+        unmatchedObservations: number;
+        meanConfidence: number;
+        meanSimilarity: number | null;
+    };
+}
+export declare function normalizeVoiceEmbedding(embedding: ArrayLike<number>): number[];
+export declare function cosineSimilarity(left: ArrayLike<number>, right: ArrayLike<number>): number;
+export declare function updateVoiceImprintCentroid(args: {
+    centroidEmbedding?: ArrayLike<number> | null;
+    sampleCount?: number | null;
+    confidence?: number | null;
+    observationEmbedding: ArrayLike<number>;
+    observationConfidence?: number | null;
+    maxObservationWeight?: number;
+}): VoiceImprintCentroidUpdate;
+export declare function matchVoiceImprint(args: {
+    embedding: ArrayLike<number>;
+    profiles: readonly VoiceImprintProfile[];
+    embeddingModel?: string | null;
+    threshold?: number;
+}): VoiceImprintMatch | null;
+export declare function voiceSpeakerFromImprintMatch(args: {
+    match: VoiceImprintMatch;
+    source?: VoiceInputSource;
+    observationId?: string;
+}): VoiceSpeaker;
+export declare function attributeVoiceImprintObservations(args: {
+    observations: readonly VoiceImprintObservationInput[];
+    profiles: readonly VoiceImprintProfile[];
+    threshold?: number;
+    defaultSource?: VoiceInputSource;
+}): SpeakerAttributionResult;
+//# sourceMappingURL=speaker-imprint.d.ts.map

package/src/services/voice/speaker-imprint.d.ts.map

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

package/src/services/voice/speaker-imprint.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+import {
+	attributeVoiceImprintObservations,
+	cosineSimilarity,
+	matchVoiceImprint,
+	normalizeVoiceEmbedding,
+	updateVoiceImprintCentroid,
+	type VoiceImprintProfile,
+	voiceSpeakerFromImprintMatch,
+} from "./speaker-imprint";
+
+describe("speaker-imprint", () => {
+	it("normalizes embeddings and computes cosine similarity", () => {
+		const normalized = normalizeVoiceEmbedding([3, 4]);
+		expect(normalized[0]).toBeCloseTo(0.6, 6);
+		expect(normalized[1]).toBeCloseTo(0.8, 6);
+		expect(cosineSimilarity([2, 0], [4, 0])).toBeCloseTo(1, 6);
+		expect(cosineSimilarity([1, 0], [0, 1])).toBeCloseTo(0, 6);
+	});
+
+	it("matches the nearest compatible voice imprint above threshold", () => {
+		const profiles: VoiceImprintProfile[] = [
+			{
+				id: "cluster-a",
+				label: "Owner",
+				centroidEmbedding: [1, 0],
+				embeddingModel: "eliza-voice-embed-v1",
+				confidence: 0.9,
+				entityId: "entity-owner",
+			},
+			{
+				id: "cluster-b",
+				label: "Guest",
+				centroidEmbedding: [0, 1],
+				embeddingModel: "eliza-voice-embed-v1",
+				confidence: 0.9,
+			},
+		];
+
+		const match = matchVoiceImprint({
+			embedding: [0.98, 0.05],
+			embeddingModel: "eliza-voice-embed-v1",
+			profiles,
+			threshold: 0.8,
+		});
+
+		expect(match?.profile.id).toBe("cluster-a");
+		expect(match?.similarity).toBeGreaterThan(0.99);
+		if (!match) throw new Error("expected voice imprint match");
+		const speaker = voiceSpeakerFromImprintMatch({
+			match,
+			observationId: "obs-1",
+			source: { kind: "local_mic", deviceId: "mic-1" },
+		});
+		expect(speaker.entityId).toBe("entity-owner");
+		expect(speaker.imprintClusterId).toBe("cluster-a");
+		expect(speaker.imprintObservationId).toBe("obs-1");
+		expect(speaker.source?.kind).toBe("local_mic");
+	});
+
+	it("does not match across embedding-model or dimension mismatches", () => {
+		const profiles: VoiceImprintProfile[] = [
+			{
+				id: "cluster-a",
+				centroidEmbedding: [1, 0],
+				embeddingModel: "other-model",
+			},
+			{
+				id: "cluster-b",
+				centroidEmbedding: [1, 0, 0],
+				embeddingModel: "eliza-voice-embed-v1",
+			},
+		];
+
+		expect(
+			matchVoiceImprint({
+				embedding: [1, 0],
+				embeddingModel: "eliza-voice-embed-v1",
+				profiles,
+			}),
+		).toBeNull();
+	});
+
+	it("updates a centroid with weighted observations", () => {
+		const first = updateVoiceImprintCentroid({
+			observationEmbedding: [10, 0],
+			observationConfidence: 0.8,
+		});
+		expect(first.centroidEmbedding).toEqual([1, 0]);
+		expect(first.sampleCount).toBe(1);
+		expect(first.confidence).toBeCloseTo(0.8, 6);
+
+		const second = updateVoiceImprintCentroid({
+			centroidEmbedding: first.centroidEmbedding,
+			sampleCount: first.sampleCount,
+			confidence: first.confidence,
+			observationEmbedding: [0, 10],
+			observationConfidence: 0.5,
+		});
+		expect(second.sampleCount).toBe(2);
+		expect(second.centroidEmbedding[0]).toBeGreaterThan(
+			second.centroidEmbedding[1],
+		);
+		expect(second.confidence).toBeCloseTo(0.65, 6);
+	});
+
+	it("attributes diarized observation embeddings without granting synthesis or identity authority", () => {
+		const profiles: VoiceImprintProfile[] = [
+			{
+				id: "cluster-owner",
+				label: "Owner",
+				displayName: "Owner",
+				entityId: "entity-owner",
+				centroidEmbedding: [1, 0],
+				embeddingModel: "eliza-voice-embed-v1",
+				confidence: 0.9,
+			},
+			{
+				id: "cluster-guest",
+				label: "Guest",
+				entityId: "entity-guest",
+				centroidEmbedding: [0, 1],
+				embeddingModel: "eliza-voice-embed-v1",
+				confidence: 0.8,
+			},
+		];
+		const source = {
+			kind: "local_mic" as const,
+			deviceId: "default-input",
+			roomId: "room-1",
+		};
+
+		const result = attributeVoiceImprintObservations({
+			defaultSource: source,
+			profiles,
+			threshold: 0.8,
+			observations: [
+				{
+					id: "obs-owner-1",
+					segmentId: "seg-owner-1",
+					text: "I am the owner",
+					startMs: 0,
+					endMs: 1200,
+					embedding: [0.99, 0.02],
+					embeddingModel: "eliza-voice-embed-v1",
+				},
+				{
+					id: "obs-guest-1",
+					segmentId: "seg-guest-1",
+					text: "and I am a guest",
+					startMs: 1300,
+					endMs: 2100,
+					embedding: [0.02, 0.99],
+					embeddingModel: "eliza-voice-embed-v1",
+				},
+			],
+		});
+
+		expect(result.summary).toMatchObject({
+			totalObservations: 2,
+			matchedObservations: 2,
+			unmatchedObservations: 0,
+		});
+		expect(result.primarySpeaker?.entityId).toBe("entity-owner");
+		expect(result.segments.map((segment) => segment.speaker?.entityId)).toEqual(
+			["entity-owner", "entity-guest"],
+		);
+		expect(result.segments[0].metadata).toMatchObject({
+			attributionOnly: true,
+			evidenceKind: "voice_imprint_attribution",
+			identityAuthority: false,
+			synthesisAuthorization: false,
+			diarizationMode: "attribution_only",
+			imprintClusterId: "cluster-owner",
+			imprintObservationId: "obs-owner-1",
+			entityId: "entity-owner",
+		});
+		expect(result.segments[0].speaker?.metadata).toMatchObject({
+			attributionOnly: true,
+			evidenceKind: "voice_imprint_attribution",
+			identityAuthority: false,
+			synthesisAuthorization: false,
+		});
+	});
+});