@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.11-beta.7

package/src/services/voice/speaker/attribution-pipeline.ts

@@ -0,0 +1,386 @@
+/**
+ * Speaker-ID + diarization attribution pipeline.
+ *
+ * Wraps a `StreamingTranscriber` so the partial / final
+ * `TranscriptUpdate`s carry diarized `VoiceSegment[]` and a
+ * `primarySpeaker`. The attribution runs in parallel with ASR — the
+ * encoder fires the moment ≥ 1 s of audio is available, and the
+ * profile store's `beginMatch` starts at speech-start.
+ *
+ * This module owns *only* the attribution logic. It does NOT replace
+ * the transcriber; callers feed PCM through both the transcriber and
+ * the attributor in parallel, then attach the resolved metadata via
+ * `BaseStreamingTranscriber.setMetadataDefaults()` once it lands.
+ *
+ * Why a separate module: the existing `VoicePipeline` is large and
+ * already handles a lot. Putting attribution behind a small adapter
+ * lets the voice pipeline opt in without entangling the diarizer /
+ * encoder / profile-store dependencies into the streaming-ASR contract.
+ */
+
+import type {
+	VoiceProfileObservation,
+	VoiceProfileStore,
+} from "../profile-store";
+import { voiceSpeakerFromImprintMatch } from "../speaker-imprint";
+import type {
+	VoiceInputSource,
+	VoiceSegment,
+	VoiceSpeaker,
+	VoiceTurnMetadata,
+} from "../types";
+import type { Diarizer, LocalSpeakerSegment } from "./diarizer";
+import type { SpeakerEncoder } from "./encoder";
+import { WESPEAKER_MIN_SAMPLES } from "./encoder";
+
+export interface VoiceAttributionPipelineDeps {
+	encoder: SpeakerEncoder;
+	diarizer?: Diarizer;
+	profileStore: VoiceProfileStore;
+}
+
+export interface VoiceAttributionRequest {
+	turnId: string;
+	source?: VoiceInputSource;
+	/** Concatenated mono 16 kHz PCM for the entire turn. */
+	pcm: Float32Array;
+	startedAtMs?: number;
+	endedAtMs?: number;
+	/** When set, the attributor will only run if the abort signal isn't yet fired. */
+	signal?: AbortSignal;
+}
+
+export interface VoiceAttributionOutput {
+	turnId: string;
+	primarySpeaker?: VoiceSpeaker;
+	segments: VoiceSegment[];
+	turn: VoiceTurnMetadata;
+	observation: VoiceProfileObservation | null;
+}
+
+function nonOverlappingSegments(
+	local: ReadonlyArray<LocalSpeakerSegment>,
+): LocalSpeakerSegment[] {
+	if (local.length === 0) return [];
+	return local
+		.filter((seg) => !seg.hasOverlap)
+		.sort((a, b) =>
+			a.startMs !== b.startMs ? a.startMs - b.startMs : a.endMs - b.endMs,
+		);
+}
+
+function pickPrimaryLocalSpeaker(
+	local: ReadonlyArray<LocalSpeakerSegment>,
+): number | null {
+	if (local.length === 0) return null;
+	const durations = new Map<number, number>();
+	for (const seg of local) {
+		const ms = Math.max(0, seg.endMs - seg.startMs);
+		durations.set(
+			seg.localSpeakerId,
+			(durations.get(seg.localSpeakerId) ?? 0) + ms,
+		);
+	}
+	let best: { id: number; ms: number } | null = null;
+	for (const [id, ms] of durations.entries()) {
+		if (!best || ms > best.ms) best = { id, ms };
+	}
+	return best?.id ?? null;
+}
+
+/**
+ * Run the diarizer + encoder + profile-store against a complete turn's
+ * audio. The caller is responsible for slicing the audio buffer (the
+ * pipeline's prefix queue already buffers the entire utterance for
+ * the streaming-ASR path).
+ *
+ * The high-level flow:
+ *   1. Diarizer runs on the full PCM, producing per-segment speaker
+ *      tags (window-local ids).
+ *   2. We pick the longest local-speaker span and run the encoder on
+ *      that span (≥ 1 s) to produce a 256-dim embedding.
+ *   3. The embedding is matched against the profile store. On hit,
+ *      attribute the turn to the matched profile's entity. On miss,
+ *      create a new cluster profile (no entity binding — that happens
+ *      at the LifeOps layer based on utterance text).
+ *   4. Build `VoiceSegment[]` with the resolved speaker, plus a
+ *      `VoiceTurnMetadata` for downstream consumers.
+ */
+export class VoiceAttributionPipeline {
+	constructor(private readonly deps: VoiceAttributionPipelineDeps) {}
+
+	async attribute(
+		req: VoiceAttributionRequest,
+	): Promise<VoiceAttributionOutput> {
+		if (req.signal?.aborted) {
+			return this.buildEmptyOutput(req);
+		}
+		// Diarizer is optional — when missing we treat the whole turn as
+		// one segment with `localSpeakerId=0`.
+		let local: LocalSpeakerSegment[] = [];
+		if (this.deps.diarizer) {
+			try {
+				const out = await this.deps.diarizer.diarizeWindow(req.pcm);
+				local = nonOverlappingSegments(out.segments);
+			} catch {
+				local = [];
+			}
+		}
+		if (local.length === 0) {
+			local = [
+				{
+					startMs: 0,
+					endMs: Math.round(
+						(req.pcm.length / this.deps.encoder.sampleRate) * 1000,
+					),
+					localSpeakerId: 0,
+					confidence: 0.5,
+					hasOverlap: false,
+				},
+			];
+		}
+		const primaryLocal = pickPrimaryLocalSpeaker(local);
+		if (primaryLocal === null) return this.buildEmptyOutput(req);
+		// Concatenate the primary local speaker's spans into a single PCM
+		// window for the embedding.
+		const primarySpans = local.filter(
+			(seg) => seg.localSpeakerId === primaryLocal,
+		);
+		const window = this.spliceSpans(req.pcm, primarySpans);
+		if (window.length < WESPEAKER_MIN_SAMPLES) {
+			// Not enough audio for a stable embedding — emit an
+			// "unknown speaker" segment, no profile observation.
+			const turn: VoiceTurnMetadata = {
+				turnId: req.turnId,
+				source: req.source,
+				segments: this.localToUnknownSegments(local, req.source),
+				...(req.startedAtMs !== undefined
+					? { startedAtMs: req.startedAtMs }
+					: {}),
+				...(req.endedAtMs !== undefined ? { endedAtMs: req.endedAtMs } : {}),
+				diarization: this.deps.diarizer
+					? {
+							provider: "local",
+							model: this.deps.diarizer.modelId,
+							version: "v1",
+						}
+					: undefined,
+			};
+			return {
+				turnId: req.turnId,
+				segments: turn.segments ?? [],
+				turn,
+				observation: null,
+			};
+		}
+		if (req.signal?.aborted) return this.buildEmptyOutput(req);
+
+		const embedding = await this.deps.encoder.encode(window);
+		if (req.signal?.aborted) return this.buildEmptyOutput(req);
+
+		const match = await this.deps.profileStore.findBestMatch({
+			embedding,
+			embeddingModel: this.deps.encoder.modelId ?? "",
+		});
+
+		let observation: VoiceProfileObservation;
+		let speaker: VoiceSpeaker;
+		if (match) {
+			// Update the existing profile with the new observation.
+			const refined = await this.deps.profileStore.refine({
+				profileId: match.profile.id,
+				embedding,
+				durationMs: this.spanMsTotal(primarySpans),
+				confidence: match.confidence,
+			});
+			observation = {
+				profileId: match.profile.id,
+				imprintClusterId: match.profile.sourceScopeId ?? match.profile.id,
+				entityId: refined?.entityId ?? match.profile.entityId ?? null,
+				embedding,
+				embeddingModel: this.deps.encoder.modelId ?? "",
+				confidence: match.confidence,
+				source: req.source,
+				startMs: primarySpans[0]?.startMs,
+				endMs: primarySpans[primarySpans.length - 1]?.endMs,
+			};
+			speaker = voiceSpeakerFromImprintMatch({
+				match,
+				source: req.source,
+				observationId: req.turnId,
+			});
+		} else {
+			// Create a new cluster.
+			const created = await this.deps.profileStore.createProfile({
+				centroid: embedding,
+				embeddingModel: this.deps.encoder.modelId ?? "",
+				entityId: null,
+				confidence: 0.5,
+				durationMs: this.spanMsTotal(primarySpans),
+			});
+			observation = {
+				profileId: created.profileId,
+				imprintClusterId: created.imprintClusterId,
+				entityId: null,
+				embedding,
+				embeddingModel: this.deps.encoder.modelId ?? "",
+				confidence: 0.5,
+				source: req.source,
+				startMs: primarySpans[0]?.startMs,
+				endMs: primarySpans[primarySpans.length - 1]?.endMs,
+			};
+			speaker = {
+				id: created.imprintClusterId,
+				imprintClusterId: created.imprintClusterId,
+				imprintObservationId: req.turnId,
+				entityId: undefined,
+				source: req.source,
+				confidence: 0.5,
+				metadata: {
+					attributionOnly: true,
+					evidenceKind: "voice_imprint_attribution",
+					identityAuthority: false,
+					synthesisAuthorization: false,
+					embeddingModel: this.deps.encoder.modelId ?? "",
+					profileId: created.profileId,
+				},
+			};
+		}
+
+		const segments = this.localToVoiceSegments(
+			local,
+			primaryLocal,
+			speaker,
+			req.source,
+		);
+
+		const turn: VoiceTurnMetadata = {
+			turnId: req.turnId,
+			source: req.source,
+			primarySpeaker: speaker,
+			segments,
+			...(req.startedAtMs !== undefined
+				? { startedAtMs: req.startedAtMs }
+				: {}),
+			...(req.endedAtMs !== undefined ? { endedAtMs: req.endedAtMs } : {}),
+			diarization: this.deps.diarizer
+				? {
+						provider: "local",
+						model: this.deps.diarizer.modelId,
+						version: "v1",
+						confidence: match?.confidence,
+					}
+				: undefined,
+		};
+
+		return {
+			turnId: req.turnId,
+			primarySpeaker: speaker,
+			segments,
+			turn,
+			observation,
+		};
+	}
+
+	private buildEmptyOutput(
+		req: VoiceAttributionRequest,
+	): VoiceAttributionOutput {
+		const turn: VoiceTurnMetadata = {
+			turnId: req.turnId,
+			source: req.source,
+			segments: [],
+			...(req.startedAtMs !== undefined
+				? { startedAtMs: req.startedAtMs }
+				: {}),
+			...(req.endedAtMs !== undefined ? { endedAtMs: req.endedAtMs } : {}),
+		};
+		return { turnId: req.turnId, segments: [], turn, observation: null };
+	}
+
+	private spliceSpans(
+		pcm: Float32Array,
+		spans: ReadonlyArray<LocalSpeakerSegment>,
+	): Float32Array {
+		const sr = this.deps.encoder.sampleRate;
+		// Compute total length first so we can allocate once.
+		let total = 0;
+		for (const span of spans) {
+			const a = Math.max(0, Math.floor((span.startMs / 1000) * sr));
+			const b = Math.min(pcm.length, Math.ceil((span.endMs / 1000) * sr));
+			if (b > a) total += b - a;
+		}
+		if (total === 0) return new Float32Array(0);
+		const out = new Float32Array(total);
+		let cursor = 0;
+		for (const span of spans) {
+			const a = Math.max(0, Math.floor((span.startMs / 1000) * sr));
+			const b = Math.min(pcm.length, Math.ceil((span.endMs / 1000) * sr));
+			if (b > a) {
+				out.set(pcm.subarray(a, b), cursor);
+				cursor += b - a;
+			}
+		}
+		return out;
+	}
+
+	private spanMsTotal(spans: ReadonlyArray<LocalSpeakerSegment>): number {
+		let total = 0;
+		for (const span of spans) total += Math.max(0, span.endMs - span.startMs);
+		return total;
+	}
+
+	private localToVoiceSegments(
+		local: ReadonlyArray<LocalSpeakerSegment>,
+		primaryLocalId: number,
+		primarySpeaker: VoiceSpeaker,
+		source?: VoiceInputSource,
+	): VoiceSegment[] {
+		return local.map<VoiceSegment>((seg, i) => {
+			const isPrimary = seg.localSpeakerId === primaryLocalId;
+			const speaker: VoiceSpeaker = isPrimary
+				? primarySpeaker
+				: {
+						id: `local_${seg.localSpeakerId}`,
+						label: `Speaker ${seg.localSpeakerId}`,
+						source,
+						confidence: seg.confidence,
+						metadata: {
+							attributionOnly: true,
+							evidenceKind: "voice_imprint_attribution",
+							identityAuthority: false,
+							synthesisAuthorization: false,
+							diarizationOnly: true,
+						},
+					};
+			return {
+				id: `seg_${i}`,
+				text: "",
+				startMs: seg.startMs,
+				endMs: seg.endMs,
+				speaker,
+				speakerId: speaker.id,
+				...(source ? { source } : {}),
+				confidence: seg.confidence,
+				metadata: {
+					localSpeakerId: seg.localSpeakerId,
+					primary: isPrimary,
+				},
+			};
+		});
+	}
+
+	private localToUnknownSegments(
+		local: ReadonlyArray<LocalSpeakerSegment>,
+		source?: VoiceInputSource,
+	): VoiceSegment[] {
+		return local.map<VoiceSegment>((seg, i) => ({
+			id: `seg_${i}`,
+			text: "",
+			startMs: seg.startMs,
+			endMs: seg.endMs,
+			...(source ? { source } : {}),
+			confidence: seg.confidence,
+			metadata: { localSpeakerId: seg.localSpeakerId, primary: false },
+		}));
+	}
+}

package/src/services/voice/speaker/diarizer-fused.d.ts

@@ -0,0 +1,59 @@
+/**
+ * pyannote-segmentation-3.0 diarizer — fused `libelizainference` binding
+ * (ABI v6).
+ *
+ * Drives the native pyannote diarizer through the single fused-FFI
+ * `libelizainference` handle (the merged llama.cpp fork — see
+ * `plugins/plugin-local-inference/native/CLAUDE.md` §1) via the
+ * `eliza_inference_diariz_*` ABI. This is the SOLE on-device diarizer runtime —
+ * the same `ffi`/`ctx` pair powers VAD / wake-word / speaker / TTS / ASR.
+ *
+ * The native call returns a per-frame powerset-label sequence (293 int8
+ * labels per 5 s window, each in `[0, 7)`). Agglomerative clustering and the
+ * frame→segment reduction stay JS-side: this class one-hots the labels and
+ * feeds them through the shared pure `classifyFramesToSegments` reducer.
+ *
+ * No silent fallback: when the fused build does not export the diarizer ABI
+ * (`eliza_inference_diariz_supported() == 0`) `load()` throws a structured
+ * `DiarizerUnavailableError` (AGENTS.md §3 — never fabricate a label
+ * sequence, no standalone-lib fallback).
+ */
+import type { ElizaInferenceContextHandle, ElizaInferenceFfi } from "../ffi-bindings";
+import { type Diarizer, type DiarizerOutput, type PyannoteDiarizerModelId } from "./diarizer";
+export interface FusedDiarizerOptions {
+    ffi: ElizaInferenceFfi;
+    ctx: ElizaInferenceContextHandle | (() => ElizaInferenceContextHandle);
+    /**
+     * Optional explicit pyannote GGUF path. `null` lets the native runtime
+     * resolve the bundle's `diariz/` dir (the default).
+     */
+    ggufPath?: string | null;
+    /** Stored model id (purely informational). */
+    modelId?: PyannoteDiarizerModelId;
+}
+/**
+ * Fused-`libelizainference` pyannote-3 diarizer. Owns one
+ * `eliza_inference_diariz_*` session; `diarizeWindow()` runs one forward pass
+ * over a ~5 s window and reduces the powerset labels into speaker segments.
+ */
+export declare class FusedDiarizer implements Diarizer {
+    private readonly ffi;
+    private readonly handle;
+    readonly sampleRate = 16000;
+    readonly modelId: PyannoteDiarizerModelId;
+    private disposed;
+    private constructor();
+    /**
+     * True only when the fused `libelizainference` build exports the diarizer
+     * ABI and advertises support at runtime.
+     */
+    static isSupported(ffi: ElizaInferenceFfi | null | undefined): boolean;
+    /**
+     * Open a native diarizer session. Throws `DiarizerUnavailableError` when
+     * the runtime is not present.
+     */
+    static load(opts: FusedDiarizerOptions): Promise<FusedDiarizer>;
+    diarizeWindow(pcm: Float32Array): Promise<DiarizerOutput>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=diarizer-fused.d.ts.map

package/src/services/voice/speaker/diarizer-fused.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diarizer-fused.d.ts","sourceRoot":"","sources":["diarizer-fused.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACX,2BAA2B,EAC3B,iBAAiB,EAEjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEN,KAAK,QAAQ,EACb,KAAK,cAAc,EAMnB,KAAK,uBAAuB,EAC5B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACpC,GAAG,EAAE,iBAAiB,CAAC;IACvB,GAAG,EAAE,2BAA2B,GAAG,CAAC,MAAM,2BAA2B,CAAC,CAAC;IACvE;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,uBAAuB,CAAC;CAClC;AAED;;;;GAIG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAM5C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IANxB,QAAQ,CAAC,UAAU,SAAwB;IAC3C,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAS;IAEzB,OAAO;IAQP;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;IAKtE;;;OAGG;WACU,IAAI,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IA6B/D,aAAa,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAsCzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK9B"}

package/src/services/voice/speaker/diarizer-fused.real.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Real-FFI tests for `FusedDiarizer`: run against the ACTUAL fused
+ * `libelizainference` — loaded, `create`d, and probed for `diarizSupported()`
+ * — never a stub. The pyannote diarizer is the SOLE on-device diarization
+ * runtime (the `eliza_inference_diariz_*` ABI off the one fused handle), feeding
+ * its per-frame powerset labels through the shared pure `classifyFramesToSegments`
+ * reducer.
+ *
+ * Skipped (not faked) when the fused lib is not resolvable, or when it does not
+ * link the pyannote diarizer graph. To run them, point `ELIZA_INFERENCE_LIBRARY`
+ * (or `ELIZA_INFERENCE_LIB_DIR`) at a built `libelizainference` with the diarizer
+ * ABI, or build one via `packages/app-core/scripts/build-llama-cpp-mtp.mjs`.
+ * Runs in the post-merge `bun test` lane (`*.real.test.ts` is excluded from the
+ * default lane in `vitest.config.ts`).
+ */
+
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+	afterAll,
+	afterEach,
+	beforeAll,
+	beforeEach,
+	describe,
+	expect,
+	it,
+} from "vitest";
+
+import { resolveFusedLibraryPath } from "../../desktop-fused-ffi-backend-runtime";
+import {
+	type ElizaInferenceContextHandle,
+	type ElizaInferenceFfi,
+	loadElizaInferenceFfi,
+} from "../ffi-bindings";
+import { FusedDiarizer } from "./diarizer-fused";
+
+const DIARIZ_WINDOW_SAMPLES = 16_000 * 5; // 5 s @ 16 kHz
+
+const isBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+const LIB_PATH = resolveFusedLibraryPath(null, process.env);
+// The native diariz_open needs a pyannote-segmentation GGUF. Provide one via
+// ELIZA_TEST_DIARIZ_GGUF; the diarize assertion skips honestly when it isn't
+// supplied — it is never faked.
+const DIARIZ_GGUF = process.env.ELIZA_TEST_DIARIZ_GGUF?.trim();
+const HAVE_MODEL = !!DIARIZ_GGUF && existsSync(DIARIZ_GGUF);
+
+describe.skipIf(!isBun || !LIB_PATH)("FusedDiarizer — real FFI", () => {
+	let ffi: ElizaInferenceFfi;
+	let ctx: ElizaInferenceContextHandle;
+	let tmp: string;
+
+	beforeAll(() => {
+		// LIB_PATH is non-null inside the skipIf-guarded block.
+		ffi = loadElizaInferenceFfi(LIB_PATH as string);
+	});
+	afterAll(() => {
+		ffi?.close();
+	});
+	beforeEach(() => {
+		tmp = mkdtempSync(path.join(os.tmpdir(), "diarizer-fused-real-"));
+		ctx = ffi.create(tmp);
+	});
+	afterEach(() => {
+		ffi.destroy(ctx);
+		rmSync(tmp, { recursive: true, force: true });
+	});
+
+	it("isSupported() reflects the loaded build's diarizer ABI", () => {
+		expect(typeof FusedDiarizer.isSupported(ffi)).toBe("boolean");
+	});
+
+	it.skipIf(!HAVE_MODEL)(
+		"diarizeWindow() reduces real native labels into bounded segments",
+		async () => {
+			const dia = await FusedDiarizer.load({ ffi, ctx, ggufPath: DIARIZ_GGUF });
+			expect(dia.sampleRate).toBe(16_000);
+			expect(dia.modelId).toBe("pyannote-segmentation-3.0-int8");
+			// 5 s of a 180 Hz tone — a real, finite window the native graph accepts.
+			const pcm = new Float32Array(DIARIZ_WINDOW_SAMPLES);
+			for (let i = 0; i < pcm.length; i += 1) {
+				pcm[i] = 0.2 * Math.sin((2 * Math.PI * 180 * i) / 16_000);
+			}
+			const out = await dia.diarizeWindow(pcm);
+			// Every reduced segment must be well-formed: start < end, a valid local
+			// speaker id, and a confidence in [0, 1]. The exact speaker count is
+			// content-dependent and not asserted here.
+			expect(out.localSpeakerCount).toBe(
+				new Set(out.segments.map((s) => s.localSpeakerId)).size,
+			);
+			for (const seg of out.segments) {
+				expect(seg.endMs).toBeGreaterThanOrEqual(seg.startMs);
+				expect(seg.localSpeakerId).toBeGreaterThanOrEqual(0);
+				expect(seg.confidence).toBeGreaterThanOrEqual(0);
+				expect(seg.confidence).toBeLessThanOrEqual(1);
+			}
+			await dia.dispose();
+		},
+	);
+});

package/src/services/voice/speaker/diarizer-fused.ts

@@ -0,0 +1,154 @@
+/**
+ * pyannote-segmentation-3.0 diarizer — fused `libelizainference` binding
+ * (ABI v6).
+ *
+ * Drives the native pyannote diarizer through the single fused-FFI
+ * `libelizainference` handle (the merged llama.cpp fork — see
+ * `plugins/plugin-local-inference/native/CLAUDE.md` §1) via the
+ * `eliza_inference_diariz_*` ABI. This is the SOLE on-device diarizer runtime —
+ * the same `ffi`/`ctx` pair powers VAD / wake-word / speaker / TTS / ASR.
+ *
+ * The native call returns a per-frame powerset-label sequence (293 int8
+ * labels per 5 s window, each in `[0, 7)`). Agglomerative clustering and the
+ * frame→segment reduction stay JS-side: this class one-hots the labels and
+ * feeds them through the shared pure `classifyFramesToSegments` reducer.
+ *
+ * No silent fallback: when the fused build does not export the diarizer ABI
+ * (`eliza_inference_diariz_supported() == 0`) `load()` throws a structured
+ * `DiarizerUnavailableError` (AGENTS.md §3 — never fabricate a label
+ * sequence, no standalone-lib fallback).
+ */
+
+import type {
+	ElizaInferenceContextHandle,
+	ElizaInferenceFfi,
+	NativeDiarizHandle,
+} from "../ffi-bindings";
+import {
+	classifyFramesToSegments,
+	type Diarizer,
+	type DiarizerOutput,
+	DiarizerUnavailableError,
+	PYANNOTE_CLASS_COUNT,
+	PYANNOTE_FRAME_STRIDE_MS,
+	PYANNOTE_SAMPLE_RATE,
+	PYANNOTE_SEGMENTATION_3_INT8_MODEL_ID,
+	type PyannoteDiarizerModelId,
+} from "./diarizer";
+
+export interface FusedDiarizerOptions {
+	ffi: ElizaInferenceFfi;
+	ctx: ElizaInferenceContextHandle | (() => ElizaInferenceContextHandle);
+	/**
+	 * Optional explicit pyannote GGUF path. `null` lets the native runtime
+	 * resolve the bundle's `diariz/` dir (the default).
+	 */
+	ggufPath?: string | null;
+	/** Stored model id (purely informational). */
+	modelId?: PyannoteDiarizerModelId;
+}
+
+/**
+ * Fused-`libelizainference` pyannote-3 diarizer. Owns one
+ * `eliza_inference_diariz_*` session; `diarizeWindow()` runs one forward pass
+ * over a ~5 s window and reduces the powerset labels into speaker segments.
+ */
+export class FusedDiarizer implements Diarizer {
+	readonly sampleRate = PYANNOTE_SAMPLE_RATE;
+	readonly modelId: PyannoteDiarizerModelId;
+	private disposed = false;
+
+	private constructor(
+		private readonly ffi: ElizaInferenceFfi,
+		private readonly handle: NativeDiarizHandle,
+		modelId: PyannoteDiarizerModelId,
+	) {
+		this.modelId = modelId;
+	}
+
+	/**
+	 * True only when the fused `libelizainference` build exports the diarizer
+	 * ABI and advertises support at runtime.
+	 */
+	static isSupported(ffi: ElizaInferenceFfi | null | undefined): boolean {
+		if (!ffi || typeof ffi.diarizSupported !== "function") return false;
+		return ffi.diarizSupported();
+	}
+
+	/**
+	 * Open a native diarizer session. Throws `DiarizerUnavailableError` when
+	 * the runtime is not present.
+	 */
+	static async load(opts: FusedDiarizerOptions): Promise<FusedDiarizer> {
+		if (!FusedDiarizer.isSupported(opts.ffi)) {
+			throw new DiarizerUnavailableError(
+				"native-missing",
+				"[diarizer-fused] The native diarizer is not present in this libelizainference build. Rebuild with the pyannote forward graph linked in (eliza_inference_diariz_* symbols).",
+			);
+		}
+		if (
+			!opts.ffi.diarizOpen ||
+			!opts.ffi.diarizSegment ||
+			!opts.ffi.diarizClose
+		) {
+			throw new DiarizerUnavailableError(
+				"model-load-failed",
+				"[diarizer-fused] Diarizer support probe succeeded, but the required FFI methods are missing on the binding.",
+			);
+		}
+		const ctx = typeof opts.ctx === "function" ? opts.ctx() : opts.ctx;
+		const handle = opts.ffi.diarizOpen({
+			ctx,
+			ggufPath: opts.ggufPath ?? null,
+		});
+		return new FusedDiarizer(
+			opts.ffi,
+			handle,
+			opts.modelId ?? PYANNOTE_SEGMENTATION_3_INT8_MODEL_ID,
+		);
+	}
+
+	async diarizeWindow(pcm: Float32Array): Promise<DiarizerOutput> {
+		if (this.disposed) {
+			throw new DiarizerUnavailableError(
+				"model-load-failed",
+				"[diarizer-fused] diarizeWindow called after dispose()",
+			);
+		}
+		const segment = this.ffi.diarizSegment;
+		if (!segment) {
+			throw new DiarizerUnavailableError(
+				"model-load-failed",
+				"[diarizer-fused] diarizeWindow missing FFI method",
+			);
+		}
+		const labels = segment({ diariz: this.handle, pcm });
+		const frames = labels.length;
+		// One-hot the powerset labels into the frame×class tensor the shared
+		// pure reducer expects (it argmaxes back out, so the one-hot is exact).
+		const probs = new Float32Array(frames * PYANNOTE_CLASS_COUNT);
+		for (let frame = 0; frame < frames; frame += 1) {
+			const label = labels[frame] ?? -1;
+			if (label < 0 || label >= PYANNOTE_CLASS_COUNT) {
+				throw new DiarizerUnavailableError(
+					"model-load-failed",
+					`[diarizer-fused] native diarizer emitted invalid class ${label} at frame ${frame}`,
+				);
+			}
+			probs[frame * PYANNOTE_CLASS_COUNT + label] = 1;
+		}
+		return classifyFramesToSegments(
+			probs,
+			frames,
+			PYANNOTE_CLASS_COUNT,
+			0,
+			PYANNOTE_FRAME_STRIDE_MS,
+		);
+	}
+
+	async dispose(): Promise<void> {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.ffi.diarizClose?.(this.handle);
+	}
+}