@elizaos/shared 2.0.0-beta.1 → 2.0.3-beta.3

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 (removed; retained only as a historical asset/label for already-published versions — 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 migrated off ONNX. onnxruntime-node
+     * has since been removed, so assets with `quant: "onnx-*"` are historical
+     * labels only — the runtime never loads them.
+     */
+    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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"}