@startsimpli/llm 0.4.29 → 0.4.31

package/README.md

@@ -181,9 +181,9 @@ Per CLAUDE.md **rule 9**, LLM client wiring never belongs in app `src/`. If you
 
 ## Speech (`@startsimpli/llm/speech`)
 
-Pluggable speech-to-text, same provider pattern as the text service. **It picks the
-cheapest vendor that has a key** — each provider states its list price — and falls
-through to the next cheapest on failure.
+Pluggable speech-to-text and text-to-speech, same provider pattern as the text service.
+**Each direction picks the cheapest vendor that has a key** — each provider states its
+list price — and falls through to the next cheapest on failure.
 
 ```ts
 import { SpeechService } from '@startsimpli/llm/speech';
@@ -196,11 +196,39 @@ const { text, words } = await speech.transcribe({
 
 | Env | Provider | List price |
 | --- | --- | --- |
-| `OPENAI_API_KEY` | OpenAI `gpt-4o-mini-transcribe` (default; `gpt-4o-transcribe` / `whisper-1` cost 2x) | $0.18 / hour |
-| `ELEVENLABS_API_KEY` | ElevenLabs Scribe (keyterm hints are a billed add-on, so off unless `sendKeyterms`) | $0.22 / hour |
+| `OPENAI_API_KEY` | OpenAI TTS (`gpt-4o-mini-tts`, no alignment) and `gpt-4o-mini-transcribe` (default; `gpt-4o-transcribe` / `whisper-1` cost 2x) | $0.18 / hour |
+| `ELEVENLABS_API_KEY` | ElevenLabs Scribe + text-to-speech with alignment (`ELEVENLABS_VOICE_ID` = default voice); Scribe (keyterm hints are a billed add-on, so off unless `sendKeyterms`) | $0.22 / hour |
 | `SPEECH_PROVIDER=mock` | deterministic, for tests | — |
 | `SPEECH_PROVIDER` / `SPEECH_LANGUAGE` | force a vendor / pin the language (e.g. `en`) so short clips don't mis-detect | — |
 
+**Text to speech**
+
+```ts
+const { audio, mimeType, words, characters, durationSec, usage } = await speech.synthesize({
+  text: 'Plan mode changes that.',
+  voiceId, model: 'eleven_v3', outputFormat: 'mp3_44100_128',   // voiceId defaults to ELEVENLABS_VOICE_ID
+  style: { tags: ['excited'], speed: 1.05, stability: 0.4 },     // tags only on models that read them
+});
+// usage = { characters, costUsd } at the model's list rate
+```
+
+`words` come from the vendor's character alignment (absent when it gives none, as OpenAI's doesn't).
+`[tag]` audio markup is not a word: it is dropped from `words` with the timing offsets kept; `characters`
+is the raw alignment and `keepTags: true` keeps tags in `words`. `voiceSettings` passes raw vendor
+settings and wins over `style`.
+
+**CLI for non-TS callers** — `startsimpli-speech` (JSON in via `--in` or stdin, JSON on stdout, audio to a file;
+keys from env only; exit 0 ok, 1 provider error as `{"error":{code,retryable,...}}`, 2 bad command line):
+
+```bash
+echo '{"text":"[excited] Hello.","model":"eleven_v3","style":{"speed":1.0}}' \
+  | startsimpli-speech synthesize --out hello.mp3 [--voice ID --model ID --format pcm_22050 --voice-settings '{"stability":0.3}']
+# -> {"mimeType":"audio/mpeg","audioPath":"hello.mp3","bytes":...,"words":[{"text":"Hello.","start":..,"end":..}],"characters":[...],"usage":{"characters":..,"costUsd":..},...}
+echo '{"audioPath":"hello.mp3"}' | startsimpli-speech transcribe   # -> {"text":..,"words":[..],"usage":{..}}
+```
+
+It runs the tsup bundle when built (`pnpm --filter @startsimpli/llm build`), else the source via `tsx`.
+
 Retryable errors back off and retry; a failure that survives falls through to the next
 vendor (`fallback: false` to pin one). Bad audio (`INVALID_REQUEST`) never falls through.
 
@@ -213,10 +241,53 @@ registerSpeechProvider('mine', () => (process.env.MINE_KEY ? new MyProvider(proc
 ```
 
 `registerLLMProvider(name, factory)` does the same for text. Both sit on `ProviderRegistry`,
+<<<<<<< HEAD
 so a new modality (TTS, embeddings) reuses it rather than hard-coding a provider list.
 
+### Voice cast library (`@startsimpli/llm/speech/voices`)
+
+Voices keyed by neutral ids (never by avatar), with model, per-model settings, per-language rows, an emotion map, and the
+retired / expiring ElevenLabs Default voice ids (they die 2026-12-31). Data is `src/speech/voices/cast-voices.json`.
+
+```ts
+const cv = createCastVoices(defaultCastLibrary, { expiring: 'warn' });      // warn | allow | error; `today` injectable
+const voices = cv.resolveCast([{ id: 'maya', voice: 'maya' }, { id: 'b' }], { language: 'es' });
+const { textSent, settings } = directEmotion(cv, voices.b, 'Hello.', 'excited');
+```
+
+A member's `voice` is a library id or a real voice id; anything else is an alias and the member takes the next `default_pool`
+entry. Unfilled slot, retired / expiring id, unknown model or language, and two members on one voice throw named errors
+(`VoiceNotResolvableError` subclasses). CLI: `echo '{"cast":[{"id":"a"}]}' | startsimpli-speech voices resolve [--model --language --expiring --today --library]`.
+
+### Captions (`@startsimpli/llm/speech/captions`)
+
+Pure caption logic, no vendor and no I/O: `cuesFromWords` / `cuesFromText` / `cuesForBeat` (clause-aware splitting),
+`holdGaps`, `cueFrameRange` (round half to even), `toSrt` / `toVtt`, and word checks: `wordsAreProportional` (is this
+vendor alignment real or spread by character count?), `assertValidWords` (`InvalidWordsError` on empty or disordered
+transcripts), `splitWhitespaceTokens`, `captionTiming`. Pixel and line-width layout stays with the renderer.
+CLI: `startsimpli-speech captions --format json|srt|vtt [--out FILE] < request.json`.
+
+## Refine with gates (`@startsimpli/llm/refine`)
+
+```ts
+const gates = createGateRegistry<Doc, Ctx>();
+gates.register('schema', (doc, ctx) => validate(doc));            // string[] | { text, level: 'info' }[] , sync or async
+const out = await refineWithGates({
+  step: llmRefineStep({ provider, systemPrompt, brief, validate }), // one model call per try; inject any client
+  gates, tries: 3,                                                  // an integer >= 1, or null to loop until every gate passes
+});
+// out.attempts[i] = { n, result, report, notes, cost, passed }; out.cost, out.tally, out.passed
+```
+
+Each try is exactly one step call; the step receives the previous result and the gates' failures as data. Informational
+lines (`level: 'info'`) never fail a gate. A step that throws ends the loop with `RefineStepError`. This is the multi-gate,
+caller-bounded loop; `extractValidateCorrect` stays the single-validator JSON repair loop.
+
 ## Links
 
 - Source: https://github.com/qosha1/start-simpli/tree/main/packages/llm
 - Homepage: https://startsimpli.com
 - License: MIT, see [LICENSE](./LICENSE)
+=======
+so a new modality (embeddings) reuses it rather than hard-coding a provider list.
+>>>>>>> eda91372 (speech: synthesize() with alignment, ElevenLabs TTS, tags and style, startsimpli-speech CLI)

package/bin/startsimpli-speech.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Launcher for the speech CLI. Packages here publish TypeScript source, so this
+// runs the tsup bundle (`pnpm build`) when it exists, else the source via tsx.
+const { existsSync } = require('node:fs');
+const { join } = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const root = join(__dirname, '..');
+const bundle = join(root, 'dist', 'speech', 'bin.js');
+const localTsx = join(root, 'node_modules', '.bin', 'tsx');
+const args = process.argv.slice(2);
+if (existsSync(bundle)) {
+  process.argv.splice(1, 1, bundle);
+  require(bundle);
+} else {
+  const tsx = spawnSync(existsSync(localTsx) ? localTsx : 'tsx', [join(root, 'src', 'speech', 'bin.ts'), ...args], { stdio: 'inherit' });
+  if (tsx.error) {
+    process.stdout.write(JSON.stringify({ error: { code: 'USAGE', message: 'startsimpli-speech needs a build (pnpm --filter @startsimpli/llm build) or tsx on PATH' } }) + '\n');
+    process.exit(2);
+  }
+  process.exit(tsx.status ?? 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -17,10 +17,14 @@
   "exports": {
     ".": "./src/index.ts",
     "./translation": "./src/translation/index.ts",
-    "./speech": "./src/speech/index.ts"
+    "./speech": "./src/speech/index.ts",
+    "./refine": "./src/refine/index.ts",
+    "./speech/voices": "./src/speech/voices/index.ts",
+    "./speech/captions": "./src/speech/captions/index.ts"
   },
   "files": [
     "src",
+    "bin",
     "README.md",
     "LICENSE"
   ],
@@ -29,7 +33,7 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@startsimpli/i18n": "^0.1.4"
+    "@startsimpli/i18n": "^0.1.3"
   },
   "devDependencies": {
     "@types/node": "^20.19.39",
@@ -37,6 +41,9 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },
+  "bin": {
+    "startsimpli-speech": "./bin/startsimpli-speech.js"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",