@startsimpli/llm 0.4.25 → 0.4.27

package/README.md

@@ -177,3 +177,41 @@ Test suite ships **32 tests across 4 files**: `json-extraction.test.ts`, `mock-p
 ## Shared-first
 
 Per CLAUDE.md **rule 9**, LLM client wiring never belongs in app `src/`. If you find a `lib/openai.ts` or an `LLMService` clone inside an app (today: `raise-simpli/web-app/src/integrations/providers/openai/`), the right move is to delete it and import from `@startsimpli/llm`. Domain prompts and Zod schemas stay in the app; provider abstraction, retries, JSON extraction, and cost accounting stay here.
+
+
+## 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.
+
+```ts
+import { SpeechService } from '@startsimpli/llm/speech';
+
+const speech = new SpeechService();   // SPEECH_PROVIDER if set, else the cheapest vendor with a key
+const { text, words } = await speech.transcribe({
+  audio, mimeType: 'audio/webm', timestamps: 'word', hints: ['Crochets'],
+});
+```
+
+| Env | Provider | List price |
+| --- | --- | --- |
+| `GROQ_API_KEY` | Groq `whisper-large-v3-turbo` | $0.04 / audio hour |
+| `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 |
+| `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 | — |
+
+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.
+
+**Add a vendor** — implement `ISpeechProvider` (state `costPerMinuteUsd`) and register it, no
+service edit. An OpenAI-compatible host is a ten-line subclass of `OpenAISpeechProvider`
+(see `providers/groq.ts`):
+
+```ts
+registerSpeechProvider('mine', () => (process.env.MINE_KEY ? new MyProvider(process.env.MINE_KEY) : null));
+```
+
+`registerLLMProvider(name, factory)` does the same for text. Both sit on `ProviderRegistry`,
+so a new modality (TTS, embeddings) reuses it rather than hard-coding a provider list.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./translation": "./src/translation/index.ts"
+    "./translation": "./src/translation/index.ts",
+    "./speech": "./src/speech/index.ts"
   },
   "files": [
     "src",

package/src/__tests__/llm-service.test.ts

@@ -106,3 +106,19 @@ describe('LLMService', () => {
     })
   })
 })
+
+describe('registerLLMProvider', () => {
+  it('adds a text provider without editing LLMService', async () => {
+    const { registerLLMProvider, llmProviders, LLMService } = await import('../index');
+    registerLLMProvider('custom', () => ({
+      name: 'custom', availableModels: ['m'], defaultModel: 'm', isAvailable: () => true,
+      generate: async () => ({ content: 'hi', usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }, model: 'm', provider: 'custom' }),
+    }));
+    try {
+      const svc = new LLMService({ preferredProvider: 'custom' as never });
+      expect((await svc.chat('u', 's')).provider).toBe('custom');
+    } finally {
+      llmProviders.unregister('custom');
+    }
+  });
+});

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

@@ -0,0 +1,83 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ElevenLabsSpeechProvider, GroqSpeechProvider, OpenAISpeechProvider, SpeechService, createGroqSpeechProvider,
+} from '../speech';
+import type { ISpeechProvider, TranscribeRequest } from '../speech';
+
+const req: TranscribeRequest = { audio: new Uint8Array([1, 2, 3]), mimeType: 'audio/webm', hints: ['Crochets'] };
+const okJson = (body: unknown) => vi.fn(async () => new Response(JSON.stringify(body), { status: 200 }));
+
+describe('what each vendor costs per audio minute (USD, list price)', () => {
+  it('openai: the cheap default model, and the dearer ones priced as such', () => {
+    const p = new OpenAISpeechProvider({ apiKey: 'k' });
+    expect(p.defaultModel).toBe('gpt-4o-mini-transcribe');
+    expect(p.costPerMinuteUsd()).toBeCloseTo(0.003);
+    expect(p.costPerMinuteUsd('gpt-4o-transcribe')).toBeCloseTo(0.006);
+    expect(p.costPerMinuteUsd('whisper-1')).toBeCloseTo(0.006);
+  });
+  it('elevenlabs Scribe is $0.22/hour', () => {
+    expect(new ElevenLabsSpeechProvider({ apiKey: 'k' }).costPerMinuteUsd()).toBeCloseTo(0.22 / 60);
+  });
+  it('groq whisper-large-v3-turbo is $0.04/hour', () => {
+    expect(new GroqSpeechProvider({ apiKey: 'k' }).costPerMinuteUsd()).toBeCloseTo(0.04 / 60);
+  });
+});
+
+describe('groq provider (OpenAI-compatible endpoint)', () => {
+  it('is only built when GROQ_API_KEY is set', () => {
+    expect(createGroqSpeechProvider({})).toBeNull();
+    expect(createGroqSpeechProvider({ GROQ_API_KEY: 'g' })?.name).toBe('groq');
+  });
+  it('posts to Groq with its own default model and reports itself as groq', async () => {
+    const f = okJson({ text: ' hi ' });
+    const out = await new GroqSpeechProvider({ apiKey: 'g', fetchImpl: f as never }).transcribe(req);
+    const [url, init] = f.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('https://api.groq.com/openai/v1/audio/transcriptions');
+    expect((init.body as FormData).get('model')).toBe('whisper-large-v3-turbo');
+    expect(out).toMatchObject({ text: 'hi', provider: 'groq' });
+  });
+});
+
+describe('elevenlabs keyterms are a BILLED add-on, so they are opt-in', () => {
+  it('does not send keyterms by default', async () => {
+    const f = okJson({ text: 'x' });
+    await new ElevenLabsSpeechProvider({ apiKey: 'k', fetchImpl: f as never }).transcribe(req);
+    expect(((f.mock.calls[0] as unknown as [unknown, RequestInit])[1].body as FormData).getAll('keyterms')).toEqual([]);
+  });
+  it('sends them when asked', async () => {
+    const f = okJson({ text: 'x' });
+    await new ElevenLabsSpeechProvider({ apiKey: 'k', sendKeyterms: true, fetchImpl: f as never }).transcribe(req);
+    expect(((f.mock.calls[0] as unknown as [unknown, RequestInit])[1].body as FormData).getAll('keyterms')).toEqual(['Crochets']);
+  });
+});
+
+describe('SpeechService picks the cheapest available vendor unless told otherwise', () => {
+  const fake = (name: string, cost: number | undefined): ISpeechProvider => ({
+    name, capabilities: { transcribe: true }, defaultModel: 'm', isAvailable: () => true,
+    ...(cost === undefined ? {} : { costPerMinuteUsd: () => cost }),
+    transcribe: (async () => ({ text: name, model: 'm', provider: name, usage: {} })) as never,
+  });
+  const svc = (config: ConstructorParameters<typeof SpeechService>[0], ...ps: ISpeechProvider[]) => {
+    const s = new SpeechService(config);
+    (s as any).providers = new Map(ps.map((p) => [p.name, p]));
+    return s;
+  };
+  it('cheapest wins by default', async () => {
+    const s = svc({}, fake('pricey', 0.0067), fake('cheap', 0.0007), fake('mid', 0.003));
+    expect((await s.transcribe(req)).provider).toBe('cheap');
+  });
+  it('a provider with no stated price is tried last, not first', async () => {
+    const s = svc({}, fake('unknown', undefined), fake('mid', 0.003));
+    expect((await s.transcribe(req)).provider).toBe('mid');
+  });
+  it('an explicit preference beats price', async () => {
+    const s = svc({ preferredProvider: 'pricey' }, fake('pricey', 0.0067), fake('cheap', 0.0007));
+    expect((await s.transcribe(req)).provider).toBe('pricey');
+  });
+  it('falls through to the next-cheapest when the cheapest fails', async () => {
+    const down: ISpeechProvider = { ...fake('cheap', 0.0007), transcribe: (async () => { throw Object.assign(new Error('down'), { code: 'SERVICE_UNAVAILABLE', retryable: false }); }) as never };
+    const s = svc({ retryDelayMs: 1, maxRetries: 0 }, down, fake('mid', 0.003), fake('pricey', 0.0067));
+    expect((await s.transcribe(req)).provider).toBe('mid');
+  });
+});

package/src/__tests__/speech.test.ts

@@ -0,0 +1,203 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { LLMProviderError } from '../errors';
+import { ProviderRegistry } from '../providers/registry';
+import {
+  ElevenLabsSpeechProvider, MockSpeechProvider, OpenAISpeechProvider, SpeechService,
+  audioExtension, registerSpeechProvider, resetMockSpeechBehavior, setMockSpeechBehavior, speechProviders,
+} from '../speech';
+import type { ISpeechProvider, TranscribeRequest } from '../speech';
+
+const req: TranscribeRequest = { audio: new Uint8Array([1, 2, 3]), mimeType: 'audio/mp4' };
+afterEach(() => { resetMockSpeechBehavior(); vi.unstubAllEnvs(); });
+
+/** One fake wire per vendor — the CONTRACT below is what every provider must satisfy. */
+const wires: Array<{ name: string; make: (f: typeof fetch) => ISpeechProvider; ok: unknown; wordsOk: unknown }> = [
+  {
+    name: 'elevenlabs',
+    make: (fetchImpl) => new ElevenLabsSpeechProvider({ apiKey: 'k', fetchImpl }),
+    ok: { text: ' hello world ', language_code: 'en', words: [
+      { text: 'hello', start: 0, end: 0.4, type: 'word' }, { text: ' ', start: 0.4, end: 0.5, type: 'spacing' },
+      { text: 'world', start: 0.5, end: 1.2, type: 'word' } ] },
+    wordsOk: null,
+  },
+  {
+    name: 'openai',
+    make: (fetchImpl) => new OpenAISpeechProvider({ apiKey: 'k', fetchImpl }),
+    ok: { text: ' hello world ', language: 'en', duration: 1.2,
+      words: [{ word: 'hello', start: 0, end: 0.4 }, { word: 'world', start: 0.5, end: 1.2 }] },
+    wordsOk: null,
+  },
+];
+
+describe.each(wires)('provider contract: $name', ({ name, make, ok }) => {
+  const respond = (body: unknown, status = 200) =>
+    vi.fn(async (_u: unknown, _i: RequestInit) => new Response(typeof body === 'string' ? body : JSON.stringify(body), { status }));
+
+  it('is unavailable without a key and available with one', () => {
+    expect(make(fetch).isAvailable()).toBe(true);
+    const keyless = name === 'elevenlabs' ? new ElevenLabsSpeechProvider() : new OpenAISpeechProvider();
+    expect(keyless.isAvailable()).toBe(false);
+  });
+
+  it('returns trimmed text, provider name, model, and usage', async () => {
+    const out = await make(respond(ok) as never).transcribe!({ ...req, timestamps: 'word' });
+    expect(out).toMatchObject({ text: 'hello world', provider: name, language: 'en' });
+    expect(out.words?.map((w) => w.text)).toEqual(['hello', 'world']);
+    expect(out.usage.audioSeconds).toBeCloseTo(1.2);
+  });
+
+  it('names the upload for its container so the vendor can decode it', async () => {
+    const f = respond(ok);
+    await make(f as never).transcribe!({ ...req, mimeType: 'audio/webm;codecs=opus' });
+    const file = ((f.mock.calls[0][1] as RequestInit).body as FormData).get('file') as File;
+    expect(file.name).toBe('audio.webm');
+  });
+
+  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).transcribe!(req).catch((e) => e);
+      expect(err).toBeInstanceOf(LLMProviderError);
+      expect(err).toMatchObject({ code, retryable, provider: name });
+    });
+
+  it('refuses empty audio without calling the vendor', async () => {
+    const f = respond(ok);
+    await expect(make(f as never).transcribe!({ ...req, audio: new Uint8Array() })).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).transcribe!(req)).rejects.toMatchObject({ retryable: true, code: 'SERVICE_UNAVAILABLE' });
+  });
+});
+
+describe('vendor specifics', () => {
+  it('openai: word timings switch to whisper-1 verbose_json', async () => {
+    const f = vi.fn(async () => new Response(JSON.stringify({ text: 'x', words: [] }), { status: 200 }));
+    await new OpenAISpeechProvider({ apiKey: 'k', fetchImpl: f as never }).transcribe({ ...req, timestamps: 'word', hints: ['Crochets', 'Raise'] });
+    const form = ((f.mock.calls[0] as unknown as [unknown, RequestInit])[1].body as FormData);
+    expect(form.get('model')).toBe('whisper-1');
+    expect(form.get('response_format')).toBe('verbose_json');
+    expect(form.get('prompt')).toBe('Crochets, Raise');
+  });
+  it('elevenlabs: sends the key header and Scribe model', async () => {
+    const f = vi.fn(async () => new Response(JSON.stringify({ text: 'x' }), { status: 200 }));
+    await new ElevenLabsSpeechProvider({ apiKey: 'sekret', fetchImpl: f as never }).transcribe(req);
+    const [url, init] = f.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('https://api.elevenlabs.io/v1/speech-to-text');
+    expect((init.headers as Record<string, string>)['xi-api-key']).toBe('sekret');
+    expect((init.body as FormData).get('model_id')).toBe('scribe_v1');
+  });
+  it('openai: a hint list handed back on silence is reported as no speech', async () => {
+    const f = vi.fn(async () => new Response(JSON.stringify({ text: 'Vault, Tandem, Foundry, Raise, Crochets' }), { status: 200 }));
+    const out = await new OpenAISpeechProvider({ apiKey: 'k', fetchImpl: f as never })
+      .transcribe({ ...req, hints: ['Crochets', 'Raise', 'Foundry', 'Tandem', 'Vault'] });
+    expect(out.text).toBe('');
+  });
+  it('openai: a scaffold word like "context:" on silence is no speech', async () => {
+    const f = vi.fn(async () => new Response(JSON.stringify({ text: 'context:' }), { status: 200 }));
+    const out = await new OpenAISpeechProvider({ apiKey: 'k', fetchImpl: f as never }).transcribe({ ...req, hints: ['Crochets'] });
+    expect(out.text).toBe('');
+  });
+  it('openai: real speech that merely mentions a hint is kept', async () => {
+    const f = vi.fn(async () => new Response(JSON.stringify({ text: 'Fix the Raise deck' }), { status: 200 }));
+    const out = await new OpenAISpeechProvider({ apiKey: 'k', fetchImpl: f as never }).transcribe({ ...req, hints: ['Raise'] });
+    expect(out.text).toBe('Fix the Raise deck');
+  });
+  it('audioExtension covers the Safari/Chrome split', () => {
+    expect(audioExtension('audio/mp4')).toBe('mp4');
+    expect(audioExtension('audio/webm;codecs=opus')).toBe('webm');
+  });
+});
+
+describe('SpeechService', () => {
+  const fake = (name: string, impl: () => Promise<any>): ISpeechProvider => ({
+    name, capabilities: { transcribe: true }, defaultModel: 'm', isAvailable: () => true,
+    transcribe: 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 okResult = (provider: string) => async () => ({ text: provider, model: 'm', provider, usage: {} });
+  const outage = async () => { throw new LLMProviderError('down', 'SERVICE_UNAVAILABLE', true, 503); };
+
+  it('prefers the configured provider', async () => {
+    const s = withProviders(new SpeechService({ preferredProvider: 'openai' }), fake('elevenlabs', okResult('elevenlabs')), fake('openai', okResult('openai')));
+    expect((await s.transcribe(req)).provider).toBe('openai');
+  });
+  it('with nothing preferred it uses what has a key (order = price, then registration)', async () => {
+    const s = withProviders(new SpeechService(), fake('elevenlabs', okResult('elevenlabs')), fake('openai', okResult('openai')));
+    expect((await s.transcribe(req)).provider).toBe('elevenlabs');
+    const only = withProviders(new SpeechService(), fake('openai', okResult('openai')));
+    expect((await only.transcribe(req)).provider).toBe('openai');
+  });
+  it('retries a retryable failure, then falls through to the next vendor', async () => {
+    const primary = fake('elevenlabs', outage);
+    const s = withProviders(new SpeechService({ retryDelayMs: 1, maxRetries: 2 }), primary, fake('openai', okResult('openai')));
+    expect((await s.transcribe(req)).provider).toBe('openai');
+    expect(primary.transcribe).toHaveBeenCalledTimes(3);
+  });
+  it('does not fall through on the caller\'s own bad input', async () => {
+    const bad = fake('elevenlabs', async () => { throw new LLMProviderError('bad audio', 'INVALID_REQUEST', false, 400); });
+    const next = fake('openai', okResult('openai'));
+    const s = withProviders(new SpeechService(), bad, next);
+    await expect(s.transcribe(req)).rejects.toMatchObject({ code: 'INVALID_REQUEST' });
+    expect(next.transcribe).not.toHaveBeenCalled();
+  });
+  it('fallback:false stays on one vendor', async () => {
+    const s = withProviders(new SpeechService({ fallback: false, retryDelayMs: 1, maxRetries: 0 }), fake('elevenlabs', outage), fake('openai', okResult('openai')));
+    await expect(s.transcribe(req)).rejects.toBeInstanceOf(LLMProviderError);
+  });
+  it('says what to set when nothing is configured', async () => {
+    const s = withProviders(new SpeechService());
+    await expect(s.transcribe(req)).rejects.toThrow(/GROQ_API_KEY, OPENAI_API_KEY or ELEVENLABS_API_KEY/);
+    expect(s.isAvailable()).toBe(false);
+  });
+  it('SPEECH_LANGUAGE is a default, and a per-call language wins', async () => {
+    vi.stubEnv('SPEECH_LANGUAGE', 'en');
+    const seen: Array<string | undefined> = [];
+    const spy: ISpeechProvider = { name: 'elevenlabs', capabilities: { transcribe: true }, defaultModel: 'm', isAvailable: () => true,
+      transcribe: (async (r: TranscribeRequest) => { seen.push(r.language); return { text: 'x', model: 'm', provider: 'elevenlabs', usage: {} }; }) as never };
+    const s = withProviders(new SpeechService(), spy);
+    await s.transcribe(req);
+    await s.transcribe({ ...req, language: 'fr' });
+    expect(seen).toEqual(['en', 'fr']);
+  });
+  it('SPEECH_PROVIDER=mock selects the deterministic provider', async () => {
+    vi.stubEnv('SPEECH_PROVIDER', 'mock');
+    setMockSpeechBehavior({ text: 'hi there' });
+    expect((await new SpeechService().transcribe(req)).text).toBe('hi there');
+  });
+  it('mock can simulate an outage that clears', async () => {
+    vi.stubEnv('SPEECH_PROVIDER', 'mock');
+    setMockSpeechBehavior({ failTimes: 2 });
+    expect((await new SpeechService({ retryDelayMs: 1 }).transcribe(req)).provider).toBe('mock');
+  });
+});
+
+describe('plugging in a new vendor', () => {
+  it('is one register call — no service edit', async () => {
+    class Whisperish implements ISpeechProvider {
+      name = 'selfhosted'; capabilities = { transcribe: true }; defaultModel = 'w';
+      isAvailable() { return true; }
+      async transcribe() { return { text: 'from my box', model: 'w', provider: 'selfhosted', usage: {} }; }
+    }
+    registerSpeechProvider('selfhosted', () => new Whisperish());
+    try {
+      const out = await new SpeechService({ preferredProvider: 'selfhosted' }).transcribe(req);
+      expect(out.text).toBe('from my box');
+    } finally {
+      speechProviders.unregister('selfhosted');
+    }
+  });
+});
+
+describe('ProviderRegistry', () => {
+  it('drops factories whose credentials are absent', () => {
+    const r = new ProviderRegistry<MockSpeechProvider>().register('a', () => new MockSpeechProvider()).register('b', () => null);
+    expect([...r.instantiate().keys()]).toEqual(['a']);
+  });
+});

package/src/index.ts

@@ -71,3 +71,7 @@ export type {
   AgentTurnResult,
   RunAgentOptions,
 } from './agent/types';
+
+export { registerLLMProvider, llmProviders } from './service';
+export { ProviderRegistry, pickProvider } from './providers/registry';
+export type { Selectable, ProviderFactory } from './providers/registry';

package/src/providers/registry.ts

@@ -0,0 +1,59 @@
+/**
+ * One provider registry for every modality (text, speech, and whatever comes next).
+ *
+ * WHY THIS EXISTS. `LLMService` used to hard-code its providers in a private
+ * method, so adding one meant editing the service. Speech needed the same shape
+ * and would have copied that method. Now a modality owns a registry of
+ * name -> factory, built-ins register themselves, and a new provider — in this
+ * package or in an app — is a single `register(...)` call with no service edit.
+ *
+ * A factory returns `null` when its credentials are absent, which is how
+ * `createOpenAIProvider()` already behaved; the registry just formalises it.
+ */
+export interface Selectable {
+  readonly name: string;
+  isAvailable(): boolean;
+}
+
+export type ProviderFactory<P extends Selectable> = () => P | null;
+
+export class ProviderRegistry<P extends Selectable> {
+  private readonly factories = new Map<string, ProviderFactory<P>>();
+
+  /** Register (or replace) a provider by name. Later registrations win. */
+  register(name: string, factory: ProviderFactory<P>): this {
+    this.factories.set(name, factory);
+    return this;
+  }
+
+  unregister(name: string): boolean {
+    return this.factories.delete(name);
+  }
+
+  names(): string[] {
+    return [...this.factories.keys()];
+  }
+
+  /** Build every registered provider that its own environment allows. */
+  instantiate(): Map<string, P> {
+    const out = new Map<string, P>();
+    for (const [name, factory] of this.factories) {
+      const provider = factory();
+      if (provider) out.set(name, provider);
+    }
+    return out;
+  }
+}
+
+/** The preferred provider if it is usable, otherwise the first one that is. */
+export function pickProvider<P extends Selectable>(
+  providers: Map<string, P>,
+  preferred?: string,
+): P | undefined {
+  const first = preferred ? providers.get(preferred) : undefined;
+  if (first?.isAvailable()) return first;
+  for (const provider of providers.values()) {
+    if (provider.isAvailable()) return provider;
+  }
+  return undefined;
+}

package/src/service.ts

@@ -26,6 +26,20 @@ import {
 import { OpenAIProvider, createOpenAIProvider } from './providers/openai';
 import { AnthropicProvider, createAnthropicProvider } from './providers/anthropic';
 import { MockLLMProvider } from './providers/mock';
+import { ProviderRegistry, pickProvider } from './providers/registry';
+
+/**
+ * The text-provider registry. Built-ins register below; anything else —
+ * a self-hosted model, a new vendor — is `registerLLMProvider(name, factory)`
+ * and needs no change to `LLMService`.
+ */
+export const llmProviders = new ProviderRegistry<ILLMProvider>()
+  .register('openai', () => createOpenAIProvider())
+  .register('anthropic', () => createAnthropicProvider());
+
+export function registerLLMProvider(name: string, factory: () => ILLMProvider | null): void {
+  llmProviders.register(name, factory);
+}
 
 /**
  * Metadata about a generation attempt (tokens, model, retries).
@@ -83,22 +97,14 @@ export class LLMService<TOutput> {
       return;
     }
 
-    const openai = createOpenAIProvider();
-    if (openai) this.providers.set('openai', openai);
-
-    const anthropic = createAnthropicProvider();
-    if (anthropic) this.providers.set('anthropic', anthropic);
+    for (const [name, provider] of llmProviders.instantiate()) {
+      this.providers.set(name, provider);
+    }
   }
 
   private getProvider(): ILLMProvider {
-    // Try preferred first
-    const preferred = this.providers.get(this.config.preferredProvider);
-    if (preferred?.isAvailable()) return preferred;
-
-    // Fallback to any available
-    for (const provider of this.providers.values()) {
-      if (provider.isAvailable()) return provider;
-    }
+    const picked = pickProvider(this.providers, this.config.preferredProvider);
+    if (picked) return picked;
 
     throw new LLMProviderError(
       'No LLM providers available. Please configure OPENAI_API_KEY or ANTHROPIC_API_KEY.',

package/src/speech/http.ts

@@ -0,0 +1,73 @@
+import { LLMProviderError } from '../errors';
+import type { LLMErrorCode } from '../errors';
+import type { TranscribeRequest } from './types';
+
+/** Container extension a vendor can recognise, from the recorder's MIME type. */
+const EXTENSIONS: Record<string, string> = {
+  'audio/webm': 'webm', 'video/webm': 'webm', 'audio/ogg': 'ogg', 'audio/mp4': 'mp4',
+  'audio/x-m4a': 'm4a', 'audio/m4a': 'm4a', 'audio/mpeg': 'mp3', 'audio/mp3': 'mp3',
+  'audio/wav': 'wav', 'audio/x-wav': 'wav', 'audio/flac': 'flac',
+};
+
+/**
+ * THE FILE NAME MATTERS. Vendors infer the container from it, and browsers
+ * disagree: Chrome/Firefox record webm/ogg, Safari records mp4. A webm blob
+ * uploaded as `.mp4` is rejected as unsupported, so the name comes from the
+ * MIME type, never a constant.
+ */
+export function audioExtension(mimeType: string): string {
+  const base = (mimeType || '').split(';')[0].trim().toLowerCase();
+  return EXTENSIONS[base] ?? 'webm';
+}
+
+export function audioBlob(request: Pick<TranscribeRequest, 'audio' | 'mimeType'>): { blob: Blob; filename: string } {
+  const base = (request.mimeType || 'audio/webm').split(';')[0].trim() || 'audio/webm';
+  return {
+    blob: new Blob([new Uint8Array(request.audio)], { type: base }),
+    filename: `audio.${audioExtension(request.mimeType)}`,
+  };
+}
+
+export function assertAudio(request: Pick<TranscribeRequest, 'audio'>, provider: string): void {
+  if (!request.audio?.byteLength) {
+    throw new LLMProviderError('There is no audio to transcribe.', 'INVALID_REQUEST', false, undefined, provider);
+  }
+}
+
+/** One HTTP-status -> error-code mapping, so every vendor classifies failures the same way. */
+export function speechHttpError(status: number, body: string, provider: string): LLMProviderError {
+  const code: LLMErrorCode =
+    status === 401 || status === 403 ? 'AUTHENTICATION_ERROR'
+    : status === 429 ? 'RATE_LIMITED'
+    : status === 408 || status === 504 ? 'TIMEOUT'
+    : status >= 500 ? 'SERVICE_UNAVAILABLE'
+    : status === 400 || status === 413 || status === 415 || status === 422 ? 'INVALID_REQUEST'
+    : 'UNKNOWN_ERROR';
+  const retryable = code === 'RATE_LIMITED' || code === 'SERVICE_UNAVAILABLE' || code === 'TIMEOUT';
+  return new LLMProviderError(
+    `${provider} transcription failed (${status}): ${body.slice(0, 300)}`,
+    code, retryable, status, provider,
+  );
+}
+
+/** fetch with a deadline; a timeout or network drop becomes a typed, retryable error. */
+export async function speechFetch(
+  provider: string,
+  url: string,
+  init: RequestInit,
+  timeoutMs = 240_000,
+  fetchImpl: typeof fetch = fetch,
+): Promise<Response> {
+  try {
+    const response = await fetchImpl(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+    if (!response.ok) throw speechHttpError(response.status, await response.text().catch(() => ''), provider);
+    return response;
+  } catch (error) {
+    if (error instanceof LLMProviderError) throw error;
+    const timedOut = error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError');
+    throw new LLMProviderError(
+      timedOut ? `${provider} did not answer within ${Math.round(timeoutMs / 1000)}s.` : `${provider} request failed: ${(error as Error)?.message ?? error}`,
+      timedOut ? 'TIMEOUT' : 'SERVICE_UNAVAILABLE', true, undefined, provider,
+    );
+  }
+}

package/src/speech/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `@startsimpli/llm/speech` — pluggable speech-to-text.
+ *
+ *   const speech = new SpeechService();            // SPEECH_PROVIDER, else the cheapest vendor with a key
+ *   const { text } = await speech.transcribe({ audio, mimeType: 'audio/webm' });
+ *
+ * A new vendor: implement `ISpeechProvider`, then `registerSpeechProvider(name, factory)`.
+ */
+export { SpeechService, registerSpeechProvider, speechProviders } from './service';
+export type { ISpeechProvider } from './interface';
+export type {
+  SpeechServiceConfig, SpeechUsage, TranscribeRequest, TranscriptResult, TranscriptWord,
+} from './types';
+export { ElevenLabsSpeechProvider, createElevenLabsSpeechProvider } from './providers/elevenlabs';
+export { OpenAISpeechProvider, createOpenAISpeechProvider } from './providers/openai';
+export type { OpenAISpeechOptions } from './providers/openai';
+export { GroqSpeechProvider, createGroqSpeechProvider } from './providers/groq';
+export { MockSpeechProvider, setMockSpeechBehavior, resetMockSpeechBehavior } from './providers/mock';
+export { audioExtension, speechHttpError } from './http';

package/src/speech/interface.ts

@@ -0,0 +1,25 @@
+import type { Selectable } from '../providers/registry';
+import type { TranscribeRequest, TranscriptResult } from './types';
+
+/**
+ * What a speech vendor implements. A provider supports whichever directions its
+ * API does — `capabilities` says which, so a caller (or the service) never has
+ * to call a method and catch "not supported".
+ *
+ * ADDING A VENDOR: implement this, then
+ * `registerSpeechProvider('name', () => new Mine(process.env.MINE_KEY) )` — no
+ * edit to `SpeechService`. Text-to-speech joins here as an optional
+ * `synthesize` alongside `transcribe` (bd startsim-2lnyg); nothing in the
+ * service needs to change for it either.
+ */
+export interface ISpeechProvider extends Selectable {
+  readonly capabilities: { transcribe: boolean };
+  readonly defaultModel: string;
+  /**
+   * List price per audio minute, USD, for `model` (default model when omitted).
+   * `SpeechService` uses it to prefer the cheapest available vendor. A provider
+   * that does not state a price is tried after every provider that does.
+   */
+  costPerMinuteUsd?(model?: string): number;
+  transcribe?(request: TranscribeRequest): Promise<TranscriptResult>;
+}

package/src/speech/providers/elevenlabs.ts

@@ -0,0 +1,85 @@
+/**
+ * ElevenLabs Scribe speech-to-text. https://elevenlabs.io/docs/api-reference/speech-to-text
+ * Env: ELEVENLABS_API_KEY.
+ */
+import type { ISpeechProvider } from '../interface';
+import { assertAudio, audioBlob, speechFetch } from '../http';
+import type { TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
+
+export interface ElevenLabsOptions {
+  /**
+   * Send `hints` as Scribe `keyterms`. OFF by default: keyterm prompting is a
+   * separately BILLED add-on (~+$0.07/hour on top of $0.22), and plain Scribe
+   * transcribed our project names correctly in the benchmark.
+   */
+  sendKeyterms?: boolean;
+  apiKey?: string;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+}
+
+interface ScribeWord { text: string; start?: number; end?: number; type?: string; speaker_id?: string }
+
+export class ElevenLabsSpeechProvider implements ISpeechProvider {
+  readonly name = 'elevenlabs';
+  readonly capabilities = { transcribe: true };
+  readonly defaultModel = 'scribe_v1';
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly fetchImpl?: typeof fetch;
+  private readonly sendKeyterms: boolean;
+
+  constructor(options: ElevenLabsOptions = {}) {
+    this.sendKeyterms = options.sendKeyterms ?? false;
+    this.apiKey = options.apiKey ?? '';
+    this.baseUrl = (options.baseUrl ?? 'https://api.elevenlabs.io').replace(/\/+$/, '');
+    this.fetchImpl = options.fetchImpl;
+  }
+
+  isAvailable(): boolean {
+    return Boolean(this.apiKey);
+  }
+
+  /** Scribe list price: $0.22 per audio hour. */
+  costPerMinuteUsd(): number {
+    return 0.22 / 60;
+  }
+
+  async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
+    assertAudio(request, this.name);
+    const model = request.model ?? this.defaultModel;
+    const { blob, filename } = audioBlob(request);
+    const form = new FormData();
+    form.append('file', blob, filename);
+    form.append('model_id', model);
+    form.append('timestamps_granularity', request.timestamps === 'none' ? 'none' : 'word');
+    if (request.language) form.append('language_code', request.language);
+    if (request.diarize) form.append('diarize', 'true');
+    // Scribe has no free-text prompt; `keyterms` is its (billed) bias list.
+    if (this.sendKeyterms) for (const term of request.hints ?? []) form.append('keyterms', term);
+
+    const response = await speechFetch(
+      this.name, `${this.baseUrl}/v1/speech-to-text`,
+      { method: 'POST', headers: { 'xi-api-key': this.apiKey }, body: form },
+      request.timeoutMs, this.fetchImpl,
+    );
+    const json = (await response.json()) as { text?: string; language_code?: string; words?: ScribeWord[] };
+    const words: TranscriptWord[] | undefined = json.words
+      ?.filter((w) => (w.type ?? 'word') === 'word' && typeof w.start === 'number' && typeof w.end === 'number')
+      .map((w) => ({ text: w.text, start: w.start as number, end: w.end as number, ...(w.speaker_id ? { speaker: w.speaker_id } : {}) }));
+    const audioSeconds = words?.length ? words[words.length - 1].end : undefined;
+    return {
+      text: (json.text ?? '').trim(),
+      ...(json.language_code ? { language: json.language_code } : {}),
+      ...(words?.length ? { words } : {}),
+      model, provider: this.name,
+      usage: audioSeconds !== undefined ? { audioSeconds } : {},
+    };
+  }
+}
+
+export function createElevenLabsSpeechProvider(
+  env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {},
+): ElevenLabsSpeechProvider | null {
+  return env.ELEVENLABS_API_KEY ? new ElevenLabsSpeechProvider({ apiKey: env.ELEVENLABS_API_KEY }) : null;
+}

package/src/speech/providers/groq.ts

@@ -0,0 +1,35 @@
+/**
+ * Groq-hosted Whisper — the cheapest option we benchmarked ($0.04 per audio hour,
+ * about a fifth of ElevenLabs Scribe). Groq speaks the OpenAI transcription API,
+ * so this is the OpenAI provider pointed at a different host: that is the whole
+ * file, and the template for any other OpenAI-compatible vendor.
+ * Env: GROQ_API_KEY.
+ */
+import { OpenAISpeechProvider } from './openai';
+import type { OpenAISpeechOptions } from './openai';
+
+const GROQ_PRICES: Record<string, number> = {
+  'whisper-large-v3-turbo': 0.04 / 60,
+  'whisper-large-v3': 0.111 / 60,
+};
+
+export class GroqSpeechProvider extends OpenAISpeechProvider {
+  constructor(options: Pick<OpenAISpeechOptions, 'apiKey' | 'fetchImpl' | 'baseUrl'> = {}) {
+    super({
+      ...options,
+      name: 'groq',
+      baseUrl: options.baseUrl ?? 'https://api.groq.com/openai',
+      defaultModel: 'whisper-large-v3-turbo',
+      // Groq's Whisper models return word timings from verbose_json themselves.
+      wordTimestampModel: 'whisper-large-v3-turbo',
+      prices: GROQ_PRICES,
+      fallbackCostPerMinuteUsd: 0.111 / 60,
+    });
+  }
+}
+
+export function createGroqSpeechProvider(
+  env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {},
+): GroqSpeechProvider | null {
+  return env.GROQ_API_KEY ? new GroqSpeechProvider({ apiKey: env.GROQ_API_KEY }) : null;
+}

package/src/speech/providers/mock.ts

@@ -0,0 +1,41 @@
+import { LLMProviderError } from '../../errors';
+import type { ISpeechProvider } from '../interface';
+import type { TranscribeRequest, TranscriptResult } from '../types';
+
+export interface MockSpeechBehavior {
+  text?: string;
+  /** Throw this many retryable failures before succeeding. */
+  failTimes?: number;
+  /** Throw a non-retryable auth error every time. */
+  authError?: boolean;
+}
+
+let behavior: MockSpeechBehavior = {};
+let remainingFailures = 0;
+export function setMockSpeechBehavior(next: MockSpeechBehavior) {
+  behavior = next;
+  remainingFailures = next.failTimes ?? 0;
+}
+export function resetMockSpeechBehavior() {
+  behavior = {};
+  remainingFailures = 0;
+}
+
+/** Deterministic transcription for tests — selected with `SPEECH_PROVIDER=mock`. */
+export class MockSpeechProvider implements ISpeechProvider {
+  readonly name = 'mock';
+  readonly capabilities = { transcribe: true };
+  readonly defaultModel = 'mock-transcribe';
+  isAvailable() { return true; }
+  async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
+    if (behavior.authError) throw new LLMProviderError('mock auth failure', 'AUTHENTICATION_ERROR', false, 401, this.name);
+    if (remainingFailures > 0) {
+      remainingFailures -= 1;
+      throw new LLMProviderError('mock outage', 'SERVICE_UNAVAILABLE', true, 503, this.name);
+    }
+    return {
+      text: behavior.text ?? `mock transcript of ${request.audio.byteLength} bytes`,
+      model: this.defaultModel, provider: this.name, usage: { audioSeconds: 1 },
+    };
+  }
+}

package/src/speech/providers/openai.ts

@@ -0,0 +1,119 @@
+/**
+ * OpenAI speech-to-text. Env: OPENAI_API_KEY (the same key the text provider uses).
+ *
+ * Default model is `gpt-4o-mini-transcribe` — half the price of `gpt-4o-transcribe`
+ * and equally accurate on our benchmark. Per-word timings are only offered by
+ * `whisper-1` (verbose_json), so asking for `timestamps: 'word'` switches model.
+ *
+ * ANY OpenAI-COMPATIBLE ENDPOINT IS THIS CLASS WITH DIFFERENT OPTIONS (see
+ * groq.ts): name, base URL, default model, word-timing model and price table.
+ */
+import type { ISpeechProvider } from '../interface';
+import { assertAudio, audioBlob, speechFetch } from '../http';
+import type { TranscribeRequest, TranscriptResult, TranscriptWord } from '../types';
+
+export interface OpenAISpeechOptions {
+  apiKey?: string;
+  baseUrl?: string;
+  fetchImpl?: typeof fetch;
+  /** Provider name reported in results and errors. Default `openai`. */
+  name?: string;
+  defaultModel?: string;
+  /** Model used when per-word timings are requested. Default `whisper-1`. */
+  wordTimestampModel?: string;
+  /** USD per audio minute by model; unknown models use `fallbackCostPerMinuteUsd`. */
+  prices?: Record<string, number>;
+  fallbackCostPerMinuteUsd?: number;
+}
+
+const OPENAI_PRICES: Record<string, number> = {
+  'gpt-4o-mini-transcribe': 0.003,
+  'gpt-4o-transcribe': 0.006,
+  'whisper-1': 0.006,
+};
+
+export class OpenAISpeechProvider implements ISpeechProvider {
+  readonly name: string;
+  readonly capabilities = { transcribe: true };
+  readonly defaultModel: string;
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly fetchImpl?: typeof fetch;
+  private readonly wordModel: string;
+  private readonly prices: Record<string, number>;
+  private readonly fallbackPrice: number;
+
+  constructor(options: OpenAISpeechOptions = {}) {
+    this.name = options.name ?? 'openai';
+    this.defaultModel = options.defaultModel ?? 'gpt-4o-mini-transcribe';
+    this.wordModel = options.wordTimestampModel ?? 'whisper-1';
+    this.prices = options.prices ?? OPENAI_PRICES;
+    this.fallbackPrice = options.fallbackCostPerMinuteUsd ?? 0.006;
+    this.apiKey = options.apiKey ?? '';
+    this.baseUrl = (options.baseUrl ?? 'https://api.openai.com').replace(/\/+$/, '');
+    this.fetchImpl = options.fetchImpl;
+  }
+
+  isAvailable(): boolean {
+    return Boolean(this.apiKey);
+  }
+
+  costPerMinuteUsd(model?: string): number {
+    return this.prices[model ?? this.defaultModel] ?? this.fallbackPrice;
+  }
+
+  async transcribe(request: TranscribeRequest): Promise<TranscriptResult> {
+    assertAudio(request, this.name);
+    const wantWords = request.timestamps === 'word';
+    const model = request.model ?? (wantWords ? this.wordModel : this.defaultModel);
+    const { blob, filename } = audioBlob(request);
+    const form = new FormData();
+    form.append('file', blob, filename);
+    form.append('model', model);
+    form.append('response_format', wantWords ? 'verbose_json' : 'json');
+    if (wantWords) form.append('timestamp_granularities[]', 'word');
+    if (request.language) form.append('language', request.language);
+    if (request.hints?.length) form.append('prompt', request.hints.join(', '));
+
+    const response = await speechFetch(
+      this.name, `${this.baseUrl}/v1/audio/transcriptions`,
+      { method: 'POST', headers: { authorization: `Bearer ${this.apiKey}` }, body: form },
+      request.timeoutMs, this.fetchImpl,
+    );
+    const json = (await response.json()) as {
+      text?: string; language?: string; duration?: number;
+      words?: Array<{ word: string; start: number; end: number }>;
+      usage?: { seconds?: number };
+    };
+    // On silence the model can hand the biasing prompt straight back as the
+    // "transcript". That is not speech, so report none rather than a confident lie.
+    const heard = (json.text ?? '').trim();
+    const echoed = isEcho(heard, request.hints);
+    const words: TranscriptWord[] | undefined = json.words?.map((w) => ({ text: w.word, start: w.start, end: w.end }));
+    const audioSeconds = json.usage?.seconds ?? json.duration;
+    return {
+      text: echoed ? '' : heard,
+      ...(json.language ? { language: json.language } : {}),
+      ...(words?.length ? { words } : {}),
+      model, provider: this.name,
+      usage: audioSeconds !== undefined ? { audioSeconds } : {},
+    };
+  }
+}
+
+export function createOpenAISpeechProvider(
+  env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {},
+): OpenAISpeechProvider | null {
+  return env.OPENAI_API_KEY ? new OpenAISpeechProvider({ apiKey: env.OPENAI_API_KEY }) : null;
+}
+
+const tokens = (text: string) => text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+
+/** True when every word heard is one of the hint words — i.e. the prompt came back, not speech. */
+function isEcho(heard: string, hints?: string[]): boolean {
+  if (!hints?.length) return false;
+  const said = tokens(heard);
+  // Scaffold words a model attaches when it parrots the prompt ("context:", "projects:").
+  const allowed = new Set([...tokens(hints.join(' ')), 'context', 'prompt', 'vocabulary', 'glossary', 'terms', 'projects', 'names', 'keywords']);
+  return said.length > 0 && said.every((word) => allowed.has(word));
+}

package/src/speech/service.ts

@@ -0,0 +1,103 @@
+import { LLMProviderError } from '../errors';
+import { ProviderRegistry } from '../providers/registry';
+import type { ISpeechProvider } from './interface';
+import { createElevenLabsSpeechProvider } from './providers/elevenlabs';
+import { createGroqSpeechProvider } from './providers/groq';
+import { MockSpeechProvider } from './providers/mock';
+import { createOpenAISpeechProvider } from './providers/openai';
+import type { SpeechServiceConfig, TranscribeRequest, TranscriptResult } from './types';
+
+/**
+ * The speech registry. Built-ins register here; a new vendor is
+ * `registerSpeechProvider('name', factory)` — no edit to `SpeechService`.
+ */
+export const speechProviders = new ProviderRegistry<ISpeechProvider>()
+  .register('groq', () => createGroqSpeechProvider())
+  .register('openai', () => createOpenAISpeechProvider())
+  .register('elevenlabs', () => createElevenLabsSpeechProvider());
+
+export function registerSpeechProvider(name: string, factory: () => ISpeechProvider | null): void {
+  speechProviders.register(name, factory);
+}
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Provider-agnostic speech. Pick a vendor with `preferredProvider` or the
+ * `SPEECH_PROVIDER` env var; with neither it uses the CHEAPEST vendor that has a
+ * key (each provider states its list price) and falls back to the next cheapest. A retryable failure is retried with backoff, and
+ * one that survives the retries falls through to the next available vendor —
+ * unless the error is the caller's (bad audio), which no other vendor would fix.
+ */
+export class SpeechService {
+  private readonly config: Required<SpeechServiceConfig>;
+  private readonly providers: Map<string, ISpeechProvider>;
+
+  constructor(config: SpeechServiceConfig = {}) {
+    const env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {};
+    this.config = {
+      preferredProvider: config.preferredProvider ?? env.SPEECH_PROVIDER ?? '',
+      maxRetries: config.maxRetries ?? 2,
+      fallback: config.fallback ?? true,
+      retryDelayMs: config.retryDelayMs ?? 500,
+    };
+    this.providers = env.SPEECH_PROVIDER === 'mock'
+      ? new Map([['mock', new MockSpeechProvider() as ISpeechProvider]])
+      : speechProviders.instantiate();
+  }
+
+  isAvailable(): boolean {
+    return this.getAvailableProviders().length > 0;
+  }
+
+  getAvailableProviders(): string[] {
+    return [...this.providers].filter(([, p]) => p.isAvailable() && p.capabilities.transcribe).map(([n]) => n);
+  }
+
+  /** Providers in the order they will be tried: the preferred one (if any), then cheapest first. */
+  private order(): ISpeechProvider[] {
+    const usable = [...this.providers.values()].filter((p) => p.isAvailable() && p.capabilities.transcribe);
+    const price = (p: ISpeechProvider) => p.costPerMinuteUsd?.() ?? Number.POSITIVE_INFINITY;
+    // Array.sort is stable, so equal/unknown prices keep registration order.
+    const byPrice = [...usable].sort((a, b) => price(a) - price(b));
+    const wanted = this.config.preferredProvider
+      ? usable.find((p) => p.name === this.config.preferredProvider)
+      : undefined;
+    const first = wanted ?? byPrice[0];
+    if (!first) return [];
+    return this.config.fallback ? [first, ...byPrice.filter((p) => p !== first)] : [first];
+  }
+
+  async transcribe(input: TranscribeRequest): Promise<TranscriptResult> {
+    // A deployment-wide language default stops auto-detect drifting on short clips
+    // (an English note came back in French once). A per-call `language` wins.
+    const env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {};
+    const request = input.language || !env.SPEECH_LANGUAGE ? input : { ...input, language: env.SPEECH_LANGUAGE };
+    const order = this.order();
+    if (!order.length) {
+      throw new LLMProviderError(
+        'No speech providers available. Set GROQ_API_KEY, OPENAI_API_KEY or ELEVENLABS_API_KEY.',
+        'AUTHENTICATION_ERROR', false,
+      );
+    }
+    let last: unknown;
+    for (const provider of order) {
+      for (let attempt = 0; ; attempt += 1) {
+        try {
+          return await provider.transcribe!(request);
+        } catch (error) {
+          last = error;
+          const typed = error instanceof LLMProviderError ? error : null;
+          if (typed?.retryable && attempt < this.config.maxRetries) {
+            await sleep(this.config.retryDelayMs * 2 ** attempt);
+            continue;
+          }
+          // The caller's input is bad — another vendor would say the same.
+          if (typed?.code === 'INVALID_REQUEST') throw error;
+          break;
+        }
+      }
+    }
+    throw last;
+  }
+}

package/src/speech/types.ts

@@ -0,0 +1,59 @@
+/**
+ * Speech types — provider-neutral. Nothing here names a vendor, an app, or a
+ * use case (voice notes, video narration): a provider maps its own API onto
+ * these shapes and a caller never sees the vendor's.
+ */
+export interface TranscriptWord {
+  text: string;
+  /** Seconds from the start of the audio. */
+  start: number;
+  end: number;
+  speaker?: string;
+}
+
+export interface SpeechUsage {
+  /** Billable input, when the provider reports it; else derived from word timings. */
+  audioSeconds?: number;
+  /** Characters synthesized (TTS). */
+  characters?: number;
+}
+
+export interface TranscribeRequest {
+  audio: Uint8Array;
+  /** The recorder's MIME type, parameters allowed (`audio/webm;codecs=opus`). */
+  mimeType: string;
+  /** ISO-639 hint. Omit to auto-detect. */
+  language?: string;
+  /**
+   * Words the speaker is likely to say (names, product terms). Providers that
+   * can bias recognition do; the rest ignore it.
+   */
+  hints?: string[];
+  /** `word` asks for per-word timings; providers that cannot return `words: undefined`. */
+  timestamps?: 'none' | 'word';
+  diarize?: boolean;
+  /** Provider-specific model override. */
+  model?: string;
+  timeoutMs?: number;
+}
+
+export interface TranscriptResult {
+  text: string;
+  language?: string;
+  words?: TranscriptWord[];
+  /** The model that answered, as the vendor reports it. */
+  model: string;
+  provider: string;
+  usage: SpeechUsage;
+}
+
+export interface SpeechServiceConfig {
+  /** Provider tried first. Default: `SPEECH_PROVIDER`, else the cheapest vendor with a key. */
+  preferredProvider?: string;
+  /** Retries on a retryable error, per provider. Default 2. */
+  maxRetries?: number;
+  /** On a failure that survives retries, try the next available provider. Default true. */
+  fallback?: boolean;
+  /** Base delay for exponential backoff, ms. Default 500. */
+  retryDelayMs?: number;
+}