@elizaos/shared 2.0.0-alpha.538 → 2.0.11-beta.7

package/local-inference/verify.js

@@ -0,0 +1,105 @@
+/**
+ * Model-file integrity verification.
+ *
+ * GGUF files are large (0.8 – 20 GB). Corrupted files surface as cryptic
+ * llama.cpp errors much later, so we verify at install time and expose a
+ * manual verify button for users who want to re-check after a system
+ * event (crash, disk fill, external tool edited the file, etc).
+ *
+ * We don't require SHA256 from HuggingFace — HF doesn't publish per-file
+ * hashes in the standard API, and hand-curating them in the catalog would
+ * drift. Instead, after a successful download we compute the SHA256
+ * ourselves and stash it on the InstalledModel. Re-verify compares the
+ * file's current hash against the stashed one. A mismatch means the file
+ * changed on disk since we installed it — user can redownload.
+ *
+ * For GGUF specifically we also do a cheap structural header check
+ * (the file starts with the magic bytes "GGUF") so obvious truncations
+ * flag instantly without having to hash a 10GB file.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import { registryPath } from "./paths.js";
+const GGUF_MAGIC = Buffer.from("GGUF", "ascii");
+async function fileExists(path) {
+    try {
+        const stat = await fsp.stat(path);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function isGgufHeader(path) {
+    try {
+        const fd = await fsp.open(path, "r");
+        try {
+            const buf = Buffer.alloc(4);
+            await fd.read(buf, 0, 4, 0);
+            return buf.equals(GGUF_MAGIC);
+        }
+        finally {
+            await fd.close();
+        }
+    }
+    catch {
+        return false;
+    }
+}
+export async function hashFile(path) {
+    return new Promise((resolve, reject) => {
+        const hasher = createHash("sha256");
+        const stream = fs.createReadStream(path, { highWaterMark: 1 << 20 });
+        stream.on("data", (chunk) => {
+            hasher.update(chunk);
+        });
+        stream.on("end", () => resolve(hasher.digest("hex")));
+        stream.on("error", reject);
+    });
+}
+/**
+ * Run the full verification pipeline on a model. Returns the state and
+ * the freshly computed hash so the caller can persist it to the registry.
+ */
+export async function verifyInstalledModel(model) {
+    if (!(await fileExists(model.path))) {
+        return {
+            state: "missing",
+            currentSha256: null,
+            expectedSha256: model.sha256 ?? null,
+            currentBytes: null,
+        };
+    }
+    const stat = await fsp.stat(model.path);
+    if (!(await isGgufHeader(model.path))) {
+        return {
+            state: "truncated",
+            currentSha256: null,
+            expectedSha256: model.sha256 ?? null,
+            currentBytes: stat.size,
+        };
+    }
+    const currentSha256 = await hashFile(model.path);
+    if (!model.sha256) {
+        // First-time verification — no baseline to compare against. Caller
+        // decides whether to treat this as "ok" and persist the hash.
+        return {
+            state: "unknown",
+            currentSha256,
+            expectedSha256: null,
+            currentBytes: stat.size,
+        };
+    }
+    return {
+        state: currentSha256 === model.sha256 ? "ok" : "mismatch",
+        currentSha256,
+        expectedSha256: model.sha256,
+        currentBytes: stat.size,
+    };
+}
+/** Helper for tests — no runtime use. */
+export function __registryPathForTests() {
+    return registryPath();
+}
+//# sourceMappingURL=verify.js.map

package/local-inference/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/local-inference/verify.ts"],"names":[],"mappings":"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"}

package/local-inference/voice-models.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Sub-model versioning for voice components.
+ *
+ * The bundle manifest (`eliza-1.manifest.json`) ships the *current* set of
+ * files for one tier. This module ships the *history*: every voice
+ * sub-model id we publish, every semver version, the parent it succeeds,
+ * the per-version eval deltas vs. that parent, the GGUF assets, and the
+ * minimum bundle version each voice version is compatible with.
+ *
+ * The publish pipeline writes both this file AND the matching H3 in
+ * the sibling `voice-models/CHANGELOG.md`. The publish gate refuses to
+ * land one without the other. The runtime auto-update checker reads
+ * only this file.
+ *
+ * Spec: `.swarm/research/R5-versioning.md` §2.
+ */
+/**
+ * Stable id for each voice sub-model. Never reused across architectures —
+ * if we rip out `voice-emotion` (Wav2Small) for a different classifier
+ * later, give it a new id rather than incrementing the version.
+ *
+ * Aligned with `Eliza1FilesSchema` keys where applicable and with the
+ * I1/I2/I3/I6/I7 implementations.
+ */
+export type VoiceModelId = "speaker-encoder" | "diarizer" | "turn-detector" | "turn-detector-intl" | "voice-emotion" | "kokoro" | "omnivoice" | "vad" | "wakeword" | "embedding" | "asr";
+/**
+ * Quant labels mirror `CatalogQuantizationVariant` ids used by the text
+ * GGUF catalog. ONNX-only voice models use a sentinel `onnx-*` quant tag.
+ */
+export type VoiceModelQuant = "q3_k_m" | "q4_0" | "q4_k_m" | "q5_k_m" | "q6_k" | "q8_0" | "gguf-fp32" | "fp16" | "onnx-fp32" | "onnx-fp16" | "onnx-int8";
+export interface VoiceModelGgufAsset {
+    /** Filename inside `hfRepo` at `hfRevision`. */
+    readonly filename: string;
+    /** SHA256 of the file at this revision, 64 lowercase hex chars. */
+    readonly sha256: string;
+    /** Bytes — used to gate downloads on cellular/metered links. */
+    readonly sizeBytes: number;
+    /** Quantization label. */
+    readonly quant: VoiceModelQuant;
+}
+export type VoiceModelMissingAssetReason = "missing-from-local-staging" | "missing-from-hf-repo";
+export interface VoiceModelMissingAsset {
+    /** Expected filename inside `hfRepo` at `hfRevision`. */
+    readonly filename: string;
+    /** Expected quantization label. */
+    readonly quant: VoiceModelQuant;
+    /** Approximate planned bytes from the staging manifest; not a verified size. */
+    readonly expectedSizeBytes?: number;
+    /** Why no sha256/sizeBytes are recorded in `ggufAssets`. */
+    readonly reason: VoiceModelMissingAssetReason;
+}
+/**
+ * Per-metric improvement vs the parent version. Sign conventions:
+ *
+ * - Negative-direction metrics (lower is better): `rtfDelta`, `werDelta`,
+ *   `eerDelta`, `falseBargeInDelta`. Negative deltas are improvements.
+ * - Positive-direction metrics (higher is better): `f1Delta`, `mosDelta`.
+ *   Positive deltas are improvements.
+ *
+ * The `netImprovement` flag is the audit trail set by the publish gate;
+ * the auto-updater requires `netImprovement === true` before it will
+ * recommend an automatic swap (see `shouldAutoUpdate` in
+ * `voice-model-updater.ts`).
+ */
+export interface VoiceModelEvalDeltas {
+    /** RTF improvement vs parentVersion, negative = faster. */
+    readonly rtfDelta?: number;
+    /** WER improvement vs parentVersion, negative = better. */
+    readonly werDelta?: number;
+    /** Equal-error-rate delta for speaker encoder; negative = better. */
+    readonly eerDelta?: number;
+    /** F1 delta for turn detector / emotion classifier; positive = better. */
+    readonly f1Delta?: number;
+    /** MOS / MOS-expressive delta for TTS; positive = better. */
+    readonly mosDelta?: number;
+    /** False-barge-in-rate delta for VAD; negative = better. */
+    readonly falseBargeInDelta?: number;
+    /**
+     * Overall improvement flag set by the publish gate from per-metric
+     * thresholds. Auto-update is gated on `netImprovement === true`.
+     * For initial releases (parentVersion absent), this is `true` if the
+     * model met its standalone publish thresholds.
+     */
+    readonly netImprovement: boolean;
+}
+/**
+ * Runtime backend label for a voice model version.
+ * - `"ggml"` — the elizaOS llama.cpp fork (canonical single-runtime policy).
+ * - `"onnx"` — onnxruntime-node (one-release deprecation runway only; do not add new models here).
+ * - `"ffi"` — direct bun:ffi into libelizainference (VAD, wake-word).
+ * - `"llama-server"` — fork's llama-server HTTP route (Kokoro, OmniVoice TTS, EOT text model).
+ */
+export type VoiceModelBackend = "ggml" | "onnx" | "ffi" | "llama-server";
+export interface VoiceModelVersion {
+    /** Stable id. */
+    readonly id: VoiceModelId;
+    /** Semver (e.g. "0.1.0", "1.2.0-rc.3"). */
+    readonly version: string;
+    /** Direct semver predecessor; absent on the initial release. */
+    readonly parentVersion?: string;
+    /** ISO timestamp of HF publish. */
+    readonly publishedToHfAt: string;
+    /** HuggingFace repo (`owner/name`) holding this version's assets. */
+    readonly hfRepo: string;
+    /** Git revision (commit SHA or tag) of the HF repo at publish time. */
+    readonly hfRevision: string;
+    /**
+     * Preferred runtime backend for this version. When set, the runtime
+     * prefers the named backend over any default. K7 policy: set to `"ggml"` /
+     * `"llama-server"` / `"ffi"` as each model migrates off ONNX. Assets with
+     * `quant: "onnx-*"` that are NOT the preferred backend are on the
+     * one-release deprecation runway.
+     */
+    readonly preferredBackend?: VoiceModelBackend;
+    /**
+     * Backends that are deprecated in this version and will be removed in the
+     * next release. The download manager surfaces these to the user; the
+     * runtime emits a deprecation warning when the deprecated backend is
+     * selected explicitly via env override.
+     */
+    readonly deprecatedBackends?: ReadonlyArray<VoiceModelBackend>;
+    /** Per-asset SHA256 + size + quant. */
+    readonly ggufAssets: ReadonlyArray<VoiceModelGgufAsset>;
+    /** Expected assets that were not available for sha256/size verification. */
+    readonly missingAssets?: ReadonlyArray<VoiceModelMissingAsset>;
+    /** Eval gates vs parentVersion (or baseline for initial releases). */
+    readonly evalDeltas: VoiceModelEvalDeltas;
+    /** First line of the matching H3 in the sibling `voice-models/CHANGELOG.md`. */
+    readonly changelogEntry: string;
+    /** Minimum `eliza1Manifest.version` this voice version is compatible with. */
+    readonly minBundleVersion: string;
+}
+/**
+ * Reverse-chronological history per model id. Index 0 is the latest.
+ *
+ * The publish pipeline prepends a new version; never edit a published
+ * entry in place (sha + size are the audit trail).
+ *
+ * Asset hashes and revisions are pinned audit data. `missingAssets` records
+ * unavailable upstream artifacts explicitly instead of using provisional
+ * checksums.
+ */
+export declare const VOICE_MODEL_VERSIONS: ReadonlyArray<VoiceModelVersion>;
+/**
+ * Strict semver compare. Returns -1 if a < b, 0 if equal, 1 if a > b.
+ * Pre-release ids are compared lexically per semver 2.0.0 §11. Returns
+ * null when either argument is not a valid semver.
+ */
+export declare function compareVoiceModelSemver(a: string, b: string): -1 | 0 | 1 | null;
+/** Return all versions for a given model id, latest first. */
+export declare function versionsFor(id: VoiceModelId): ReadonlyArray<VoiceModelVersion>;
+/** Latest known version for the given id, or undefined if none. */
+export declare function latestVoiceModelVersion(id: VoiceModelId): VoiceModelVersion | undefined;
+/** Lookup by id + exact version. */
+export declare function findVoiceModelVersion(id: VoiceModelId, version: string): VoiceModelVersion | undefined;
+//# sourceMappingURL=voice-models.d.ts.map

package/local-inference/voice-models.d.ts.map

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