@startsimpli/llm 0.4.29 → 0.4.31

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

@@ -0,0 +1,277 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { LLMProviderError } from '../errors';
+import {
+  ElevenLabsSpeechProvider, MockSpeechProvider, OpenAISpeechProvider, SpeechService,
+  createElevenLabsSpeechProvider, resetMockSpeechBehavior, setMockSpeechBehavior, wordsFromCharacters,
+} from '../speech';
+import type { ISpeechProvider, SynthesizeRequest } from '../speech';
+
+afterEach(() => { resetMockSpeechBehavior(); vi.unstubAllEnvs(); });
+
+const req: SynthesizeRequest = { text: 'hi you', voiceId: 'v1' };
+const AUDIO = new Uint8Array([9, 8, 7, 6]);
+const b64 = Buffer.from(AUDIO).toString('base64');
+
+/** ElevenLabs with-timestamps body for `hi you`. */
+const elevenBody = (text = 'hi you') => {
+  const chars = [...text];
+  return {
+    audio_base64: b64,
+    alignment: {
+      characters: chars,
+      character_start_times_seconds: chars.map((_, i) => i * 0.1),
+      character_end_times_seconds: chars.map((_, i) => (i + 1) * 0.1),
+    },
+  };
+};
+
+const respond = (body: unknown | Uint8Array, status = 200) =>
+  vi.fn(async (_u: unknown, _i?: RequestInit) =>
+    new Response(body instanceof Uint8Array ? body : typeof body === 'string' ? body : JSON.stringify(body), { status }));
+
+const wires: Array<{ name: string; make: (f: typeof fetch) => ISpeechProvider; ok: unknown; aligned: boolean; mime: string }> = [
+  { name: 'elevenlabs', make: (fetchImpl) => new ElevenLabsSpeechProvider({ apiKey: 'k', fetchImpl }), ok: elevenBody(), aligned: true, mime: 'audio/mpeg' },
+  { name: 'openai', make: (fetchImpl) => new OpenAISpeechProvider({ apiKey: 'k', fetchImpl }), ok: AUDIO, aligned: false, mime: 'audio/mpeg' },
+];
+
+describe.each(wires)('synthesize contract: $name', ({ name, make, ok, aligned, mime }) => {
+  it('advertises the capability', () => {
+    expect(make(fetch).capabilities.synthesize).toBe(true);
+  });
+
+  it('returns audio bytes, mime, provider, model and character usage', async () => {
+    const out = await make(respond(ok) as never).synthesize!(req);
+    expect([...out.audio]).toEqual([...AUDIO]);
+    expect(out.mimeType).toBe(mime);
+    expect(out).toMatchObject({ provider: name });
+    expect(out.model).toBeTruthy();
+    expect(out.usage.characters).toBe(req.text.length);
+  });
+
+  it(aligned ? 'returns ordered, non-overlapping word timings' : 'has no alignment (the vendor gives none)', async () => {
+    const out = await make(respond(ok) as never).synthesize!(req);
+    if (!aligned) { expect(out.words).toBeUndefined(); return; }
+    expect(out.words?.map((w) => w.text)).toEqual(['hi', 'you']);
+    const [a, b] = out.words!;
+    expect(a.end).toBeLessThanOrEqual(b.start);
+    expect(out.durationSec).toBeGreaterThan(0);
+  });
+
+  it.each([[401, 'AUTHENTICATION_ERROR', false], [429, 'RATE_LIMITED', true], [503, 'SERVICE_UNAVAILABLE', true], [400, 'INVALID_REQUEST', false]])(
+    'classifies HTTP %i as %s (retryable=%s)', async (status, code, retryable) => {
+      const err = await make(respond('boom', status as number) as never).synthesize!(req).catch((e) => e);
+      expect(err).toBeInstanceOf(LLMProviderError);
+      expect(err).toMatchObject({ code, retryable, provider: name });
+      expect(err.message).not.toMatch(/transcription/);
+    });
+
+  it('refuses empty text without calling the vendor', async () => {
+    const f = respond(ok);
+    await expect(make(f as never).synthesize!({ ...req, text: '   ' })).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+    expect(f).not.toHaveBeenCalled();
+  });
+
+  it('turns a network failure into a retryable error', async () => {
+    const f = vi.fn(async () => { throw new TypeError('fetch failed'); });
+    await expect(make(f as never).synthesize!(req)).rejects.toMatchObject({ retryable: true, code: 'SERVICE_UNAVAILABLE' });
+  });
+});
+
+describe('elevenlabs synthesize specifics', () => {
+  const run = async (patch: Partial<SynthesizeRequest> = {}, body: unknown = elevenBody()) => {
+    const f = respond(body);
+    const out = await new ElevenLabsSpeechProvider({ apiKey: 'sekret', fetchImpl: f as never }).synthesize({ ...req, ...patch });
+    const [url, init] = f.mock.calls[0] as unknown as [string, RequestInit];
+    return { out, url, init, sent: JSON.parse(init.body as string) };
+  };
+
+  it('posts to with-timestamps with the key header and voice in the path', async () => {
+    const { url, init } = await run();
+    expect(url).toBe('https://api.elevenlabs.io/v1/text-to-speech/v1/with-timestamps?output_format=mp3_44100_128');
+    expect((init.headers as Record<string, string>)['xi-api-key']).toBe('sekret');
+  });
+
+  it('takes the voice from the call, else ELEVENLABS_VOICE_ID, else refuses', async () => {
+    const p = createElevenLabsSpeechProvider({ ELEVENLABS_API_KEY: 'k', ELEVENLABS_VOICE_ID: 'envvoice' })!;
+    const f = respond(elevenBody());
+    (p as any).fetchImpl = f;
+    await p.synthesize({ text: 'hi you' });
+    expect((f.mock.calls[0] as unknown as [string])[0]).toContain('/text-to-speech/envvoice/with-timestamps');
+    const bare = new ElevenLabsSpeechProvider({ apiKey: 'k', fetchImpl: respond(elevenBody()) as never });
+    await expect(bare.synthesize({ text: 'hi' })).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+  });
+
+  it('maps outputFormat to the mime type', async () => {
+    expect((await run({ outputFormat: 'pcm_22050' })).out.mimeType).toBe('audio/pcm');
+    expect((await run({ outputFormat: 'pcm_22050' })).url).toContain('output_format=pcm_22050');
+  });
+
+  it('passes model, language and voiceSettings through', async () => {
+    const { sent } = await run({ model: 'eleven_v3', language: 'en', voiceSettings: { stability: 0.5, similarity_boost: 0.7 } });
+    expect(sent).toMatchObject({ text: 'hi you', model_id: 'eleven_v3', language_code: 'en', voice_settings: { stability: 0.5, similarity_boost: 0.7 } });
+  });
+
+  it('typed style speed/stability become voice_settings; explicit voiceSettings win', async () => {
+    const { sent } = await run({ style: { speed: 1.1, stability: 0.3 }, voiceSettings: { stability: 0.9 } });
+    expect(sent.voice_settings).toEqual({ speed: 1.1, stability: 0.9 });
+  });
+
+  it('style tags are prefixed on models that read them', async () => {
+    const { sent, out } = await run({ model: 'eleven_v3', style: { tags: ['excited', 'whispers'] } },
+      elevenBody('[excited][whispers] hi you'));
+    expect(sent.text).toBe('[excited][whispers] hi you');
+    expect(out.usage.characters).toBe('[excited][whispers] hi you'.length);
+  });
+
+  it('style tags are dropped on models that would speak them aloud', async () => {
+    const { sent } = await run({ model: 'eleven_multilingual_v2', style: { tags: ['excited'] } });
+    expect(sent.text).toBe('hi you');
+  });
+
+  it('audio tags are not words: stripped from the words, offsets kept, characters untouched', async () => {
+    const text = '[excited] hi you';
+    const { out } = await run({ model: 'eleven_v3', text }, elevenBody(text));
+    expect(out.words?.map((w) => w.text)).toEqual(['hi', 'you']);
+    expect(out.words![0].start).toBeCloseTo(1.0);      // "[excited] " is 10 chars at 0.1s
+    expect(out.characters?.length).toBe(text.length);
+  });
+
+  it('keepTags:true leaves tags in the words', async () => {
+    const text = '[excited] hi you';
+    const { out } = await run({ model: 'eleven_v3', text, keepTags: true }, elevenBody(text));
+    expect(out.words?.map((w) => w.text)).toEqual(['[excited]', 'hi', 'you']);
+  });
+
+  it('cost follows the model rate table (USD per 1k characters)', async () => {
+    const text = 'x'.repeat(1000);
+    expect((await run({ model: 'eleven_v3', text }, elevenBody(text))).out.usage.costUsd).toBeCloseTo(0.08);
+    expect((await run({ model: 'eleven_multilingual_v2', text }, elevenBody(text))).out.usage.costUsd).toBeCloseTo(0.08);
+    expect((await run({ model: 'eleven_flash_v2_5', text }, elevenBody(text))).out.usage.costUsd).toBeCloseTo(0.04);
+    expect((await run({ model: 'some_future_model', text }, elevenBody(text))).out.usage.costUsd).toBeCloseTo(0.10);
+  });
+
+  it('a response with no alignment still returns audio', async () => {
+    const { out } = await run({}, { audio_base64: b64 });
+    expect(out.words).toBeUndefined();
+    expect([...out.audio]).toEqual([...AUDIO]);
+  });
+
+  it('openai: posts the voice and format to /v1/audio/speech', async () => {
+    const f = respond(AUDIO);
+    await new OpenAISpeechProvider({ apiKey: 'k', fetchImpl: f as never }).synthesize({ text: 'hi' });
+    const [url, init] = f.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('https://api.openai.com/v1/audio/speech');
+    expect(JSON.parse(init.body as string)).toMatchObject({ input: 'hi', response_format: 'mp3' });
+  });
+});
+
+describe('wordsFromCharacters', () => {
+  it('splits on whitespace and skips bracket tags by default', () => {
+    const chars = [...'[calm] a b'].map((text, i) => ({ text, start: i, end: i + 1 }));
+    expect(wordsFromCharacters(chars).map((w) => [w.text, w.start])).toEqual([['a', 7], ['b', 9]]);
+    expect(wordsFromCharacters(chars, { keepTags: true }).map((w) => w.text)).toEqual(['[calm]', 'a', 'b']);
+  });
+  it('leaves an unclosed bracket as ordinary text', () => {
+    const chars = [...'a [b'].map((text, i) => ({ text, start: i, end: i + 1 }));
+    expect(wordsFromCharacters(chars).map((w) => w.text)).toEqual(['a', '[b']);
+  });
+});
+
+describe('real v3 alignment fixture', () => {
+  it('drops the [excited] tag from the words but keeps the true offsets', () => {
+    const fx = JSON.parse(readFileSync(join(__dirname, 'fixtures', 'eleven-v3-tagged-alignment.json'), 'utf8'));
+    const chars = fx.alignment.characters.map((text: string, i: number) => ({
+      text, start: fx.alignment.character_start_times_seconds[i], end: fx.alignment.character_end_times_seconds[i] }));
+    const words = wordsFromCharacters(chars);
+    expect(words[0].text).toBe('Most');
+    expect(words[0].start).toBeCloseTo(0.202, 2);   // the tag took the first ~0.2s
+    expect(wordsFromCharacters(chars, { keepTags: true })[0].text).toBe('[excited]');
+  });
+});
+
+describe('mock synthesize', () => {
+  it('is deterministic with aligned words and usage', async () => {
+    const out = await new MockSpeechProvider().synthesize(req);
+    expect(out.audio.byteLength).toBeGreaterThan(0);
+    expect(out.words?.map((w) => w.text)).toEqual(['hi', 'you']);
+    expect(out.usage.characters).toBe(6);
+    expect(out.provider).toBe('mock');
+  });
+  it('refuses empty text and simulates auth and outage failures', async () => {
+    const mock = new MockSpeechProvider();
+    await expect(mock.synthesize({ text: '' })).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+    setMockSpeechBehavior({ authError: true });
+    await expect(mock.synthesize(req)).rejects.toMatchObject({ code: 'AUTHENTICATION_ERROR', retryable: false });
+    setMockSpeechBehavior({ failTimes: 1 });
+    await expect(mock.synthesize(req)).rejects.toMatchObject({ code: 'SERVICE_UNAVAILABLE', retryable: true });
+  });
+});
+
+describe('SpeechService.synthesize', () => {
+  const fake = (name: string, impl: () => Promise<any>, synth = true): ISpeechProvider => ({
+    name, capabilities: { transcribe: true, synthesize: synth }, defaultModel: 'm', isAvailable: () => true,
+    transcribe: vi.fn() as never, synthesize: vi.fn(impl) as never,
+  });
+  const withProviders = (service: SpeechService, ...ps: ISpeechProvider[]) => {
+    (service as any).providers = new Map(ps.map((p) => [p.name, p]));
+    return service;
+  };
+  const ok = (provider: string) => async () => ({ audio: AUDIO, mimeType: 'audio/mpeg', model: 'm', provider, usage: { characters: 6 } });
+  const outage = async () => { throw new LLMProviderError('down', 'SERVICE_UNAVAILABLE', true, 503); };
+
+  it('only considers providers that can synthesize', async () => {
+    const s = withProviders(new SpeechService(), fake('elevenlabs', ok('elevenlabs'), false), fake('openai', ok('openai')));
+    expect((await s.synthesize(req)).provider).toBe('openai');
+    expect(s.getAvailableProviders('synthesize')).toEqual(['openai']);
+  });
+  it('picks the cheapest vendor that states a price, then falls back to the dearer one', async () => {
+    const priced = (name: string, price: number, impl: () => Promise<any>) => ({ ...fake(name, impl), costPer1kCharsUsd: () => price });
+    const s = withProviders(new SpeechService({ retryDelayMs: 1, maxRetries: 0 }),
+      priced('elevenlabs', 0.08, ok('elevenlabs')), priced('openai', 0.015, outage));
+    expect((await s.synthesize(req)).provider).toBe('elevenlabs'); // openai (cheapest) failed, fell through
+    const cheap = withProviders(new SpeechService(), priced('elevenlabs', 0.08, ok('elevenlabs')), priced('openai', 0.015, ok('openai')));
+    expect((await cheap.synthesize(req)).provider).toBe('openai');
+    const pinned = withProviders(new SpeechService({ preferredProvider: 'elevenlabs' }), priced('elevenlabs', 0.08, ok('elevenlabs')), priced('openai', 0.015, ok('openai')));
+    expect((await pinned.synthesize(req)).provider).toBe('elevenlabs');
+  });
+  it('a provider without a key is unavailable, not an error', () => {
+    const none = new OpenAISpeechProvider({ apiKey: '' });
+    expect(none.isAvailable()).toBe(false);
+    expect(withProviders(new SpeechService(), none).getAvailableProviders('synthesize')).toEqual([]);
+  });
+  it('retries a retryable failure, then falls through', async () => {
+    const primary = fake('elevenlabs', outage);
+    const s = withProviders(new SpeechService({ retryDelayMs: 1, maxRetries: 2 }), primary, fake('openai', ok('openai')));
+    expect((await s.synthesize(req)).provider).toBe('openai');
+    expect(primary.synthesize).toHaveBeenCalledTimes(3);
+  });
+  it('never retries an auth error', async () => {
+    const bad = fake('elevenlabs', async () => { throw new LLMProviderError('no', 'AUTHENTICATION_ERROR', false, 401); });
+    const s = withProviders(new SpeechService({ retryDelayMs: 1 }), bad, fake('openai', ok('openai')));
+    await s.synthesize(req);
+    expect(bad.synthesize).toHaveBeenCalledTimes(1);
+  });
+  it('does not fall through on the caller\'s bad input', async () => {
+    const bad = fake('elevenlabs', async () => { throw new LLMProviderError('bad', 'INVALID_REQUEST', false, 400); });
+    const next = fake('openai', ok('openai'));
+    await expect(withProviders(new SpeechService(), bad, next).synthesize(req)).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+    expect(next.synthesize).not.toHaveBeenCalled();
+  });
+  it('says what to set when nothing can synthesize', async () => {
+    await expect(withProviders(new SpeechService()).synthesize(req)).rejects.toThrow(/ELEVENLABS_API_KEY/);
+  });
+  it('SPEECH_PROVIDER=mock synthesizes, and survives a cleared outage', async () => {
+    vi.stubEnv('SPEECH_PROVIDER', 'mock');
+    setMockSpeechBehavior({ failTimes: 2 });
+    const out = await new SpeechService({ retryDelayMs: 1 }).synthesize(req);
+    expect(out.provider).toBe('mock');
+  });
+  it('transcribe is untouched by synthesize-only providers', async () => {
+    const synthOnly = { ...fake('elevenlabs', ok('elevenlabs')), capabilities: { transcribe: false, synthesize: true } } as ISpeechProvider;
+    const s = withProviders(new SpeechService(), synthOnly);
+    await expect(s.transcribe({ audio: AUDIO, mimeType: 'audio/mp4' })).rejects.toThrow(/No speech providers/);
+  });
+});

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';

package/src/refine/llm-step.ts

@@ -0,0 +1,35 @@
+import type { ILLMProvider } from '../providers/interface';
+import type { GenerateOptions } from '../types';
+import { extractJson } from '../utils/json-extraction';
+import type { ExtractValidation } from '../utils/extract-validate-correct';
+import type { RefineStep } from './types';
+
+export interface LLMRefineStepOptions<T> {
+  /** Any `ILLMProvider` (or a fake with `generate`): the injectable client. */
+  provider: Pick<ILLMProvider, 'generate'>;
+  systemPrompt: string;
+  /** The brief, sent on every try. */
+  brief: string;
+  /** Validates the parsed JSON; its errors become the step's rejections and go back to the model. */
+  validate: (json: unknown) => ExtractValidation<T>;
+  options?: GenerateOptions;
+}
+
+/**
+ * A `RefineStep` over one provider call: the user message is JSON `{brief, previous_result?, gate_failures?}`, so
+ * the model sees its previous result and what the gates said about it. An unreadable or invalid reply is returned as
+ * `errors` (a failure the loop feeds back); a provider error throws and ends the loop.
+ */
+export function llmRefineStep<T>(config: LLMRefineStepOptions<T>): RefineStep<T> {
+  return async ({ previous, failures }) => {
+    const payload: Record<string, unknown> = { brief: config.brief };
+    if (previous !== null) payload.previous_result = previous;
+    if (failures.length) payload.gate_failures = failures;
+    const response = await config.provider.generate(JSON.stringify(payload), config.systemPrompt, config.options);
+    const meta = { model: response.model, usage: response.usage };
+    const extracted = extractJson(response.content);
+    if (!extracted.success) return { result: null, errors: [extracted.error ?? 'No valid JSON object found in response'], ...meta };
+    const checked = config.validate(extracted.json);
+    return checked.valid ? { result: checked.data, ...meta } : { result: null, errors: checked.errors, ...meta };
+  };
+}

package/src/refine/refine.ts

@@ -0,0 +1,81 @@
+import { addUsage, newUsageTally, type UsageTally } from '../utils/usage-tally';
+import { InvalidTriesError, RefineStepError } from './errors';
+import type { GateRegistry } from './gates';
+import type { RefineAttempt, RefineCost, GateFailure, RefineStep } from './types';
+
+export interface RefineOptions<T, C = unknown> {
+  /** One model call per try (see `llmRefineStep`). Hand it the client you want; tests hand it a fake. */
+  step: RefineStep<T>;
+  gates: GateRegistry<T, C>;
+  /** An integer >= 1 is the number of step calls at most. `null` loops until every gate passes: nothing else caps it. */
+  tries: number | null;
+  /** Passed to every gate. */
+  context?: C;
+  /** Run only these gates (default: every registered gate except opt-in ones). Unknown names throw before any call. */
+  only?: string[];
+  /** RefineGate name under which the step's own rejections (`errors`, or no result) are reported. Default `step`. */
+  rejectedGate?: string;
+  /** Clock for `seconds`, injectable. Default `Date.now`. */
+  now?: () => number;
+}
+
+export interface RefineOutcome<T> {
+  /** The last result (the passing one when `passed`). */
+  result: T | null;
+  passed: boolean;
+  attempts: RefineAttempt<T>[];
+  /** Summed over every attempt. */
+  cost: RefineCost;
+  /** Per-model token usage over every attempt (the shared `UsageTally`). */
+  tally: UsageTally;
+}
+
+const zeroCost = (): RefineCost => ({ usd: 0, promptTokens: 0, completionTokens: 0, cachedTokens: 0 });
+const round6 = (n: number) => Math.round(n * 1e6) / 1e6;
+
+/**
+ * Prompt refinement: brief -> result -> gates -> the failures go back to the step -> a revised result.
+ * Each try is exactly one step call; the step gets the previous result and the gates' failures as data, so the
+ * model revises its own work instead of starting over. A step that throws ends the loop with `RefineStepError`.
+ * Every attempt's result, report and cost is returned.
+ */
+export async function refineWithGates<T, C = unknown>(options: RefineOptions<T, C>): Promise<RefineOutcome<T>> {
+  const { step, gates, tries, context = undefined as C, only, rejectedGate = 'step', now = Date.now } = options;
+  if (tries !== null && !(typeof tries === 'number' && Number.isInteger(tries) && tries >= 1)) throw new InvalidTriesError(tries);
+  const names = gates.select(only);
+
+  const attempts: RefineAttempt<T>[] = [];
+  const tally = newUsageTally();
+  const total = zeroCost();
+  let previous: T | null = null;
+  let failures: GateFailure[] = [];
+
+  for (let n = 1; tries === null || n <= tries; n += 1) {
+    const t0 = now();
+    let out;
+    try {
+      out = await step({ n, previous, failures });
+    } catch (error) {
+      throw new RefineStepError(n, attempts, error);
+    }
+    const errors = out.errors ?? [];
+    let report: GateFailure[];
+    let notes: RefineAttempt<T>['notes'] = [];
+    if (errors.length || out.result === null) {
+      report = [{ gate: rejectedGate, failures: errors.length ? errors : ['the reply could not be read as a result'] }];
+    } else {
+      ({ report, notes } = await gates.run(out.result, context, names));
+    }
+    const cost: RefineCost = {
+      usd: out.costUsd ?? 0, promptTokens: out.usage?.promptTokens ?? 0, completionTokens: out.usage?.completionTokens ?? 0, cachedTokens: out.usage?.cachedTokens ?? 0,
+    };
+    if (out.usage) addUsage(tally, { model: out.model, usage: out.usage });
+    total.usd = round6(total.usd + cost.usd);
+    total.promptTokens += cost.promptTokens; total.completionTokens += cost.completionTokens; total.cachedTokens += cost.cachedTokens;
+    attempts.push({ n, result: out.result, report, notes, cost, passed: report.length === 0, seconds: Math.round(((now() - t0) / 1000) * 1000) / 1000, calls: out.calls ?? 1 });
+    if (report.length === 0) return { result: out.result, passed: true, attempts, cost: total, tally };
+    previous = out.result;
+    failures = report;
+  }
+  return { result: attempts[attempts.length - 1]?.result ?? null, passed: false, attempts, cost: total, tally };
+}