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

package/src/services/voice/first-line-cache.d.ts

@@ -0,0 +1,181 @@
+/**
+ * First-line LRU TTS cache (disk-tier, voice-scoped).
+ *
+ * The in-RAM `PhraseCache` is the hot tier (keyed on text alone, single voice
+ * per scheduler). This disk-tier sits behind it and is keyed on
+ *   (algoVersion, provider, voiceId, voiceRevision, sampleRate, codec,
+ *    voiceSettingsFingerprint, normalizedText)
+ * so the F3 bug in `.swarm/VOICE_WAVE_2.md` (Kokoro→ElevenLabs voice swap
+ * replaying Kokoro audio) is impossible by construction: swapping the active
+ * voice changes `voiceId` and therefore changes the cache key.
+ *
+ * Storage layout (anchored to `resolveStateDir()`):
+ *   <stateDir>/cache/tts-first-line/
+ *     ├── index.sqlite                            -- LRU manifest
+ *     └── blobs/
+ *         <provider>/<voiceId>/<voiceRevision>/<keyHash>.<ext>
+ *
+ * Index schema:
+ *   See `INDEX_SCHEMA_SQL` below.
+ *
+ * Eviction: LRU by `last_accessed_at_ms`, bounded by a configurable byte
+ * budget (default 64 MB), per-entry cap (default 256 KB), TTL (default 30 d).
+ *
+ * Safety rules (see R4 §6):
+ *   - empty `voiceRevision` rejected at insert.
+ *   - cancelled / errored synth never reaches `put`.
+ *   - non-default `voiceSettingsFingerprint` produces a different key.
+ *   - `realtime` / non-deterministic provider models live on a per-call
+ *     bypass list (callers consult `firstLineCacheBypassFromEnv`).
+ *
+ * Concurrency: SQLite is opened in WAL mode for many-readers / single-writer
+ * across the runtime, dashboard server, and any spawned coding-agent
+ * processes that emit speech. Blob writes go through a temp file + atomic
+ * rename so partials never reach the index.
+ *
+ * SQLite resolution mirrors `packages/app-core/src/api/training-benchmarks.ts`:
+ * try `node:sqlite` (Node ≥22.5), then `bun:sqlite` (Bun). Neither runtime
+ * ships both. When neither is present the cache silently no-ops (`get` returns
+ * null, `put` returns false) — the caller's fallback path (synthesize fresh)
+ * still works.
+ */
+import { FIRST_SENTENCE_MAX_WORDS, FIRST_SENTENCE_SNIP_VERSION, type FirstSentenceSnipResult, firstSentenceSnip, wordCount } from "@elizaos/shared";
+/**
+ * Logical cache key. The on-disk filename + index row are keyed on
+ * `keyHash`, computed deterministically from this record.
+ */
+export interface FirstLineCacheKey {
+    /** Pinned to `FIRST_SENTENCE_SNIP_VERSION`; bumping it invalidates every entry. */
+    readonly algoVersion: string;
+    readonly provider: string;
+    readonly voiceId: string;
+    /** sha256 of voice pack + model file (local) or `client.voices.get`
+     * settings hash (cloud-side). MUST be non-empty. */
+    readonly voiceRevision: string;
+    readonly sampleRate: number;
+    readonly codec: "opus" | "mp3" | "wav" | "pcm_f32" | "ogg" | "flac";
+    /** sha256 of `{stability, similarityBoost, style, useSpeakerBoost, speed,
+     *  pitch, ...}` JSON normalised by `fingerprintVoiceSettings`. */
+    readonly voiceSettingsFingerprint: string;
+    /** Output of `normalizeForKey(snip)`. */
+    readonly normalizedText: string;
+}
+/** Stored row + bytes. */
+export interface FirstLineCacheEntry extends FirstLineCacheKey {
+    /** Encoded payload bytes. */
+    bytes: Uint8Array;
+    /** Raw (un-normalised) snip — kept for DEBUG logs only. */
+    rawText: string;
+    /** Negotiated content-type, e.g. `audio/mpeg`, `audio/opus`. */
+    contentType: string;
+    /** Synthesized audio length, used for player buffering math. */
+    durationMs: number;
+    /** Unicode-aware word count over `normalizedText`. */
+    wordCount: number;
+    /** Epoch-ms of last access; updated on get(). */
+    lastAccessedAtMs: number;
+    /** Epoch-ms of original synthesis. */
+    generatedAtMs: number;
+    /** Diagnostic counter, incremented on every get(). */
+    hitCount: number;
+}
+export interface FirstLineCacheOptions {
+    /** Root directory; defaults to `<stateDir>/cache/tts-first-line/`. */
+    rootDir?: string;
+    /** Total byte budget on disk; defaults to 64 MB. */
+    maxBytes?: number;
+    /** Per-entry byte cap; defaults to 256 KB. */
+    maxBytesPerEntry?: number;
+    /** Soft TTL in days; defaults to 30. */
+    ttlDays?: number;
+    /** When true, get/put both no-op (used by tests + emergency kill-switch). */
+    disabled?: boolean;
+}
+export interface PutInput extends FirstLineCacheKey {
+    bytes: Uint8Array;
+    rawText: string;
+    contentType: string;
+    durationMs: number;
+    wordCount?: number;
+}
+/**
+ * Comma-separated provider names that bypass the cache entirely.
+ * Default: empty (none).
+ * Set `ELIZA_TTS_CACHE_BYPASS_PROVIDERS="omnivoice,kokoro"` to skip those.
+ */
+export declare function firstLineCacheBypassFromEnv(): ReadonlySet<string>;
+/**
+ * Deterministic hash of the cache key. Stable across processes.
+ */
+export declare function hashCacheKey(key: FirstLineCacheKey): string;
+/**
+ * Stable sha256 hex of an arbitrary settings object — used as
+ * `voiceSettingsFingerprint`. Object keys are sorted before serialisation so
+ * the order in which the caller built the object doesn't affect the hash.
+ */
+export declare function fingerprintVoiceSettings(settings: Record<string, unknown> | null | undefined): string;
+export declare function computeLocalVoiceRevision(files: ReadonlyArray<string>): Promise<string>;
+/** Test-only — clear the voice-revision memoisation. */
+export declare function _resetVoiceRevisionMemoForTesting(): void;
+export interface FirstLineCacheStats {
+    entries: number;
+    bytes: number;
+    maxBytes: number;
+    dbReady: boolean;
+}
+export declare class FirstLineCache {
+    private readonly rootDir;
+    private readonly blobsDir;
+    private readonly indexPath;
+    private readonly maxBytes;
+    private readonly maxBytesPerEntry;
+    private readonly ttlMs;
+    private readonly disabled;
+    private db;
+    private initialised;
+    private initFailed;
+    constructor(opts?: FirstLineCacheOptions);
+    get isEnabled(): boolean;
+    /**
+     * Lazy-init the SQLite index and blob directory. Returns `false` if
+     * neither `node:sqlite` nor `bun:sqlite` is available — the cache then
+     * no-ops on every call.
+     */
+    private ensureInit;
+    /**
+     * Look up a cached entry. Returns null on miss. Touches `lastAccessedAtMs`
+     * + `hitCount` on hit. Lazy-reads the blob bytes from disk.
+     */
+    get(key: FirstLineCacheKey): FirstLineCacheEntry | null;
+    has(key: FirstLineCacheKey): boolean;
+    /**
+     * Store an entry. Returns true on success, false when rejected (bad key,
+     * over-budget per-entry, sqlite unavailable, etc.).
+     *
+     * Per R4 §6: `voiceRevision` MUST be non-empty (otherwise stale bytes
+     * could survive a voice re-publish). `bytes.length === 0` is rejected
+     * too — we don't cache empty audio (likely a cancelled synthesis).
+     */
+    put(input: PutInput): boolean;
+    /**
+     * Delete one entry by key. Removes both row and blob. Idempotent.
+     */
+    delete(key: FirstLineCacheKey): boolean;
+    /**
+     * Sweep entries older than the TTL. Returns the number of entries removed.
+     */
+    sweep(now?: number): number;
+    stats(): FirstLineCacheStats;
+    close(): void;
+    private evictOverflow;
+    private resolveBlobAbs;
+}
+/**
+ * Per-process singleton. Tests should construct their own `FirstLineCache`
+ * pointing at a temp dir instead of using this one.
+ */
+export declare function getSharedFirstLineCache(): FirstLineCache;
+/** Test-only — reset the process-wide singleton. */
+export declare function _resetSharedFirstLineCacheForTesting(): void;
+export { FIRST_SENTENCE_MAX_WORDS, FIRST_SENTENCE_SNIP_VERSION, type FirstSentenceSnipResult, firstSentenceSnip, wordCount, };
+//# sourceMappingURL=first-line-cache.d.ts.map

package/src/services/voice/first-line-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-line-cache.d.ts","sourceRoot":"","sources":["first-line-cache.ts"],"names":[],"mappings":"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"}