@startsimpli/llm 0.4.30 → 0.4.31

package/src/__tests__/refine.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ILLMProvider } from '../providers/interface';
+import type { GenerateOptions, LLMResponse } from '../types';
+import {
+  InvalidTriesError, RefineStepError, UnknownGateError, createGateRegistry, llmRefineStep, refineWithGates,
+} from '../refine';
+import type { RefineStep, StepInput } from '../refine';
+
+type Doc = { title: string; screens: number };
+
+/** Gates in the shape the anim loop has: a schema-ish one and a policy one. */
+const registry = () => {
+  const gates = createGateRegistry<Doc, { kind: string }>();
+  gates.register('title', (d) => (d.title.length > 3 ? ['title is too long'] : []));
+  gates.register('screens', (d) => (d.screens > 0 ? [`a skit expects no screens, found ${d.screens}`] : []));
+  return gates;
+};
+
+/** A step that answers call i with replies[i] (the last repeats) and records what it was handed. */
+const sequenced = (...replies: Array<Doc | Error | { result: Doc | null; errors?: string[]; costUsd?: number }>) => {
+  const calls: StepInput<Doc>[] = [];
+  const step: RefineStep<Doc> = async (input) => {
+    calls.push(structuredClone(input));
+    const r = replies[Math.min(calls.length - 1, replies.length - 1)];
+    if (r instanceof Error) throw r;
+    return 'title' in r ? { result: r, costUsd: 0.01, usage: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }, model: 'm' } : r;
+  };
+  return { step, calls };
+};
+const good: Doc = { title: 'Ok', screens: 0 };
+const withScreen: Doc = { title: 'Ok', screens: 2 };
+const run = (step: RefineStep<Doc>, tries: number | null, extra: Record<string, unknown> = {}) =>
+  refineWithGates<Doc, { kind: string }>({ step, gates: registry(), tries, context: { kind: 'skit' }, ...extra });
+
+describe('refineWithGates: the loop', () => {
+  it('a result that passes every gate costs exactly one step call', async () => {
+    const { step, calls } = sequenced(good);
+    const out = await run(step, 3);
+    expect(out.passed).toBe(true);
+    expect(calls).toHaveLength(1);
+    expect(out.attempts).toHaveLength(1);
+    expect(out.attempts[0]).toMatchObject({ n: 1, report: [], result: good, passed: true });
+  });
+
+  it('the step receives the previous result and the gates failures as data', async () => {
+    const { step, calls } = sequenced(withScreen, good);
+    const out = await run(step, 3);
+    expect(out.passed).toBe(true);
+    expect(calls[0]).toMatchObject({ n: 1, previous: null, failures: [] });
+    expect(calls[1].previous).toEqual(withScreen);
+    expect(calls[1].failures).toEqual([{ gate: 'screens', failures: ['a skit expects no screens, found 2'] }]);
+    expect(out.attempts[0].passed).toBe(false);
+  });
+
+  it('tries=N makes N calls at most and returns every attempt', async () => {
+    const { step, calls } = sequenced(withScreen);
+    const out = await run(step, 3);
+    expect(out.passed).toBe(false);
+    expect(calls).toHaveLength(3);
+    expect(out.attempts.map((a) => a.n)).toEqual([1, 2, 3]);
+    expect(out.result).toEqual(withScreen);
+    expect((await run(sequenced(withScreen, good).step, 1)).passed).toBe(false);
+  });
+
+  it('tries=null loops until every gate passes, with no hidden cap', async () => {
+    const { step, calls } = sequenced(...Array(25).fill(withScreen), good);
+    const out = await run(step, null);
+    expect(out.passed).toBe(true);
+    expect(calls).toHaveLength(26);
+  });
+
+  it('a bad tries value is refused, not clamped, before any call', async () => {
+    const { step, calls } = sequenced(good);
+    for (const bad of [0, -1, 1.5, true as any, 'x' as any, undefined as any]) await expect(run(step, bad)).rejects.toBeInstanceOf(InvalidTriesError);
+    expect(calls).toHaveLength(0);
+  });
+
+  it('every attempt carries {result, report, cost} and the outcome tallies usage', async () => {
+    const { step } = sequenced(withScreen, good);
+    const out = await run(step, 3);
+    expect(out.attempts[0].cost).toMatchObject({ usd: 0.01, promptTokens: 100, completionTokens: 50 });
+    expect(out.cost.usd).toBeCloseTo(0.02, 6);
+    expect(out.tally).toMatchObject({ calls: 2, promptTokens: 200, completionTokens: 100 });
+  });
+
+  it('a step that throws is surfaced with the attempts so far, not retried', async () => {
+    const boom = new Error('network down');
+    const { step, calls } = sequenced(withScreen, boom, good);
+    const error = await run(step, 5).catch((e) => e);
+    expect(error).toBeInstanceOf(RefineStepError);
+    expect(error.cause).toBe(boom);
+    expect(error.attempts).toHaveLength(1);
+    expect(error.n).toBe(2);
+    expect(calls).toHaveLength(2);
+  });
+
+  it('a reply the step rejected, or no result, is a failure under the rejected-gate name and the loop goes on', async () => {
+    const { step, calls } = sequenced({ result: null, errors: ['not json'] }, good);
+    const out = await run(step, 2);
+    expect(out.passed).toBe(true);
+    expect(out.attempts[0].report).toEqual([{ gate: 'step', failures: ['not json'] }]);
+    expect(calls[1]).toMatchObject({ previous: null, failures: [{ gate: 'step', failures: ['not json'] }] });
+    const named = await run(sequenced({ result: null }).step, 1, { rejectedGate: 'schema' });
+    expect(named.attempts[0].report[0]).toMatchObject({ gate: 'schema' });
+  });
+
+  it('calls a step made in one try (e.g. per-scene regeneration) are counted', async () => {
+    const out = await run(async () => ({ result: good, calls: 3 }), 1);
+    expect(out.attempts[0].calls).toBe(3);
+  });
+});
+
+describe('refineWithGates: gates', () => {
+  it('are registered by name; the context reaches them; a new one plugs in; a named subset runs', async () => {
+    const seen: string[] = [];
+    const gates = registry();
+    gates.register('ctx', (_d, ctx) => { seen.push(ctx.kind); return []; });
+    const out = await refineWithGates({ step: sequenced(withScreen).step, gates, tries: 1, context: { kind: 'skit' } });
+    expect(seen).toEqual(['skit']);
+    expect(out.attempts[0].report.map((r) => r.gate)).toEqual(['screens']);
+    const only = await refineWithGates({ step: sequenced(withScreen).step, gates, tries: 1, context: { kind: 'skit' }, only: ['title'] });
+    expect(only.passed).toBe(true);
+  });
+
+  it('an unknown gate name throws before any step call', async () => {
+    const { step, calls } = sequenced(good);
+    await expect(run(step, 1, { only: ['nope'] })).rejects.toBeInstanceOf(UnknownGateError);
+    expect(calls).toHaveLength(0);
+  });
+
+  it('opt-in gates are registered but run only when named', async () => {
+    const gates = registry();
+    gates.register('storyboard', () => ['nobody on stage'], { optIn: true });
+    expect(gates.defaultNames()).toEqual(['title', 'screens']);
+    const base = { step: sequenced(good).step, gates, tries: 1, context: { kind: 'k' } };
+    expect((await refineWithGates(base)).passed).toBe(true);
+    expect((await refineWithGates({ ...base, step: sequenced(good).step, only: ['storyboard'] })).passed).toBe(false);
+  });
+
+  it('informational lines never fail a gate and are kept on the attempt', async () => {
+    const gates = createGateRegistry<Doc>();
+    gates.register('lint', () => [{ text: 'unrealized data: screens', level: 'info' }, { text: 'note', level: 'info' }]);
+    const out = await refineWithGates({ step: sequenced(good).step, gates, tries: 2 });
+    expect(out.passed).toBe(true);
+    expect(out.attempts[0].notes).toEqual([{ gate: 'lint', text: 'unrealized data: screens' }, { gate: 'lint', text: 'note' }]);
+    gates.register('mixed', () => [{ text: 'fine', level: 'info' }, { text: 'broken', level: 'defect' }]);
+    const failed = await refineWithGates({ step: sequenced(good).step, gates, tries: 1 });
+    expect(failed.attempts[0].report).toEqual([{ gate: 'mixed', failures: ['broken'] }]);
+  });
+
+  it('async gates work, and replace=false refuses a duplicate name', async () => {
+    const gates = createGateRegistry<Doc>();
+    gates.register('slow', async () => ['late']);
+    expect(() => gates.register('slow', () => [], { replace: false })).toThrow(/already registered/);
+    const out = await refineWithGates({ step: sequenced(good).step, gates, tries: 1 });
+    expect(out.attempts[0].report).toEqual([{ gate: 'slow', failures: ['late'] }]);
+  });
+});
+
+describe('llmRefineStep: an injectable client', () => {
+  const provider = (answers: string[]) => {
+    const generate = vi.fn(async (_u: string, _s: string, _o?: GenerateOptions): Promise<LLMResponse> => ({
+      content: answers.shift() ?? '{}', model: 'fake', usage: { promptTokens: 10, completionTokens: 5, totalTokens: 15 },
+    }));
+    return { name: 'fake', availableModels: ['fake'], defaultModel: 'fake', generate, isAvailable: () => true } as ILLMProvider & { generate: typeof generate };
+  };
+  const validate = (json: any) => (typeof json?.title === 'string'
+    ? { valid: true as const, data: { title: json.title, screens: json.screens ?? 0 } }
+    : { valid: false as const, errors: ['title: expected string'] });
+
+  it('sends the brief, previous result and failures as data, and feeds a rejected reply back as a failure', async () => {
+    const p = provider(['not json', JSON.stringify({ title: 'Ok' })]);
+    const step = llmRefineStep<Doc>({ provider: p, systemPrompt: 'sys', brief: 'a skit', validate });
+    const out = await refineWithGates({ step, gates: createGateRegistry<Doc>(), tries: 3 });
+    expect(out.passed).toBe(true);
+    expect(out.attempts[0].report[0].gate).toBe('step');
+    expect(p.generate).toHaveBeenCalledTimes(2);
+    const first = JSON.parse(p.generate.mock.calls[0][0]);
+    const second = JSON.parse(p.generate.mock.calls[1][0]);
+    expect(first).toEqual({ brief: 'a skit' });
+    expect(second.brief).toBe('a skit');
+    expect(second.gate_failures[0].gate).toBe('step');
+    expect(out.attempts[1].cost).toMatchObject({ promptTokens: 10, completionTokens: 5 });
+  });
+
+  it('a provider that throws is surfaced as a step error', async () => {
+    const p = provider([]);
+    p.generate.mockRejectedValueOnce(new Error('401'));
+    const step = llmRefineStep<Doc>({ provider: p, systemPrompt: 's', brief: 'b', validate });
+    await expect(refineWithGates({ step, gates: createGateRegistry<Doc>(), tries: 3 })).rejects.toBeInstanceOf(RefineStepError);
+  });
+});

package/src/__tests__/speech-captions-cli.test.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import { runCli } from '../speech/cli';
+
+const golden: Array<{ fn: string; input: any; expected: any }> = JSON.parse(readFileSync(join(__dirname, 'fixtures', 'captions-golden.json'), 'utf8'));
+const run = (argv: string[], body: unknown) => runCli(argv, { readStdin: async () => JSON.stringify(body) });
+
+describe('startsimpli-speech captions', () => {
+  it.each(golden.map((g, n) => [n, g] as const).filter(([, g]) => g.fn === 'cues_for_beat' || (g.fn === 'cues_from_words' && g.input.words.length)))(
+    'json format equals the Python cues (case %i)', async (_n, g) => {
+      const i = g.input;
+      const words = i.words?.map(({ word, ...r }: any) => ({ text: word, ...r }));
+      const res = await run(['captions', '--format', 'json'], {
+        words, text: i.text, duration: i.duration, offset: i.offset, clauseBreaks: i.clause_breaks, maxWords: i.max_words, maxChars: i.max_chars, maxGap: i.max_gap,
+      });
+      expect(res.exitCode).toBe(0);
+      expect((res.output as any).cues).toEqual(g.expected);
+    });
+
+  it('srt and vtt return the file text; holdGap and fps are applied', async () => {
+    const body = { words: [{ text: 'a', start: 0, end: 1 }, { text: 'b', start: 1.2, end: 2 }], maxWords: 1, holdGapS: 0.5, fps: 10 };
+    const srt = await run(['captions', '--format', 'srt'], body);
+    expect(srt.exitCode).toBe(0);
+    expect((srt.output as any).content).toContain('00:00:00,000 --> 00:00:01,200');
+    expect((srt.output as any).frames).toEqual([[0, 12], [12, 20]]);
+    expect(((await run(['captions', '--format', 'vtt'], body)).output as any).content.startsWith('WEBVTT')).toBe(true);
+  });
+
+  it('usage errors exit 2; unusable words exit 1 with a named error', async () => {
+    expect((await run(['captions', '--format', 'pdf'], { text: 'x', duration: 1 })).exitCode).toBe(2);
+    expect((await run(['captions', '--format', 'json'], {})).exitCode).toBe(2);
+    const bad = await run(['captions', '--format', 'json'], { words: [{ text: 'a', start: 2, end: 1 }] });
+    expect(bad).toMatchObject({ exitCode: 1, output: { error: { code: 'INVALID_WORDS' } } });
+  });
+});

package/src/__tests__/speech-captions.test.ts

@@ -0,0 +1,136 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import {
+  InvalidWordsError, assertValidWords, captionTiming, cueFrameRange, cuesForBeat, cuesFromText, cuesFromWords,
+  holdGaps, splitWhitespaceTokens, toSrt, toVtt, wordsAreProportional,
+} from '../speech';
+import type { TranscriptWord } from '../speech';
+
+type Golden = { fn: string; input: any; expected: any };
+const golden: Golden[] = JSON.parse(readFileSync(join(__dirname, 'fixtures', 'captions-golden.json'), 'utf8'));
+
+/** The Python code names a word's text `word`. */
+const toWords = (ws: any[] | null | undefined): TranscriptWord[] | undefined =>
+  ws?.map(({ word, ...rest }) => ({ text: word, ...rest }));
+const camel = (o: Record<string, any>, drop: string[]) => ({
+  ...(o.max_words !== undefined && { maxWords: o.max_words }),
+  ...(o.max_chars !== undefined && { maxChars: o.max_chars }),
+  ...(o.max_gap !== undefined && { maxGap: o.max_gap }),
+  ...(o.clause_breaks !== undefined && { clauseBreaks: o.clause_breaks }),
+  ...(o.offset !== undefined && { offset: o.offset }),
+  ...Object.fromEntries(Object.entries(o).filter(([k]) => drop.includes(k))),
+});
+
+const replay: Record<string, (i: any) => unknown> = {
+  cues_from_words: (i) => cuesFromWords(toWords(i.words)!, camel(i, [])),
+  cues_from_text: (i) => cuesFromText(i.text, i.duration, camel(i, [])),
+  cues_for_beat: (i) => cuesForBeat(toWords(i.words), i.text, i.duration, camel(i, [])),
+  hold_gaps: (i) => holdGaps(i.cues, i.max_gap_s),
+  cue_frame_range: (i) => cueFrameRange(i.cue, i.fps),
+  words_are_proportional: (i) => wordsAreProportional(toWords(i.words)!.map((w, n) => ({ ...w, ...(i.flagged ? { alignment: i.flagged } : {}), ...(i.words[n].alignment ? { alignment: i.words[n].alignment } : {}) })), { stepMax: i.step_max, minWords: i.min_words }),
+  check_words: (i) => {
+    try { assertValidWords(toWords(i.words)!); return { ok: true }; } catch (e) {
+      if (!(e instanceof InvalidWordsError)) throw e;
+      return { error: e.message };
+    }
+  },
+};
+
+describe('captions: parity with the Python implementation (golden)', () => {
+  it('has golden cases', () => expect(golden.length).toBeGreaterThanOrEqual(35));
+  it.each(golden.map((g, n) => [`${n} ${g.fn}`, g] as const))('%s', (_n, g) => {
+    expect(replay[g.fn](g.input)).toEqual(g.expected);
+  });
+});
+
+const w = (text: string, step = 0.3): TranscriptWord[] => text.split(' ').map((t, i) => ({ text: t, start: i * step, end: i * step + 0.25 }));
+
+describe('captions: cue building', () => {
+  it('splits at a clause end with at least two tokens before the cut, never mid-clause when it can avoid it', () => {
+    const text = 'Today the frog will hop three feet to the right, and the elephant will watch.';
+    expect(cuesFromWords(w(text), { clauseBreaks: true }).map((c) => c.text))
+      .toEqual(['Today the frog will hop three feet', 'to the right,', 'and the elephant will watch.']);
+    expect(cuesFromWords(w('I watched. It was a very good three feet.'), { clauseBreaks: true }).map((c) => c.text))
+      .toEqual(['I watched.', 'It was a very good three feet.']);
+    // a single-token head is not a cut ("Hi, there ..." keeps the limit split)
+    expect(cuesFromWords(w('Hi, one two three four five six seven'), { clauseBreaks: true }).map((c) => c.text)[0]).toBe('Hi, one two three four five six');
+  });
+  it('holdGaps fills gaps up to the limit and never moves a start or mutates its input', () => {
+    const cues = [{ start: 0, end: 1, text: 'a' }, { start: 1.2, end: 2, text: 'b' }, { start: 3.5, end: 4, text: 'c' }];
+    expect(holdGaps(cues, 0.6).map((c) => c.end)).toEqual([1.2, 2, 4]);
+    expect(holdGaps(cues, 0)).toEqual(cues);
+    expect(cues[0].end).toBe(1);
+  });
+  it('cueFrameRange rounds half to even like Python', () => {
+    expect(cueFrameRange({ start: 1.25, end: 2.75, text: '' }, 10)).toEqual([12, 28]);
+  });
+});
+
+describe('captions: word checks', () => {
+  it('proportional detection: evenly spread characters yes, real vendor alignment no', () => {
+    const even = 'one two three four five six seven eight nine ten'.split(' ').map((t, i, a) => {
+      const start = a.slice(0, i).reduce((s, x) => s + 0.06 * x.length + 0.06, 0);
+      return { text: t, start, end: start + 0.06 * t.length };
+    });
+    expect(wordsAreProportional(even)).toBe(true);
+    const real = [[0, .31], [.35, .52], [.55, 1.1], [1.4, 1.5], [1.52, 2.4], [2.45, 2.6], [2.9, 3.0], [3.02, 3.9]].map(([s, e], i) => ({ text: `word${i}`, start: s, end: e }));
+    expect(wordsAreProportional(real)).toBe(false);
+  });
+  it('assertValidWords rejects empty and disordered transcripts with a named error', () => {
+    expect(() => assertValidWords([])).toThrow(InvalidWordsError);
+    expect(() => assertValidWords([{ text: 'a', start: 1, end: 0.5 }])).toThrow(/ends before it starts/);
+    expect(() => assertValidWords([{ text: 'a', start: 1, end: 2 }, { text: 'b', start: 0.5, end: 3 }])).toThrow(/not in time order/);
+    expect(assertValidWords(w('a b'))).toHaveLength(2);
+  });
+  it('splitWhitespaceTokens shares a multi-word token time evenly', () => {
+    expect(splitWhitespaceTokens([{ text: 'a b', start: 0, end: 1 }, { text: '  ', start: 1, end: 2 }])).toEqual([
+      { text: 'a', start: 0, end: 0.5 }, { text: 'b', start: 0.5, end: 1 },
+    ]);
+  });
+  it('captionTiming is not_measured for proportional words, else reports start errors', () => {
+    const real = [[0, .31], [.35, .52], [.55, 1.1], [1.4, 1.5], [1.52, 2.4], [2.45, 2.6], [2.9, 3.0], [3.02, 3.9]].map(([s, e], i) => ({ text: `w${i}`, start: s, end: e }));
+    const exact = captionTiming([{ start: 0, end: 1.1, text: 'w0 w1 w2' }], real);
+    expect(exact).toMatchObject({ measured: true, n: 1, pass: true, max_abs_start_err_ms: 0 });
+    expect(captionTiming([{ start: 0.5, end: 1.1, text: 'w0 w1 w2' }], real)).toMatchObject({ pass: false });
+  });
+});
+
+/** A strict reader for the two formats, independent of the writer. */
+function parseCues(text: string, kind: 'srt' | 'vtt') {
+  const stamp = kind === 'srt' ? /^(\d\d):([0-5]\d):([0-5]\d),(\d{3})$/ : /^(\d\d):([0-5]\d):([0-5]\d)\.(\d{3})$/;
+  const ms = (s: string) => { const m = stamp.exec(s); if (!m) throw new Error(`bad timestamp ${s}`); return ((+m[1] * 60 + +m[2]) * 60 + +m[3]) * 1000 + +m[4]; };
+  let body = text;
+  if (kind === 'vtt') { if (!body.startsWith('WEBVTT\n\n')) throw new Error('missing WEBVTT header'); body = body.slice(8); }
+  if (!body.endsWith('\n')) throw new Error('no trailing newline');
+  return body.trimEnd().split('\n\n').map((block, n) => {
+    const lines = block.split('\n');
+    let i = 0;
+    if (kind === 'srt') { if (lines[i++] !== String(n + 1)) throw new Error(`bad index in ${block}`); }
+    const [a, arrow, b] = lines[i++].split(' ');
+    if (arrow !== '-->') throw new Error(`bad timing line in ${block}`);
+    const start = ms(a); const end = ms(b);
+    if (end <= start) throw new Error('end before start');
+    const cueText = lines.slice(i).join('\n');
+    if (!cueText || cueText.includes('\n\n')) throw new Error('empty cue text');
+    return { start: start / 1000, end: end / 1000, text: cueText };
+  });
+}
+
+describe('captions: SRT and VTT output', () => {
+  const cues = [{ start: 0, end: 1.2345, text: 'Hello there,' }, { start: 3661.5, end: 3662, text: 'second --> cue' }, { start: 3662, end: 3662.0004, text: 'x' }];
+  it.each([['srt', toSrt], ['vtt', toVtt]] as const)('%s parses back to the same cues (millisecond precision)', (kind, write) => {
+    const back = parseCues(write(cues), kind);
+    expect(back).toHaveLength(2 + 1);
+    expect(back[0]).toEqual({ start: 0, end: 1.235, text: 'Hello there,' });
+    expect(back[1].start).toBe(3661.5);
+  });
+  it('formats carry the right separators and header', () => {
+    expect(toSrt(cues)).toContain('00:00:00,000 --> 00:00:01,235');
+    expect(toVtt(cues).startsWith('WEBVTT\n\n00:00:00.000 --> 00:00:01.235')).toBe(true);
+  });
+  it('an end that rounds to its start is lifted one millisecond so the cue stays valid', () => {
+    expect(parseCues(toSrt(cues), 'srt')[2]).toEqual({ start: 3662, end: 3662.001, text: 'x' });
+  });
+});

package/src/__tests__/speech-voices-cli.test.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import { defaultCastLibrary } from '../speech';
+import { runCli } from '../speech/cli';
+
+/** Produced by the Python resolver (blender-spike anim/voice/export_golden.py): the CLI must agree with it. */
+const golden: Array<{ name: string; request: any; expected: any }> = JSON.parse(
+  readFileSync(join(__dirname, 'fixtures', 'voices-golden.json'), 'utf8'),
+);
+
+const run = (argv: string[], stdin: string) => runCli(argv, { readStdin: async () => stdin });
+
+describe('startsimpli-speech voices resolve', () => {
+  it('has golden cases from the Python resolver', () => expect(golden.length).toBeGreaterThanOrEqual(15));
+
+  it.each(golden.map((g) => [g.name, g] as const))('golden: %s', async (_name, g) => {
+    const { libraryPatch, ...request } = g.request;
+    const body = { ...request, ...(libraryPatch ? { library: { ...defaultCastLibrary, ...libraryPatch } } : {}) };
+    const res = await run(['voices', 'resolve'], JSON.stringify(body));
+    if (g.expected.error) {
+      expect(res.exitCode).toBe(1);
+      // Python knows two kinds; TypeScript names more, all of them "not_resolvable" to Python.
+      const error = (res.output as any).error;
+      expect(error.message).toBe(g.expected.error.message);
+      if (g.expected.error.kind === 'unfilled') expect(error.kind).toBe('unfilled');
+      expect((res.output as any).warnings).toEqual(g.expected.warnings);
+    } else {
+      expect(res.exitCode).toBe(0);
+      expect(res.output).toEqual({ voices: g.expected.voices, warnings: g.expected.warnings });
+    }
+  });
+
+  it('flags override the request, and --in reads a file', async () => {
+    const res = await run(['voices', 'resolve', '--model', 'eleven_multilingual_v2', '--expiring', 'allow', '--today', '2027-01-01'], '{"cast":[{"id":"a","voice":"presenter"}]}');
+    expect((res.output as any).voices.a.model).toBe('eleven_multilingual_v2');
+  });
+
+  it('usage errors exit 2', async () => {
+    expect((await run(['voices'], '{}')).exitCode).toBe(2);
+    expect((await run(['voices', 'resolve'], '{}')).exitCode).toBe(2);
+    expect((await run(['voices', 'resolve', '--expiring', 'sometimes'], '{"cast":[]}')).exitCode).toBe(2);
+  });
+});

package/src/__tests__/speech-voices.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  DuplicateVoiceError, ExpiringVoiceError, RetiredVoiceError, UnfilledVoiceSlotError, UnknownLanguageError,
+  UnknownModelError, VoiceNotResolvableError, createCastVoices, defaultCastLibrary, directEmotion, stripTags,
+  validateCastLibrary,
+} from '../speech';
+
+const lib = () => structuredClone(defaultCastLibrary) as typeof defaultCastLibrary;
+const cast = (o: Record<string, unknown> = {}) => createCastVoices(lib(), { expiring: 'allow', ...o } as any);
+const ES = 'A'.repeat(20);
+const EXPIRING = 'cgSgspJ2msm6clMCkdW9';
+
+describe('voice cast library: resolution', () => {
+  it('a library id resolves to that entry; a real-looking voice id passes through; an unknown alias is ignored', () => {
+    const cv = cast();
+    expect(cv.resolve({ id: 'x', voice: 'manager' }).voiceId).toBe(lib().roles.manager.voice_id);
+    const passthrough = cv.resolve({ id: 'x', voice: 'AbCdEfGhIjKlMnOpQrSt' });
+    expect(passthrough).toMatchObject({ voiceId: 'AbCdEfGhIjKlMnOpQrSt', role: null, settings: {} });
+    expect(() => cv.resolve({ id: 'maya', voice: 'maya' })).toThrow(VoiceNotResolvableError);
+  });
+
+  it('members without a voice take default_pool in order, counting only voiceless members', () => {
+    const got = cast().resolveCast([{ id: 'a', voice: 'clone_1' }, { id: 'maya', voice: 'maya' }, { id: 'b' }]);
+    expect(got.a.role).toBe('clone_1');
+    expect(got.maya.role).toBe('presenter');
+    expect(got.b.role).toBe('engineer');
+  });
+
+  it('unfilled slot, retired id, unknown model and a shared voice each throw a named error', () => {
+    const cv = cast();
+    expect(() => cv.resolve({ id: 's', voice: 'open_slot_1' })).toThrow(UnfilledVoiceSlotError);
+    expect(() => cv.resolve({ id: 's', voice: 'open_slot_1' })).toThrow(/open_slot_1.*bspike-448/);
+    expect(() => cv.resolve({ id: 'x', voice: '21m00Tcm4TlvDq8ikWAM' })).toThrow(RetiredVoiceError);
+    expect(() => cv.resolve({ id: 'x', voice: 'presenter' }, { model: 'nope' })).toThrow(UnknownModelError);
+    expect(() => cv.resolveCast([{ id: 'a', voice: 'presenter' }, { id: 'b', voice: 'presenter' }])).toThrow(DuplicateVoiceError);
+    expect(() => cv.resolve({ id: 'z', voice: 'zz' }, {})).toThrow(/no voice reference/);
+  });
+
+  it('a per-language entry selects model and voice ids; no language is the unchanged path', () => {
+    const data = lib() as any;
+    data.languages.es = { model: 'eleven_multilingual_v2', rhubarb_recognizer: 'phonetic', roles: { presenter: { voice_id: ES } } };
+    const cv = createCastVoices(data, { expiring: 'allow' });
+    const base = cv.resolve({ id: 'm', voice: 'presenter' });
+    expect(cv.resolve({ id: 'm', voice: 'presenter' }, { language: 'en-GB' })).toEqual(base);
+    expect(base.language).toBeNull();
+    const es = cv.resolve({ id: 'm', voice: 'presenter' }, { language: 'es-MX' });
+    expect(es).toMatchObject({ voiceId: ES, model: 'eleven_multilingual_v2', language: 'es' });
+    expect(cv.resolve({ id: 'm', voice: 'engineer' }, { language: 'es' }).voiceId).toBe(lib().roles.engineer.voice_id);
+    expect(cv.resolve({ id: 'm', voice: 'presenter' }, { language: 'es', model: 'eleven_v3' }).model).toBe('eleven_v3');
+    expect(() => cv.resolve({ id: 'm', voice: 'presenter' }, { language: 'xx' })).toThrow(UnknownLanguageError);
+  });
+});
+
+describe('voice cast library: expiring Default voices (clock injected)', () => {
+  const member = { id: 'x', voice: EXPIRING };
+  it('warns before 2026-12-31 (once per voice) and errors from the deadline', () => {
+    const onWarn = vi.fn();
+    const cv = createCastVoices(lib(), { today: '2026-11-02', onWarn });
+    cv.resolve(member); cv.resolve(member);
+    expect(onWarn).toHaveBeenCalledTimes(1);
+    expect(onWarn.mock.calls[0][0]).toMatch(/Jessica.*expires 2026-12-31.*59 days left/);
+    expect(cv.warnings).toHaveLength(1);
+    expect(() => createCastVoices(lib(), { today: '2026-12-31' }).resolve(member)).toThrow(ExpiringVoiceError);
+  });
+  it('allow never complains; error always does; anything else is rejected', () => {
+    const onWarn = vi.fn();
+    createCastVoices(lib(), { today: '2027-06-01', expiring: 'allow', onWarn }).resolve(member);
+    expect(onWarn).not.toHaveBeenCalled();
+    expect(() => createCastVoices(lib(), { today: '2026-01-01', expiring: 'error' }).resolve(member)).toThrow(ExpiringVoiceError);
+    expect(() => createCastVoices(lib(), { expiring: 'sometimes' as any })).toThrow(/expiring must be/);
+  });
+});
+
+describe('voice cast library: emotion and tags', () => {
+  const spec = (model: string, role = 'presenter') => cast().resolve({ id: 'm', voice: role }, { model });
+  it('tag models get a prepended tag and untouched settings; the tag is not spoken text', () => {
+    const s = spec('eleven_v3');
+    const d = directEmotion(cast(), s, 'Hello there.', 'excited');
+    expect(d).toMatchObject({ textSent: '[excited] Hello there.', spokenText: 'Hello there.', settings: s.settings });
+  });
+  it('non-tag models get a clamped settings delta and no tag', () => {
+    const s = spec('eleven_multilingual_v2');
+    const d = directEmotion(cast(), s, 'Hello there.', 'excited');
+    expect(d.textSent).toBe('Hello there.');
+    expect(d.settings).toEqual({ stability: 0.25, similarity_boost: 0.75, style: 0.7, speed: 1.04 });
+  });
+  it('neutral, null and unknown emotions change nothing; a role can opt out; mode off/cli', () => {
+    const s = spec('eleven_v3');
+    for (const e of ['neutral', null, 'grumpy']) expect(directEmotion(cast(), s, 'Hi.', e)).toMatchObject({ textSent: 'Hi.', settings: s.settings });
+    expect(directEmotion(cast(), spec('eleven_v3', 'ai_assistant'), 'Hi.', 'excited').textSent).toBe('Hi.');
+    expect(directEmotion(cast(), s, 'Hi.', 'excited', 'off')).toMatchObject({ textSent: 'Hi.', cliEmotion: null });
+    expect(directEmotion(cast(), s, 'Hi.', 'excited', 'cli')).toMatchObject({ textSent: 'Hi.', cliEmotion: 'excited' });
+    expect(() => directEmotion(cast(), s, 'Hi.', 'excited', 'bogus' as any)).toThrow(/emotion mode/);
+  });
+  it('already-tagged text is not double tagged; stripTags collapses whitespace', () => {
+    const d = directEmotion(cast(), spec('eleven_v3'), '[laughs] Hello.', 'excited');
+    expect(d).toMatchObject({ textSent: '[laughs] Hello.', spokenText: 'Hello.' });
+    expect(stripTags('[a]  hi   [b] you ')).toBe('hi you');
+  });
+});
+
+describe('voice cast library: schema', () => {
+  it('the shipped library validates, holds no secret, and rejects a broken one', () => {
+    expect(() => validateCastLibrary(defaultCastLibrary)).not.toThrow();
+    expect(JSON.stringify(defaultCastLibrary)).not.toMatch(/sk_[0-9a-f]{20,}|xi-api-key/i);
+    expect(() => validateCastLibrary({ ...defaultCastLibrary, roles: undefined })).toThrow();
+  });
+});

package/src/index.ts

@@ -75,3 +75,6 @@ export type {
 export { registerLLMProvider, llmProviders } from './service';
 export { ProviderRegistry, pickProvider } from './providers/registry';
 export type { Selectable, ProviderFactory } from './providers/registry';
+
+// Refine-with-gates loop (also at `@startsimpli/llm/refine`)
+export * from './refine';

package/src/refine/errors.ts

@@ -0,0 +1,23 @@
+import type { RefineAttempt } from './types';
+
+export class InvalidTriesError extends RangeError {
+  constructor(tries: unknown) {
+    super(`tries must be an integer >= 1, or null to loop until the gates pass; got ${String(tries)}`);
+    this.name = 'InvalidTriesError';
+  }
+}
+
+export class UnknownGateError extends Error {
+  constructor(readonly missing: string[], registered: string[]) {
+    super(`unknown gate(s) ${JSON.stringify(missing)}; registered: ${JSON.stringify([...registered].sort())}`);
+    this.name = 'UnknownGateError';
+  }
+}
+
+/** The step threw. Not retried: `attempts` holds the tries completed before it, `n` the try that failed. */
+export class RefineStepError<T = unknown> extends Error {
+  constructor(readonly n: number, readonly attempts: RefineAttempt<T>[], readonly cause: unknown) {
+    super(`refine step failed on try ${n}: ${cause instanceof Error ? cause.message : String(cause)}`);
+    this.name = 'RefineStepError';
+  }
+}

package/src/refine/gates.ts

@@ -0,0 +1,55 @@
+import { UnknownGateError } from './errors';
+import type { RefineGate, GateFailure, GateNote } from './types';
+
+export interface RegisterOptions {
+  /** Default true: a second registration of a name replaces the first. false throws instead. */
+  replace?: boolean;
+  /** Registered, but run only when named (`only: [...]`). */
+  optIn?: boolean;
+}
+
+/** Gates by name. A module adds one by registering it; the loop runs them in registration order. */
+export interface GateRegistry<T, C = unknown> {
+  register(name: string, gate: RefineGate<T, C>, options?: RegisterOptions): void;
+  names(): string[];
+  /** Registered gates that run when none are named (opt-in ones left out). */
+  defaultNames(): string[];
+  /** Throws `UnknownGateError` for a name that is not registered; returns the names to run. */
+  select(only?: string[]): string[];
+  /** The gates that failed, plus the informational lines of all of them. */
+  run(result: T, context: C, only?: string[]): Promise<{ report: GateFailure[]; notes: GateNote[] }>;
+}
+
+export function createGateRegistry<T, C = unknown>(): GateRegistry<T, C> {
+  const gates = new Map<string, RefineGate<T, C>>();
+  const optIn = new Set<string>();
+  const registry: GateRegistry<T, C> = {
+    register(name, gate, options = {}) {
+      if (gates.has(name) && options.replace === false) throw new Error(`gate ${JSON.stringify(name)} is already registered`);
+      gates.set(name, gate);
+      if (options.optIn) optIn.add(name); else optIn.delete(name);
+    },
+    names: () => [...gates.keys()],
+    defaultNames: () => [...gates.keys()].filter((n) => !optIn.has(n)),
+    select(only) {
+      if (!only) return registry.defaultNames();
+      const missing = only.filter((n) => !gates.has(n));
+      if (missing.length) throw new UnknownGateError(missing, registry.names());
+      return [...only];
+    },
+    async run(result, context, only) {
+      const report: GateFailure[] = [];
+      const notes: GateNote[] = [];
+      for (const name of registry.select(only)) {
+        const failures: string[] = [];
+        for (const finding of await gates.get(name)!(result, context)) {
+          const { text, level } = typeof finding === 'string' ? { text: finding, level: 'defect' as const } : { text: finding.text, level: finding.level ?? 'defect' };
+          if (level === 'info') notes.push({ gate: name, text: String(text) }); else failures.push(String(text));
+        }
+        if (failures.length) report.push({ gate: name, failures });
+      }
+      return { report, notes };
+    },
+  };
+  return registry;
+}

package/src/refine/index.ts

@@ -0,0 +1,11 @@
+/** Refine-with-gates: a result is checked by named gates and the failures go back to a model step until they pass. */
+export { refineWithGates } from './refine';
+export type { RefineOptions, RefineOutcome } from './refine';
+export { createGateRegistry } from './gates';
+export type { GateRegistry, RegisterOptions } from './gates';
+export { llmRefineStep } from './llm-step';
+export type { LLMRefineStepOptions } from './llm-step';
+export { InvalidTriesError, RefineStepError, UnknownGateError } from './errors';
+export type {
+  RefineAttempt, RefineCost, RefineGate, GateFailure, GateFinding, GateNote, RefineStep, StepInput, StepOutput,
+} from './types';