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

package/src/services/voice/kokoro/__tests__/kokoro-engine-bridge.real.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Real-FFI tests for `EngineVoiceBridge.startKokoroOnly`: construct the
+ * Kokoro-backed bridge against the ACTUAL fused `libelizainference` — loaded,
+ * `create`d, and probed for `kokoroSupported()` — never a stub.
+ *
+ * Skipped (not faked) when the fused lib is not resolvable. To run them, point
+ * `ELIZA_INFERENCE_LIBRARY` (or `ELIZA_INFERENCE_LIB_DIR`) at a built
+ * `libelizainference` or build one via
+ * `packages/app-core/scripts/build-llama-cpp-mtp.mjs`.
+ */
+
+import { 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 { EngineVoiceBridge } from "../../engine-bridge";
+import {
+	type ElizaInferenceFfi,
+	loadElizaInferenceFfi,
+} from "../../ffi-bindings";
+import type { VoiceLifecycleLoaders } from "../../lifecycle";
+import type {
+	MmapRegionHandle,
+	RefCountedResource,
+} from "../../shared-resources";
+import type { KokoroTtsBackend } from "../kokoro-backend";
+import type { KokoroEngineDiscoveryResult } from "../kokoro-engine-discovery";
+
+const isBun = typeof (globalThis as { Bun?: unknown }).Bun !== "undefined";
+const LIB_PATH = resolveFusedLibraryPath(null, process.env);
+
+// The real fused `create()` validates that the anchor dir exists, so the
+// layout root points at a live temp dir (`tmp`, per-test) rather than a
+// never-created path.
+function makeKokoroConfig(root: string): KokoroEngineDiscoveryResult {
+	return {
+		layout: {
+			root,
+			modelFile: "kokoro-82m-v1_0-Q4_K_M.gguf",
+			voicesDir: path.join(root, "voices"),
+			sampleRate: 24_000,
+		},
+		defaultVoiceId: "af_bella",
+	};
+}
+
+function lifecycleLoadersOk(): VoiceLifecycleLoaders {
+	const region: MmapRegionHandle = {
+		id: "test-region",
+		path: "/tmp/test",
+		sizeBytes: 0,
+		async evictPages() {},
+		async release() {},
+	};
+	const refc: RefCountedResource = { id: "refc", async release() {} };
+	return {
+		loadTtsRegion: async () => region,
+		loadAsrRegion: async () => region,
+		loadVoiceCaches: async () => refc,
+		loadVoiceSchedulerNodes: async () => refc,
+	};
+}
+
+describe.skipIf(!isBun || !LIB_PATH)(
+	"EngineVoiceBridge — kokoroOnly real FFI construction",
+	() => {
+		let ffi: ElizaInferenceFfi;
+		let tmp: string;
+
+		beforeAll(() => {
+			// LIB_PATH is non-null inside the skipIf-guarded block.
+			ffi = loadElizaInferenceFfi(LIB_PATH as string);
+			if (typeof ffi.kokoroSupported !== "function" || !ffi.kokoroSupported()) {
+				throw new Error(
+					`[test] the fused lib at ${LIB_PATH} (ABI v${ffi.libraryAbiVersion}) does not link the in-process Kokoro engine — rebuild with the Kokoro engine enabled.`,
+				);
+			}
+		});
+		afterAll(() => {
+			(ffi as unknown as { close?: () => void }).close?.();
+		});
+		beforeEach(() => {
+			tmp = mkdtempSync(path.join(os.tmpdir(), "kokoro-bridge-real-"));
+		});
+		afterEach(() => {
+			rmSync(tmp, { recursive: true, force: true });
+		});
+
+		it("constructs a KokoroTtsBackend against the real fused lib", () => {
+			const bridge = EngineVoiceBridge.start({
+				bundleRoot: "", // kokoroOnly skips the existsSync check
+				useFfiBackend: false,
+				kokoroOnly: makeKokoroConfig(tmp),
+				kokoroFfi: ffi,
+				lifecycleLoaders: lifecycleLoadersOk(),
+			});
+			expect(bridge.backend?.id).toBe("kokoro");
+			expect(bridge.asrAvailable).toBe(false); // ASR is not served from this path
+			expect(bridge.ffi).toBeNull();
+			bridge.dispose();
+		});
+
+		it("uses the provided bundleRoot as working dir when it exists", () => {
+			const bridge = EngineVoiceBridge.start({
+				bundleRoot: tmp,
+				useFfiBackend: false,
+				kokoroOnly: makeKokoroConfig(tmp),
+				kokoroFfi: ffi,
+				lifecycleLoaders: lifecycleLoadersOk(),
+			});
+			expect(bridge.backend?.id).toBe("kokoro");
+			bridge.dispose();
+		});
+
+		it("arms with no-op lifecycle loaders by default (no real mmap regions)", async () => {
+			const bridge = EngineVoiceBridge.start({
+				bundleRoot: "",
+				useFfiBackend: false,
+				kokoroOnly: makeKokoroConfig(tmp),
+				kokoroFfi: ffi,
+			});
+			await expect(bridge.arm()).resolves.toBeUndefined();
+			bridge.dispose();
+		});
+
+		it("preserves the requested sample rate from the kokoroOnly layout", () => {
+			const bridge = EngineVoiceBridge.start({
+				bundleRoot: "",
+				useFfiBackend: false,
+				kokoroOnly: {
+					...makeKokoroConfig(tmp),
+					layout: { ...makeKokoroConfig(tmp).layout, sampleRate: 16_000 },
+				},
+				kokoroFfi: ffi,
+				lifecycleLoaders: lifecycleLoadersOk(),
+			});
+			expect((bridge.backend as KokoroTtsBackend).sampleRate).toBe(16_000);
+			bridge.dispose();
+		});
+	},
+);

package/src/services/voice/kokoro/__tests__/kokoro-engine-bridge.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for `EngineVoiceBridge.startKokoroOnly` option validation — the
+ * mutually-exclusive backend-path checks that throw before any FFI work, so
+ * they need no library.
+ *
+ * Real FFI construction (loading `libelizainference` + `create` + Kokoro
+ * support) is exercised against the ACTUAL library — never a stub — in
+ * `kokoro-engine-bridge.real.test.ts`, gated on the fused lib being built.
+ */
+
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { EngineVoiceBridge, VoiceStartupError } from "../../engine-bridge";
+import type { KokoroEngineDiscoveryResult } from "../kokoro-engine-discovery";
+
+function makeKokoroConfig(): KokoroEngineDiscoveryResult {
+	return {
+		layout: {
+			root: "/tmp/fake-kokoro",
+			modelFile: "kokoro-82m-v1_0-Q4_K_M.gguf",
+			voicesDir: path.join("/tmp/fake-kokoro", "voices"),
+			sampleRate: 24_000,
+		},
+		defaultVoiceId: "af_bella",
+	};
+}
+
+describe("EngineVoiceBridge — kokoroOnly option validation", () => {
+	it("throws when kokoroOnly is combined with useFfiBackend:true", () => {
+		expect(() =>
+			EngineVoiceBridge.start({
+				bundleRoot: "",
+				useFfiBackend: true,
+				kokoroOnly: makeKokoroConfig(),
+			}),
+		).toThrow(VoiceStartupError);
+	});
+
+	it("throws when kokoroOnly is combined with backendOverride", () => {
+		expect(() =>
+			EngineVoiceBridge.start({
+				bundleRoot: "",
+				useFfiBackend: false,
+				kokoroOnly: makeKokoroConfig(),
+				backendOverride: {
+					async synthesize() {
+						return {
+							phraseId: 0,
+							fromIndex: 0,
+							toIndex: 0,
+							pcm: new Float32Array(0),
+							sampleRate: 24000,
+						};
+					},
+				} as never,
+			}),
+		).toThrow(VoiceStartupError);
+	});
+});

package/src/services/voice/kokoro/__tests__/kokoro-engine-discovery.test.ts

@@ -0,0 +1,277 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { resolveStateDir } from "@elizaos/core";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import {
+	isKokoroGgufFile,
+	kokoroEngineModelDir,
+	resolveKokoroEngineConfig,
+} from "../kokoro-engine-discovery";
+import {
+	KOKORO_DEFAULT_VOICE_ID,
+	KOKORO_FALLBACK_VOICE_ID,
+} from "../voice-presets";
+
+function makeStaged(opts: { modelFile?: string; voices?: string[] }): {
+	root: string;
+	cleanup: () => void;
+} {
+	const root = mkdtempSync(path.join(os.tmpdir(), "kokoro-engine-test-"));
+	if (opts.modelFile) {
+		writeFileSync(path.join(root, opts.modelFile), Buffer.alloc(4));
+	}
+	if (opts.voices && opts.voices.length > 0) {
+		mkdirSync(path.join(root, "voices"), { recursive: true });
+		for (const v of opts.voices) {
+			writeFileSync(path.join(root, "voices", v), Buffer.alloc(1024));
+		}
+	}
+	return {
+		root,
+		cleanup: () => rmSync(root, { recursive: true, force: true }),
+	};
+}
+
+describe("resolveKokoroEngineConfig", () => {
+	let cleanups: Array<() => void>;
+	let origEnv: Record<string, string | undefined>;
+	beforeEach(() => {
+		cleanups = [];
+		origEnv = {
+			ELIZA_KOKORO_MODEL_DIR: process.env.ELIZA_KOKORO_MODEL_DIR,
+			ELIZA_KOKORO_MODEL_FILE: process.env.ELIZA_KOKORO_MODEL_FILE,
+			ELIZA_KOKORO_DEFAULT_VOICE_ID: process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID,
+		};
+		delete process.env.ELIZA_KOKORO_MODEL_DIR;
+		delete process.env.ELIZA_KOKORO_MODEL_FILE;
+		delete process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID;
+	});
+	afterEach(() => {
+		for (const c of cleanups) c();
+		for (const [k, v] of Object.entries(origEnv)) {
+			if (v === undefined) delete process.env[k];
+			else process.env[k] = v;
+		}
+	});
+
+	it("returns null when the model dir does not exist", () => {
+		process.env.ELIZA_KOKORO_MODEL_DIR = path.join(
+			os.tmpdir(),
+			`definitely-not-here-${Date.now()}`,
+		);
+		expect(resolveKokoroEngineConfig()).toBeNull();
+	});
+
+	it("returns null when the model dir exists but no GGUF is staged", () => {
+		const fx = makeStaged({ voices: ["af_bella.bin"] });
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		expect(resolveKokoroEngineConfig()).toBeNull();
+	});
+
+	it("returns null when no voice .bin is staged", () => {
+		const fx = makeStaged({ modelFile: "kokoro-82m-v1_0.gguf" });
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		expect(resolveKokoroEngineConfig()).toBeNull();
+	});
+
+	it("returns the canonical Samantha default when staged", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_same.bin", "af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.defaultVoiceId).toBe(KOKORO_DEFAULT_VOICE_ID);
+		expect(cfg?.layout.modelFile).toBe("kokoro-82m-v1_0.gguf");
+		expect(cfg?.layout.sampleRate).toBe(24_000);
+		expect(cfg?.layout.root).toBe(fx.root);
+		expect(cfg?.layout.voicesDir).toBe(path.join(fx.root, "voices"));
+	});
+
+	it("falls back to af_bella with a console warning when Samantha preset is missing", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_bella.bin"], // Samantha (af_same) absent
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+
+		const warnings: string[] = [];
+		const origWarn = console.warn;
+		console.warn = (msg: unknown) => {
+			warnings.push(String(msg));
+		};
+		try {
+			const cfg = resolveKokoroEngineConfig();
+			expect(cfg).not.toBeNull();
+			expect(cfg?.defaultVoiceId).toBe(KOKORO_FALLBACK_VOICE_ID);
+			expect(warnings).toHaveLength(1);
+			expect(warnings[0]).toContain(
+				`default voice ${KOKORO_DEFAULT_VOICE_ID} preset not staged`,
+			);
+			expect(warnings[0]).toContain(
+				`falling back to ${KOKORO_FALLBACK_VOICE_ID}`,
+			);
+		} finally {
+			console.warn = origWarn;
+		}
+	});
+
+	it("can probe an explicit bundle-local Kokoro root before the global install root", () => {
+		const bundleFx = makeStaged({
+			modelFile: "kokoro-82m-v1_0-Q4_K_M.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(bundleFx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = path.join(
+			os.tmpdir(),
+			`not-used-${Date.now()}`,
+		);
+
+		const cfg = resolveKokoroEngineConfig(bundleFx.root);
+		expect(cfg).not.toBeNull();
+		expect(cfg?.layout.root).toBe(bundleFx.root);
+		expect(cfg?.layout.modelFile).toBe("kokoro-82m-v1_0-Q4_K_M.gguf");
+		expect(cfg?.defaultVoiceId).toBe("af_bella");
+		expect(kokoroEngineModelDir(bundleFx.root)).toBe(bundleFx.root);
+	});
+
+	it("picks any staged voice when the catalog default is missing", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_sarah.bin"], // not the default `af_bella`
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.defaultVoiceId).toBe("af_sarah");
+	});
+
+	it("honours ELIZA_KOKORO_DEFAULT_VOICE_ID when set + staged", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_bella.bin", "af_nicole.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID = "af_nicole";
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.defaultVoiceId).toBe("af_nicole");
+	});
+
+	it("returns null when ELIZA_KOKORO_DEFAULT_VOICE_ID is set but the .bin is missing", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID = "af_nicole";
+		expect(resolveKokoroEngineConfig()).toBeNull();
+	});
+
+	it("honours ELIZA_KOKORO_MODEL_FILE override when present", () => {
+		const fx = makeStaged({
+			modelFile: "custom-export.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		process.env.ELIZA_KOKORO_MODEL_FILE = "custom-export.gguf";
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.layout.modelFile).toBe("custom-export.gguf");
+	});
+
+	it("reports runtimeKind=gguf for GGUF model files", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.runtimeKind).toBe("gguf");
+	});
+
+	it("reports runtimeKind=gguf for Q4_K_M GGUF model files", () => {
+		const fx = makeStaged({
+			modelFile: "kokoro-82m-v1_0-Q4_K_M.gguf",
+			voices: ["af_bella.bin"],
+		});
+		cleanups.push(fx.cleanup);
+		process.env.ELIZA_KOKORO_MODEL_DIR = fx.root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.runtimeKind).toBe("gguf");
+		expect(cfg?.layout.modelFile).toBe("kokoro-82m-v1_0-Q4_K_M.gguf");
+	});
+
+	it("prefers the Q4_K_M GGUF over the unquantized GGUF when both are staged", () => {
+		const root = mkdtempSync(path.join(os.tmpdir(), "kokoro-engine-test-"));
+		writeFileSync(path.join(root, "kokoro-82m-v1_0.gguf"), Buffer.alloc(4));
+		writeFileSync(
+			path.join(root, "kokoro-82m-v1_0-Q4_K_M.gguf"),
+			Buffer.alloc(4),
+		);
+		mkdirSync(path.join(root, "voices"), { recursive: true });
+		writeFileSync(
+			path.join(root, "voices", "af_bella.bin"),
+			Buffer.alloc(1024),
+		);
+		cleanups.push(() => rmSync(root, { recursive: true, force: true }));
+
+		process.env.ELIZA_KOKORO_MODEL_DIR = root;
+		const cfg = resolveKokoroEngineConfig();
+		expect(cfg).not.toBeNull();
+		expect(cfg?.runtimeKind).toBe("gguf");
+		expect(cfg?.layout.modelFile).toBe("kokoro-82m-v1_0-Q4_K_M.gguf");
+	});
+});
+
+describe("isKokoroGgufFile", () => {
+	it("identifies GGUF model files by extension", () => {
+		expect(isKokoroGgufFile("kokoro-82m-v1_0.gguf")).toBe(true);
+		expect(isKokoroGgufFile("kokoro-82m-v1_0-Q4_K_M.gguf")).toBe(true);
+		expect(isKokoroGgufFile("KOKORO.GGUF")).toBe(true);
+	});
+
+	it("identifies non-GGUF model files as not GGUF", () => {
+		expect(isKokoroGgufFile("kokoro-v1.0.pt")).toBe(false);
+		expect(isKokoroGgufFile("model.bin")).toBe(false);
+		expect(isKokoroGgufFile("model.safetensors")).toBe(false);
+		expect(isKokoroGgufFile("model.pth")).toBe(false);
+	});
+});
+
+describe("kokoroEngineModelDir", () => {
+	let origDir: string | undefined;
+	beforeEach(() => {
+		origDir = process.env.ELIZA_KOKORO_MODEL_DIR;
+	});
+	afterEach(() => {
+		if (origDir === undefined) delete process.env.ELIZA_KOKORO_MODEL_DIR;
+		else process.env.ELIZA_KOKORO_MODEL_DIR = origDir;
+	});
+
+	it("returns the env override when set", () => {
+		process.env.ELIZA_KOKORO_MODEL_DIR = "/tmp/custom-kokoro";
+		expect(kokoroEngineModelDir()).toBe("/tmp/custom-kokoro");
+	});
+
+	it("returns the canonical home path when env is unset", () => {
+		delete process.env.ELIZA_KOKORO_MODEL_DIR;
+		expect(kokoroEngineModelDir()).toBe(
+			path.join(resolveStateDir(), "local-inference", "models", "kokoro"),
+		);
+	});
+});