@startsimpli/llm 0.4.30 → 0.4.31

package/README.md

@@ -244,6 +244,45 @@ registerSpeechProvider('mine', () => (process.env.MINE_KEY ? new MyProvider(proc
 <<<<<<< 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.30",
+  "version": "0.4.31",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -17,7 +17,10 @@
   "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",