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

package/src/services/voice/voice-profile-routes.ts

@@ -0,0 +1,425 @@
+/**
+ * Server-side voice-profile management routes.
+ *
+ * Surfaces the available OmniVoice profiles from:
+ *   1. The active Eliza-1 bundle's `cache/voice-preset-*.bin` files.
+ *   2. The `models/voice/profiles/` catalog directory (build-time profiles).
+ *
+ * Routes:
+ *   GET  /v1/voice/profiles           — list available profiles
+ *   POST /v1/voice/profiles/:id/activate  — set the active default profile
+ *   DELETE /v1/voice/profiles/:id     — soft-delete (mark inactive in catalog)
+ *
+ * The active default profile is persisted in the voice profile catalog JSON
+ * (`models/voice/profiles/catalog.json`). On model boot, the engine bridge
+ * reads this to pick which preset to load as the default.
+ *
+ * No runtime recording interface is exposed. Profile creation happens at
+ * build time via `bun run voice:create-profile`.
+ */
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import type http from "node:http";
+import path from "node:path";
+import { resolveStateDir } from "@elizaos/core";
+import {
+	readVoicePresetFile,
+	type VoicePresetFile,
+} from "./voice-preset-format";
+
+/** Catalog JSON schema version. */
+const CATALOG_SCHEMA_VERSION = 1 as const;
+
+/** One entry in `catalog.json`. */
+export interface VoiceProfileCatalogEntry {
+	/** Profile identifier — matches the `voice-preset-<id>.bin` filename suffix. */
+	id: string;
+	/** Human-readable display name. */
+	displayName: string;
+	/** Build-time instruct string (VoiceDesign vocabulary). */
+	instruct: string;
+	/** Whether this profile is currently active (visible + usable). */
+	active: boolean;
+	/** ISO timestamp when this entry was created. */
+	createdAt: string;
+	/** Optional source bundle. */
+	sourceBundleId?: string;
+	/** Optional sha256 of the source corpus. */
+	corpusSha256?: string;
+}
+
+export interface VoiceProfileCatalog {
+	version: typeof CATALOG_SCHEMA_VERSION;
+	/** ID of the profile to load as the default on model boot. */
+	defaultProfileId: string;
+	profiles: VoiceProfileCatalogEntry[];
+}
+
+export interface VoiceProfileRouteOptions {
+	/**
+	 * Directory that holds `profiles/catalog.json` and the built-in
+	 * `manifest.json`. Defaults to `<repo>/models/voice/`.
+	 */
+	voiceModelsDir?: string;
+	/**
+	 * Root of the active Eliza-1 bundle. When set, the routes also scan
+	 * `<bundleRoot>/cache/voice-preset-*.bin` for bundle-shipped profiles.
+	 */
+	bundleRoot?: string;
+}
+
+const DEFAULT_PROFILE_ID = "same";
+
+// ---------------------------------------------------------------------------
+// Catalog helpers
+// ---------------------------------------------------------------------------
+
+function resolveCatalogPath(voiceModelsDir: string): string {
+	return path.join(voiceModelsDir, "profiles", "catalog.json");
+}
+
+async function readCatalog(
+	voiceModelsDir: string,
+): Promise<VoiceProfileCatalog> {
+	const catalogPath = resolveCatalogPath(voiceModelsDir);
+	if (!fs.existsSync(catalogPath)) {
+		return {
+			version: CATALOG_SCHEMA_VERSION,
+			defaultProfileId: DEFAULT_PROFILE_ID,
+			profiles: [],
+		};
+	}
+	try {
+		const raw = await fsp.readFile(catalogPath, "utf8");
+		const parsed = JSON.parse(raw) as VoiceProfileCatalog;
+		if (!parsed.profiles) parsed.profiles = [];
+		if (!parsed.defaultProfileId) parsed.defaultProfileId = DEFAULT_PROFILE_ID;
+		parsed.version = CATALOG_SCHEMA_VERSION;
+		return parsed;
+	} catch {
+		return {
+			version: CATALOG_SCHEMA_VERSION,
+			defaultProfileId: DEFAULT_PROFILE_ID,
+			profiles: [],
+		};
+	}
+}
+
+async function writeCatalog(
+	voiceModelsDir: string,
+	catalog: VoiceProfileCatalog,
+): Promise<void> {
+	const catalogPath = resolveCatalogPath(voiceModelsDir);
+	await fsp.mkdir(path.dirname(catalogPath), { recursive: true });
+	const tmp = `${catalogPath}.tmp`;
+	await fsp.writeFile(tmp, JSON.stringify(catalog, null, 2), "utf8");
+	await fsp.rename(tmp, catalogPath);
+}
+
+// ---------------------------------------------------------------------------
+// Profile discovery
+// ---------------------------------------------------------------------------
+
+/** Parse a preset bin and extract the profile metadata we care about. */
+function parsePresetMeta(
+	presetPath: string,
+): Pick<VoicePresetFile, "instruct" | "refText" | "metadata"> | null {
+	if (!fs.existsSync(presetPath)) return null;
+	try {
+		const bytes = fs.readFileSync(presetPath);
+		const preset = readVoicePresetFile(new Uint8Array(bytes));
+		return {
+			instruct: preset.instruct,
+			refText: preset.refText,
+			metadata: preset.metadata,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/** Scan `<bundleRoot>/cache/` for `voice-preset-*.bin` files. */
+function scanBundleProfiles(
+	bundleRoot: string,
+): Array<{ id: string; presetPath: string }> {
+	const cacheDir = path.join(bundleRoot, "cache");
+	if (!fs.existsSync(cacheDir)) return [];
+	const PREFIX = "voice-preset-";
+	const SUFFIX = ".bin";
+	return fs
+		.readdirSync(cacheDir)
+		.filter((f) => f.startsWith(PREFIX) && f.endsWith(SUFFIX))
+		.map((f) => {
+			const id = f.slice(PREFIX.length, f.length - SUFFIX.length);
+			return { id, presetPath: path.join(cacheDir, f) };
+		});
+}
+
+/** Merge bundle-scanned profiles with catalog entries. */
+async function listProfiles(
+	_voiceModelsDir: string,
+	bundleRoot: string | undefined,
+	catalog: VoiceProfileCatalog,
+): Promise<
+	Array<{
+		id: string;
+		displayName: string;
+		instruct: string;
+		active: boolean;
+		isDefault: boolean;
+		source: "bundle" | "catalog";
+		createdAt: string;
+	}>
+> {
+	const seenIds = new Set<string>();
+	const out: Array<{
+		id: string;
+		displayName: string;
+		instruct: string;
+		active: boolean;
+		isDefault: boolean;
+		source: "bundle" | "catalog";
+		createdAt: string;
+	}> = [];
+
+	// Bundle-shipped presets take priority.
+	if (bundleRoot) {
+		for (const { id, presetPath } of scanBundleProfiles(bundleRoot)) {
+			seenIds.add(id);
+			const meta = parsePresetMeta(presetPath);
+			const catalogEntry = catalog.profiles.find((e) => e.id === id);
+			const active = catalogEntry ? catalogEntry.active : true;
+			out.push({
+				id,
+				displayName: catalogEntry?.displayName ?? id,
+				instruct: catalogEntry?.instruct ?? meta?.instruct ?? "",
+				active,
+				isDefault: catalog.defaultProfileId === id,
+				source: "bundle",
+				createdAt: catalogEntry?.createdAt ?? new Date().toISOString(),
+			});
+		}
+	}
+
+	// Catalog-only profiles (not in bundle).
+	for (const entry of catalog.profiles) {
+		if (seenIds.has(entry.id)) continue;
+		out.push({
+			id: entry.id,
+			displayName: entry.displayName,
+			instruct: entry.instruct,
+			active: entry.active,
+			isDefault: catalog.defaultProfileId === entry.id,
+			source: "catalog",
+			createdAt: entry.createdAt,
+		});
+	}
+
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Route handler
+// ---------------------------------------------------------------------------
+
+function sendJson(
+	res: http.ServerResponse,
+	status: number,
+	body: unknown,
+): void {
+	if (res.headersSent) return;
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	res.end(JSON.stringify(body));
+}
+
+function sendError(
+	res: http.ServerResponse,
+	status: number,
+	message: string,
+): void {
+	sendJson(res, status, { error: message });
+}
+
+/**
+ * Route handler for all `/v1/voice/profiles*` endpoints.
+ *
+ * Returns `true` if the request was handled, `false` to pass through.
+ */
+export async function handleVoiceProfileRoutes(
+	req: http.IncomingMessage,
+	res: http.ServerResponse,
+	opts: VoiceProfileRouteOptions,
+): Promise<boolean> {
+	const method = req.method?.toUpperCase() ?? "GET";
+	const rawUrl = req.url ?? "/";
+	// Strip query string for routing.
+	const pathname = rawUrl.split("?")[0] ?? rawUrl;
+
+	if (!pathname.startsWith("/v1/voice/profiles")) {
+		return false;
+	}
+
+	const voiceModelsDir =
+		opts.voiceModelsDir ??
+		path.join(resolveStateDir(process.env), "models", "voice");
+	const bundleRoot = opts.bundleRoot;
+
+	// -------------------------------------------------------------------
+	// GET /v1/voice/profiles
+	// -------------------------------------------------------------------
+	if (method === "GET" && pathname === "/v1/voice/profiles") {
+		const catalog = await readCatalog(voiceModelsDir);
+		const profiles = await listProfiles(voiceModelsDir, bundleRoot, catalog);
+		sendJson(res, 200, {
+			defaultProfileId: catalog.defaultProfileId,
+			profiles,
+		});
+		return true;
+	}
+
+	// -------------------------------------------------------------------
+	// POST /v1/voice/profiles/:id/activate
+	// -------------------------------------------------------------------
+	const activateMatch = /^\/v1\/voice\/profiles\/([^/]+)\/activate$/.exec(
+		pathname,
+	);
+	if (method === "POST" && activateMatch) {
+		const profileId = decodeURIComponent(activateMatch[1] ?? "");
+		if (!profileId || !/^[A-Za-z0-9._-]+$/.test(profileId)) {
+			sendError(res, 400, `Invalid profile id: ${profileId}`);
+			return true;
+		}
+
+		const catalog = await readCatalog(voiceModelsDir);
+
+		// Accept any profile that exists in the bundle or catalog.
+		const profiles = await listProfiles(voiceModelsDir, bundleRoot, catalog);
+		const target = profiles.find((p) => p.id === profileId);
+		if (!target) {
+			sendError(res, 404, `Profile '${profileId}' not found`);
+			return true;
+		}
+		if (!target.active) {
+			sendError(res, 409, `Profile '${profileId}' is inactive (soft-deleted)`);
+			return true;
+		}
+
+		// Update the catalog default.
+		const prevDefault = catalog.defaultProfileId;
+		catalog.defaultProfileId = profileId;
+
+		// Ensure the profile has a catalog entry (for bundle-only profiles, create one).
+		const existingEntry = catalog.profiles.find((e) => e.id === profileId);
+		if (!existingEntry) {
+			catalog.profiles.push({
+				id: profileId,
+				displayName: target.displayName,
+				instruct: target.instruct,
+				active: true,
+				createdAt: new Date().toISOString(),
+			});
+		}
+
+		await writeCatalog(voiceModelsDir, catalog);
+
+		sendJson(res, 200, {
+			defaultProfileId: profileId,
+			previousDefaultProfileId: prevDefault,
+		});
+		return true;
+	}
+
+	// -------------------------------------------------------------------
+	// DELETE /v1/voice/profiles/:id
+	// -------------------------------------------------------------------
+	const deleteMatch = /^\/v1\/voice\/profiles\/([^/]+)$/.exec(pathname);
+	if (method === "DELETE" && deleteMatch) {
+		const profileId = decodeURIComponent(deleteMatch[1] ?? "");
+		if (!profileId || !/^[A-Za-z0-9._-]+$/.test(profileId)) {
+			sendError(res, 400, `Invalid profile id: ${profileId}`);
+			return true;
+		}
+
+		const catalog = await readCatalog(voiceModelsDir);
+
+		if (catalog.defaultProfileId === profileId) {
+			sendError(
+				res,
+				409,
+				`Cannot delete the active default profile '${profileId}'. Activate a different profile first.`,
+			);
+			return true;
+		}
+
+		// Soft-delete: mark inactive in catalog. Never unlinks shipped bundle files.
+		const existingEntry = catalog.profiles.find((e) => e.id === profileId);
+		if (existingEntry) {
+			existingEntry.active = false;
+		} else {
+			// Profile exists in bundle but is absent from catalog — add as inactive.
+			const profiles = await listProfiles(voiceModelsDir, bundleRoot, catalog);
+			const target = profiles.find((p) => p.id === profileId);
+			if (!target) {
+				sendError(res, 404, `Profile '${profileId}' not found`);
+				return true;
+			}
+			catalog.profiles.push({
+				id: profileId,
+				displayName: target.displayName,
+				instruct: target.instruct,
+				active: false,
+				createdAt: new Date().toISOString(),
+			});
+		}
+
+		await writeCatalog(voiceModelsDir, catalog);
+		sendJson(res, 200, { deleted: profileId, active: false });
+		return true;
+	}
+
+	return false;
+}
+
+// ---------------------------------------------------------------------------
+// Server-side default profile loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active default profile id from the voice catalog.
+ *
+ * Called at model boot (before `EngineVoiceBridge.start()`) to determine
+ * which `voice-preset-<id>.bin` to load as the default voice. Returns
+ * `"default"` when the catalog has no explicit default set.
+ */
+export async function resolveDefaultProfileId(
+	voiceModelsDir: string,
+): Promise<string> {
+	const catalog = await readCatalog(voiceModelsDir);
+	return catalog.defaultProfileId || DEFAULT_PROFILE_ID;
+}
+
+/**
+ * Persist a newly created profile into the voice catalog.
+ *
+ * Called by `bun run voice:create-profile` after the freeze pipeline
+ * writes the preset binary. Appends an entry to `catalog.json` if the
+ * profile id is not already there; updates instruct + displayName if it is.
+ */
+export async function registerProfileInCatalog(
+	voiceModelsDir: string,
+	entry: Omit<VoiceProfileCatalogEntry, "active"> & { active?: boolean },
+): Promise<void> {
+	const catalog = await readCatalog(voiceModelsDir);
+	const existing = catalog.profiles.findIndex((e) => e.id === entry.id);
+	const full: VoiceProfileCatalogEntry = {
+		...entry,
+		active: entry.active ?? true,
+	};
+	if (existing >= 0) {
+		catalog.profiles[existing] = full;
+	} else {
+		catalog.profiles.push(full);
+	}
+	await writeCatalog(voiceModelsDir, catalog);
+}

package/src/services/voice/voice-scenario.test.ts

@@ -0,0 +1,159 @@
+// Coverage for the pure VoiceScenario validator + turn helpers (#9147). The
+// validator gates every test-matrix scenario before the corpus build, so its
+// id/participant/turn/agent/environment checks are worth pinning directly.
+
+import { describe, expect, it } from "vitest";
+import {
+	resolveTurnEnvironment,
+	turnReferenceTranscript,
+	turnSpeakerLabel,
+	type VoiceEnvironment,
+	type VoiceScenario,
+	validateVoiceScenario,
+} from "./voice-scenario";
+
+function validScenario(): VoiceScenario {
+	return {
+		id: "s1",
+		classes: ["diarization"],
+		participants: [{ label: "alice" }, { label: "bob" }],
+		turns: [
+			{ speaker: "alice", text: "hello", expectRespond: true },
+			{ speaker: "bob", text: "hi there", expectRespond: false },
+		],
+	};
+}
+
+describe("validateVoiceScenario", () => {
+	it("accepts a well-formed scenario", () => {
+		expect(validateVoiceScenario(validScenario())).toEqual({
+			valid: true,
+			errors: [],
+		});
+	});
+
+	it("requires id, a non-empty classes array, participants, and turns", () => {
+		const r = validateVoiceScenario({
+			id: "  ",
+			classes: [],
+			participants: [],
+			turns: [],
+		});
+		expect(r.valid).toBe(false);
+		expect(r.errors).toContain("scenario.id is required");
+		expect(r.errors).toContain("scenario.classes must be a non-empty array");
+		expect(r.errors).toContain("scenario.participants must be non-empty");
+		expect(r.errors).toContain("scenario.turns must be a non-empty array");
+	});
+
+	it("flags duplicate participant labels", () => {
+		const s = validScenario();
+		s.participants = [{ label: "alice" }, { label: "alice" }];
+		expect(validateVoiceScenario(s).errors).toContain(
+			"duplicate participant label: alice",
+		);
+	});
+
+	it("flags a turn whose speaker is not a participant", () => {
+		const s = validScenario();
+		s.turns = [{ speaker: "carol", text: "hi", expectRespond: true }];
+		expect(validateVoiceScenario(s).errors).toContain(
+			'turn[0].speaker "carol" is not a participant',
+		);
+	});
+
+	it("requires each turn to carry text or audioRef and a boolean expectRespond", () => {
+		const s = validScenario();
+		// @ts-expect-error — exercising the runtime guard for a missing expectRespond
+		s.turns = [{ speaker: "alice" }];
+		const errors = validateVoiceScenario(s).errors;
+		expect(errors).toContain("turn[0] must have either text or audioRef");
+		expect(errors).toContain("turn[0].expectRespond must be a boolean");
+	});
+
+	it("flags an agent label that is not a participant", () => {
+		const s = validScenario();
+		s.agents = ["ghost"];
+		expect(validateVoiceScenario(s).errors).toContain(
+			'agent "ghost" is not a participant',
+		);
+	});
+
+	it("validates acoustic environment ranges (reverb in [0,1], far-field >= 0)", () => {
+		const s = validScenario();
+		s.environment = { reverb: 2, farFieldDb: -3 } as VoiceEnvironment;
+		const errors = validateVoiceScenario(s).errors;
+		expect(errors).toContain("scenario.environment.reverb must be in [0, 1]");
+		expect(errors).toContain(
+			"scenario.environment.farFieldDb must be a non-negative dB attenuation",
+		);
+	});
+
+	it("collects every error at once instead of throwing on the first", () => {
+		const r = validateVoiceScenario({
+			id: "",
+			classes: [],
+			participants: [{ label: "alice" }],
+			turns: [{ speaker: "nope", text: "x", expectRespond: true }],
+		});
+		expect(r.valid).toBe(false);
+		expect(r.errors.length).toBeGreaterThanOrEqual(3);
+	});
+});
+
+describe("turn helpers", () => {
+	it("resolveTurnEnvironment merges turn over scenario (turn wins)", () => {
+		const s = validScenario();
+		s.environment = { reverb: 0.2, noiseSnrDb: 10 } as VoiceEnvironment;
+		const turn = {
+			speaker: "alice",
+			text: "hi",
+			expectRespond: true,
+			environment: { reverb: 0.8 } as VoiceEnvironment,
+		};
+		expect(resolveTurnEnvironment(s, turn)).toEqual({
+			reverb: 0.8,
+			noiseSnrDb: 10,
+		});
+		// Both absent → undefined.
+		expect(
+			resolveTurnEnvironment(validScenario(), {
+				speaker: "alice",
+				text: "hi",
+				expectRespond: true,
+			}),
+		).toBeUndefined();
+	});
+
+	it("turnReferenceTranscript prefers the explicit override, else the text", () => {
+		expect(
+			turnReferenceTranscript({
+				speaker: "a",
+				text: "spoken",
+				expectedTranscript: "  override  ",
+				expectRespond: true,
+			}),
+		).toBe("override");
+		expect(
+			turnReferenceTranscript({
+				speaker: "a",
+				text: "  just text  ",
+				expectRespond: true,
+			}),
+		).toBe("just text");
+	});
+
+	it("turnSpeakerLabel prefers the explicit diarization label, else the speaker", () => {
+		expect(
+			turnSpeakerLabel({
+				speaker: "alice",
+				text: "x",
+				expectedSpeakerLabel: "SPEAKER_01",
+				expectRespond: true,
+			}),
+		).toBe("SPEAKER_01");
+		expect(
+			turnSpeakerLabel({ speaker: "alice", text: "x", expectRespond: true }),
+		).toBe("alice");
+	});
+});