egaki 0.5.0 → 0.7.0

package/src/cli/cached-generate.ts

@@ -0,0 +1,348 @@
+// General-purpose persisted memoization for expensive async functions.
+//
+// cachedGenerate() wraps any async function with:
+//   - Deterministic filesystem caching (params → stable hash → file)
+//   - Concurrent call deduplication (same key → same promise)
+//   - Stale fallback management (old results moved to stale/ subfolder)
+//   - Progress tracking (namespace-based, drives the player toolbar UI)
+//
+// Binary params (Uint8Array) are auto-hashed in the cache key. The caller
+// only provides a generate function, a serializer, and a namespace.
+//
+// Usage:
+//   const generateImage = cachedGenerate({
+//     namespace: 'image',
+//     prefixFrom: (p) => p.prompt,
+//     generate: (p) => generateImageUncached(p).then(r => r.images[0]!),
+//     serialize: (file) => ({ bytes: file.uint8Array, extension: '.png' }),
+//   })
+
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  stableJsonKey, hashKey, promptPrefix,
+  generatedDir, findCachedFile, findFallbackFile, moveFileToStale,
+  generationQueue, formatKeyParams,
+} from './cache-utils.js'
+
+// ---------------------------------------------------------------------------
+// Progress registry — tracks all active generations with metadata so the
+// client and agents can observe progress across all scenes.
+// Keyed by namespace string (not a fixed enum), so any user-defined
+// namespace automatically gets tracking.
+// ---------------------------------------------------------------------------
+
+export interface GenerationEntry {
+  namespace: string
+  label: string
+  model?: string
+  startedAt: number
+  params: Record<string, unknown>
+  /** URL path to the in-progress file. Set by onPartial writes during streaming
+   *  generation (e.g. accumulated audio written every ~2s). Cleared when
+   *  generation completes. Flows through the progress SSE to the client. */
+  partialSrc?: string
+}
+
+const generationRegistry: Map<string, GenerationEntry> =
+  (globalThis as any).__egakiGenerationRegistry ??= new Map<string, GenerationEntry>()
+
+type ProgressListener = () => void
+const progressListeners: Set<ProgressListener> =
+  (globalThis as any).__egakiProgressListeners ??= new Set<ProgressListener>()
+
+function notifyProgressListeners() {
+  for (const listener of progressListeners) {
+    try { listener() } catch { /* listener errors are non-fatal */ }
+  }
+}
+
+/** Subscribe to generation progress changes. Returns an unsubscribe function. */
+export function onProgressChange(listener: ProgressListener): () => void {
+  progressListeners.add(listener)
+  return () => { progressListeners.delete(listener) }
+}
+
+export interface GenerationProgressSummary {
+  counts: Record<string, number>
+  total: number
+}
+
+export interface GenerationProgressEntry extends GenerationEntry {
+  key: string
+  elapsedMs: number
+}
+
+export interface GenerationError {
+  key: string
+  namespace: string
+  label: string
+  model?: string
+  error: string
+  durationMs: number
+}
+
+export interface GenerationProgressEvent {
+  generations: GenerationProgressEntry[]
+  errors: GenerationError[]
+  summary: GenerationProgressSummary
+  done: boolean
+}
+
+/** Recent generation errors, drained on each getGenerationProgress() call
+ *  so each SSE event includes errors that happened since the last yield. */
+const recentErrors: GenerationError[] =
+  (globalThis as any).__egakiRecentErrors ??= [] as GenerationError[]
+
+/** Get a snapshot of all active generations with elapsed time computed.
+ *  Drains the error queue so each call returns only new errors since last read. */
+export function getGenerationProgress(): GenerationProgressEvent {
+  const now = Date.now()
+  const generations: GenerationProgressEntry[] = []
+  const counts: Record<string, number> = {}
+  for (const [key, entry] of generationRegistry) {
+    generations.push({ ...entry, key, elapsedMs: now - entry.startedAt })
+    counts[entry.namespace] = (counts[entry.namespace] ?? 0) + 1
+  }
+  const total = generations.length
+  const errors = recentErrors.splice(0)
+  return {
+    generations,
+    errors,
+    summary: { counts, total },
+    done: total === 0 && errors.length === 0,
+  }
+}
+
+function registerGeneration(key: string, entry: GenerationEntry) {
+  generationRegistry.set(key, entry)
+  notifyProgressListeners()
+}
+
+function unregisterGeneration(key: string, error?: string) {
+  const entry = generationRegistry.get(key)
+  if (entry && error) {
+    recentErrors.push({
+      key,
+      namespace: entry.namespace,
+      label: entry.label,
+      model: entry.model,
+      error,
+      durationMs: Date.now() - entry.startedAt,
+    })
+  }
+  generationRegistry.delete(key)
+  notifyProgressListeners()
+}
+
+// ---------------------------------------------------------------------------
+// Auto cache key — recursively walks params, hashes Uint8Array values,
+// strips undefined. Handles nested objects and arrays of any depth.
+// ---------------------------------------------------------------------------
+
+function normalizeCacheValue(value: unknown): unknown {
+  if (value === undefined) return undefined
+  if (value instanceof Uint8Array) return hashKey(value)
+  if (Array.isArray(value)) return value.map(normalizeCacheValue)
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => [k, normalizeCacheValue(v)]),
+    )
+  }
+  return value
+}
+
+function autoCacheKey(params: Record<string, unknown>): Record<string, unknown> {
+  return normalizeCacheValue(params) as Record<string, unknown>
+}
+
+// ---------------------------------------------------------------------------
+// cachedGenerate — the higher-order function
+// ---------------------------------------------------------------------------
+
+type SerializeResult =
+  | { bytes: Uint8Array; extension: string; prefix?: string }
+  | { json: unknown; extension: '.json'; prefix?: string }
+
+export interface CachedGenerateConfig<TParams, TGenerated, TResult> {
+  /** Filesystem namespace: files go to `public/generated/{namespace}/` */
+  namespace: string
+
+  /** Human-readable filename prefix derived from params */
+  prefixFrom: (params: TParams) => string
+
+  /** Extract the cache-relevant subset of params. Use this to exclude fields
+   *  that affect naming but not identity (e.g. `filename` in transcription).
+   *  Defaults to using all params. Uint8Array values are auto-hashed regardless. */
+  cacheKey?: (params: TParams) => Record<string, unknown>
+
+  /** The actual generation function. Throw on error. */
+  generate: (params: TParams) => Promise<TGenerated>
+
+  /** How to persist the result to disk.
+   *  Return { bytes, extension } for binary files or { json, extension: '.json' } for data.
+   *  Optionally return { prefix } to override the filename prefix (e.g. when
+   *  the readable name comes from the result, not the params). */
+  serialize: (result: TGenerated, params: TParams) => SerializeResult
+
+  /** How to read a cached result back.
+   *  For binary: receives { urlPath, filePath }, defaults to { src: urlPath }.
+   *  For JSON: filePath contains the JSON data. */
+  deserialize?: (cached: { urlPath: string; filePath: string }) => TResult
+
+  /** Model ID key in params, used for progress tracking display. */
+  modelFrom?: (params: TParams) => string | undefined
+
+  /** Called after the main file is written to disk. Use this to write
+   *  sidecar files (e.g. timestamps JSON alongside audio).
+   *  Receives the generated result so it can extract extra data to persist. */
+  postWrite?: (filePath: string, result: TGenerated, params: TParams) => void
+}
+
+/** Result of getCacheInfo — used by server components for sync cache checks
+ *  and fallback lookup before starting async generation. */
+export interface CacheInfo {
+  hash: string
+  prefix: string
+  dir: string
+  key: string
+  cached: string | undefined
+  fallback: { filename: string; inStale: boolean } | undefined
+  fallbackSrc: string | undefined
+}
+
+/** Compute cache info for a given namespace and params without starting generation.
+ *  Used by server components to check cache and find fallback synchronously. */
+export function getCacheInfo(
+  namespace: string,
+  params: Record<string, unknown>,
+  prefixText: string,
+): CacheInfo {
+  const keyParams = autoCacheKey(params)
+  // Note: getCacheInfo uses the raw params. If a cachedGenerate wrapper uses
+  // cacheKey to exclude fields, the caller should pass the same subset here.
+  const key = stableJsonKey(keyParams)
+  const hash = hashKey(key)
+  const dir = generatedDir(namespace)
+  const prefix = promptPrefix(prefixText)
+
+  const cached = findCachedFile(dir, hash)
+  const fallback = cached ? undefined : findFallbackFile(dir, prefix, hash)
+  const fallbackSrc = fallback
+    ? `/generated/${namespace}/${fallback.inStale ? 'stale/' : ''}${fallback.filename}`
+    : undefined
+
+  return { hash, prefix, dir, key, cached, fallback, fallbackSrc }
+}
+
+export type CachedGenerateFn<TParams, TResult> = {
+  (params: TParams): Promise<Error | TResult>
+  /** Sync cache check using the same config as the cached function. */
+  getCacheInfo(params: TParams): CacheInfo
+}
+
+export function cachedGenerate<TParams, TGenerated, TResult = { src: string }>(
+  config: CachedGenerateConfig<TParams, TGenerated, TResult>,
+): CachedGenerateFn<TParams, TResult> {
+  const { namespace, prefixFrom, cacheKey, generate, serialize, deserialize, modelFrom, postWrite } = config
+
+  function cachedFn(params: TParams): Promise<Error | TResult> {
+    const rawKeyParams = cacheKey ? cacheKey(params) : (params as Record<string, unknown>)
+    const keyParams = autoCacheKey(rawKeyParams)
+    const key = stableJsonKey(keyParams)
+    const hash = hashKey(key)
+    const dir = generatedDir(namespace)
+    const prefix = promptPrefix(prefixFrom(params))
+
+    // Queue key includes namespace to prevent cross-namespace collisions.
+    // Two wrappers with different namespaces but identical params must not
+    // share the same in-flight promise.
+    const queueKey = `${namespace}:${key}`
+
+    // 1. Cache hit — return immediately
+    const cached = findCachedFile(dir, hash)
+    if (cached) {
+      const urlPath = `/generated/${namespace}/${cached}`
+      const filePath = path.join(dir, cached)
+      if (deserialize) {
+        return Promise.resolve(deserialize({ urlPath, filePath }))
+      }
+      return Promise.resolve({ src: urlPath } as TResult)
+    }
+
+    // 2. Dedup — return pending promise if same key is in-flight
+    const pending = generationQueue.get(queueKey)
+    if (pending) return pending
+
+    // 3. Find stale fallback for cleanup after generation
+    const fallback = findFallbackFile(dir, prefix, hash)
+
+    // 4. Register progress
+    const regKey = `${namespace}:${hash}`
+    const label = prefixFrom(params)
+    registerGeneration(regKey, {
+      namespace,
+      label,
+      model: modelFrom?.(params),
+      startedAt: Date.now(),
+      params: keyParams,
+    })
+
+    // 5. Generate, serialize, write to disk
+    // The entire body is wrapped in try/catch so that failures in serialize(),
+    // fs.writeFileSync(), or deserialize() also unregister progress and return
+    // Error instead of throwing through the promise.
+    const promise = (async (): Promise<Error | TResult> => {
+      try {
+        console.log(`[egaki] generating ${namespace}: ${prefix}-${hash} (${formatKeyParams(keyParams)})`)
+
+        const result = await generate(params)
+
+        const serialized = serialize(result, params)
+        const finalPrefix = serialized.prefix ? promptPrefix(serialized.prefix) : prefix
+        const filename = `${finalPrefix}-${hash}${serialized.extension}`
+        const filePath = path.join(dir, filename)
+
+        if ('bytes' in serialized) {
+          fs.writeFileSync(filePath, serialized.bytes)
+        } else {
+          fs.writeFileSync(filePath, JSON.stringify(serialized.json, null, 2))
+        }
+
+        if (postWrite) {
+          try { postWrite(filePath, result, params) } catch (e) {
+            console.error(`[egaki] postWrite error for ${namespace}:`, e)
+          }
+        }
+
+        console.log(`[egaki] generated ${namespace}: ${filename}`)
+        if (fallback) moveFileToStale(dir, fallback)
+        unregisterGeneration(regKey)
+
+        const urlPath = `/generated/${namespace}/${filename}`
+        if (deserialize) {
+          return deserialize({ urlPath, filePath })
+        }
+        return { src: urlPath } as TResult
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err))
+        unregisterGeneration(regKey, error.message)
+        return error
+      } finally {
+        generationQueue.delete(queueKey)
+      }
+    })()
+
+    generationQueue.set(queueKey, promise)
+    return promise
+  }
+
+  cachedFn.getCacheInfo = function (params: TParams): CacheInfo {
+    const rawKeyParams = cacheKey ? cacheKey(params) : (params as Record<string, unknown>)
+    return getCacheInfo(namespace, rawKeyParams, prefixFrom(params))
+  }
+
+  return cachedFn
+}

package/src/cli/cartesia-provider.ts

@@ -0,0 +1,249 @@
+// Custom Cartesia TTS and STT providers.
+//
+// TTS: POST https://api.cartesia.ai/tts/sse with add_timestamps=true
+//   Returns word-level timestamps natively via SSE events.
+//   API docs: https://docs.cartesia.ai/api-reference/tts/sse
+//
+// STT: POST https://api.cartesia.ai/stt (Ink models)
+//   API docs: https://docs.cartesia.ai/api-reference/stt/transcribe
+//
+// Source of truth for request/response types:
+//   JS SDK (auto-generated from OpenAPI spec by Stainless):
+//   https://github.com/cartesia-ai/cartesia-js/blob/main/src/resources/stt/stt.ts
+//   https://github.com/cartesia-ai/cartesia-js/blob/main/src/resources/tts.ts
+//
+// TTS models: https://docs.cartesia.ai/build-with-cartesia/tts-models/latest
+// STT models: https://docs.cartesia.ai/build-with-cartesia/stt/latest
+// Pricing: https://docs.cartesia.ai/pricing
+
+import type { SpeechProvider, SpeechProviderOptions, SpeechProviderResult } from './speech-generate.js'
+import type { WordTimestamp } from './transcription-generate.js'
+
+const CARTESIA_API_BASE = 'https://api.cartesia.ai'
+const CARTESIA_API_VERSION = '2026-03-01'
+
+// Default voice: Katie (en-US Female), recommended for voice agents
+const DEFAULT_VOICE_ID = 'f786b574-daa5-4673-aa0c-cbe3e8534c02'
+
+// ─── shared helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Map user-facing format strings to Cartesia output_format objects.
+ * The SSE endpoint only supports raw container (not mp3/wav), so we
+ * always use raw PCM for SSE streaming.
+ */
+function buildSseOutputFormat(format?: string): {
+  container: 'raw'
+  encoding: string
+  sample_rate: number
+} {
+  // SSE endpoint only supports raw container. We always use PCM s16le
+  // and let the caller convert if needed.
+  const sampleRate = format === 'pcm_16000' ? 16000
+    : format === 'pcm_22050' ? 22050
+    : format === 'pcm_24000' ? 24000
+    : 44100
+  return { container: 'raw', encoding: 'pcm_s16le', sample_rate: sampleRate }
+}
+
+// ─── SSE event types ─────────────────────────────────────────────────────────
+// From https://docs.cartesia.ai/api-reference/tts/sse
+
+interface CartesiaSseChunk {
+  type: 'chunk'
+  data: string // base64 encoded audio
+}
+
+interface CartesiaSseTimestamps {
+  type: 'timestamps'
+  word_timestamps: {
+    words: string[]
+    start: number[]
+    end: number[]
+  }
+}
+
+interface CartesiaSseDone {
+  type: 'done'
+}
+
+interface CartesiaSseError {
+  type: 'error'
+  message: string
+  status_code: number
+}
+
+type CartesiaSseEvent = CartesiaSseChunk | CartesiaSseTimestamps | CartesiaSseDone | CartesiaSseError
+
+// ─── SSE parser ──────────────────────────────────────────────────────────────
+
+import { EventSourceParserStream } from 'eventsource-parser/stream'
+
+/**
+ * Parse a Cartesia SSE stream into audio chunks and word timestamps.
+ * Uses eventsource-parser for robust SSE frame parsing.
+ */
+export async function parseCartesiaSseStream(
+  body: ReadableStream<Uint8Array>,
+): Promise<{ audioChunks: Uint8Array[]; timestamps: WordTimestamp[] }> {
+  const audioChunks: Uint8Array[] = []
+  const timestamps: WordTimestamp[] = []
+
+  const eventStream = body
+    .pipeThrough(new TextDecoderStream() as any)
+    .pipeThrough(new EventSourceParserStream())
+
+  const reader = eventStream.getReader()
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+
+    let event: CartesiaSseEvent
+    try {
+      event = JSON.parse(value.data)
+    } catch {
+      continue
+    }
+
+    if (event.type === 'chunk') {
+      audioChunks.push(new Uint8Array(Buffer.from(event.data, 'base64')))
+    } else if (event.type === 'timestamps') {
+      const ts = event.word_timestamps
+      for (let i = 0; i < ts.words.length; i++) {
+        timestamps.push({
+          word: ts.words[i]!,
+          startSecond: ts.start[i]!,
+          endSecond: ts.end[i]!,
+        })
+      }
+    } else if (event.type === 'error') {
+      throw new Error(`Cartesia TTS SSE error ${event.status_code}: ${event.message}`)
+    }
+  }
+
+  return { audioChunks, timestamps }
+}
+
+/** Concatenate multiple Uint8Array chunks into one. */
+function concatUint8Arrays(chunks: Uint8Array[]): Uint8Array {
+  const totalLength = chunks.reduce((sum, c) => sum + c.length, 0)
+  const result = new Uint8Array(totalLength)
+  let offset = 0
+  for (const chunk of chunks) {
+    result.set(chunk, offset)
+    offset += chunk.length
+  }
+  return result
+}
+
+/**
+ * Wrap raw PCM s16le mono audio into a WAV container.
+ * The SSE endpoint only supports raw PCM output, but browsers need a
+ * proper container format. WAV is the simplest lossless wrapper.
+ */
+function wavFromPcmS16Le(pcm: Uint8Array, sampleRate: number): Uint8Array {
+  const header = new ArrayBuffer(44)
+  const view = new DataView(header)
+  const channels = 1
+  const bitsPerSample = 16
+  const byteRate = sampleRate * channels * (bitsPerSample / 8)
+  const blockAlign = channels * (bitsPerSample / 8)
+
+  const writeStr = (offset: number, str: string) => {
+    for (let i = 0; i < str.length; i++) view.setUint8(offset + i, str.charCodeAt(i))
+  }
+
+  writeStr(0, 'RIFF')
+  view.setUint32(4, 36 + pcm.byteLength, true)
+  writeStr(8, 'WAVE')
+  writeStr(12, 'fmt ')
+  view.setUint32(16, 16, true)            // subchunk1 size (PCM)
+  view.setUint16(20, 1, true)             // audio format (PCM = 1)
+  view.setUint16(22, channels, true)
+  view.setUint32(24, sampleRate, true)
+  view.setUint32(28, byteRate, true)
+  view.setUint16(32, blockAlign, true)
+  view.setUint16(34, bitsPerSample, true)
+  writeStr(36, 'data')
+  view.setUint32(40, pcm.byteLength, true)
+
+  const wav = new Uint8Array(44 + pcm.byteLength)
+  wav.set(new Uint8Array(header), 0)
+  wav.set(pcm, 44)
+  return wav
+}
+
+// ─── Cartesia TTS SpeechProvider ─────────────────────────────────────────────
+
+/**
+ * Create a Cartesia speech provider using the SSE endpoint with word timestamps.
+ * Returns raw PCM audio (pcm_s16le) since the SSE endpoint only supports raw container.
+ */
+export function createCartesiaSpeechProvider(): SpeechProvider {
+  return {
+    async generate(options: SpeechProviderOptions): Promise<SpeechProviderResult> {
+      const apiKey = process.env['CARTESIA_API_KEY']
+      if (!apiKey) {
+        throw new Error('Missing CARTESIA_API_KEY. Run: egaki login --provider cartesia --key <key>')
+      }
+
+      const voiceId = options.voice || DEFAULT_VOICE_ID
+      const outputFormat = buildSseOutputFormat(options.outputFormat)
+
+      const body: Record<string, unknown> = {
+        model_id: options.modelId,
+        transcript: options.text,
+        voice: { mode: 'id', id: voiceId },
+        output_format: outputFormat,
+        add_timestamps: true,
+      }
+
+      if (options.language) {
+        body.language = options.language
+      }
+
+      if (options.speed != null) {
+        body.generation_config = { speed: options.speed }
+      }
+
+      const response = await fetch(`${CARTESIA_API_BASE}/tts/sse`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Cartesia-Version': CARTESIA_API_VERSION,
+          'Authorization': `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+        signal: options.abortSignal,
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => '')
+        throw new Error(
+          `Cartesia TTS SSE API error ${response.status}: ${errorText || response.statusText}`,
+        )
+      }
+
+      if (!response.body) {
+        throw new Error('Cartesia TTS SSE response has no body')
+      }
+
+      const { audioChunks, timestamps } = await parseCartesiaSseStream(response.body)
+      const pcm = concatUint8Arrays(audioChunks)
+      // Wrap raw PCM in WAV container so browsers can play the audio.
+      const audio = wavFromPcmS16Le(pcm, outputFormat.sample_rate)
+
+      return {
+        audio,
+        mediaType: 'audio/wav',
+        timestamps: timestamps.length > 0 ? timestamps : undefined,
+      }
+    },
+  }
+}
+
+// Cartesia STT is now implemented as a TranscriptionProvider in
+// transcription-providers.ts (createCartesiaTranscriptionProvider).
+// The old TranscriptionModel-based implementation was removed to drop
+// the AI SDK dependency from the transcription path.