@startsimpli/llm 0.4.26 → 0.4.28

package/README.md

@@ -181,28 +181,32 @@ Per CLAUDE.md **rule 9**, LLM client wiring never belongs in app `src/`. If you
 
 ## Speech (`@startsimpli/llm/speech`)
 
-Pluggable speech-to-text, same provider pattern as the text service.
+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, else ElevenLabs, else any vendor with a key
+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 |
-| --- | --- |
-| `ELEVENLABS_API_KEY` | ElevenLabs Scribe (default) |
-| `OPENAI_API_KEY` | OpenAI `gpt-4o-transcribe` / `whisper-1` for word timings |
-| `SPEECH_PROVIDER=mock` | deterministic, for tests |
-| `SPEECH_PROVIDER` / `SPEECH_LANGUAGE` | pick the vendor / pin the language (e.g. `en`) so short clips don't mis-detect |
+| Env | Provider | List price |
+| --- | --- | --- |
+| `OPENAI_API_KEY` | OpenAI `gpt-4o-mini-transcribe` (default; `gpt-4o-transcribe` / `whisper-1` cost 2x) | $0.18 / hour |
+| `ELEVENLABS_API_KEY` | ElevenLabs Scribe (keyterm hints are a billed add-on, so off unless `sendKeyterms`) | $0.22 / hour |
+| `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
-available vendor (`fallback: false` to pin one). Bad audio (`INVALID_REQUEST`) never falls through.
+vendor (`fallback: false` to pin one). Bad audio (`INVALID_REQUEST`) never falls through.
 
-**Add a vendor** — implement `ISpeechProvider` and register it; no service edit:
+**Add a vendor** — implement `ISpeechProvider` (state `costPerMinuteUsd`) and register it, no
+service edit. An OpenAI-compatible host is just `OpenAISpeechProvider` with a different
+`name` / `baseUrl` / `defaultModel` / `prices`:
 
 ```ts
 registerSpeechProvider('mine', () => (process.env.MINE_KEY ? new MyProvider(process.env.MINE_KEY) : null));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

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

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ElevenLabsSpeechProvider, OpenAISpeechProvider, SpeechService,
+} 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);
+  });
+});
+
+describe('an OpenAI-compatible host is the OpenAI provider with different options', () => {
+  it('reports its own name, model and price and posts to its own base URL', async () => {
+    const f = okJson({ text: ' hi ' });
+    const p = new OpenAISpeechProvider({
+      apiKey: 'k', name: 'selfhosted', baseUrl: 'https://stt.example.com/openai', defaultModel: 'w',
+      prices: { w: 0.001 }, fetchImpl: f as never,
+    });
+    const out = await p.transcribe(req);
+    const [url, init] = f.mock.calls[0] as unknown as [string, RequestInit];
+    expect(url).toBe('https://stt.example.com/openai/v1/audio/transcriptions');
+    expect((init.body as FormData).get('model')).toBe('w');
+    expect(out).toMatchObject({ text: 'hi', provider: 'selfhosted' });
+    expect(p.costPerMinuteUsd()).toBeCloseTo(0.001);
+  });
+});
+
+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

@@ -128,7 +128,7 @@ describe('SpeechService', () => {
     const s = withProviders(new SpeechService({ preferredProvider: 'openai' }), fake('elevenlabs', okResult('elevenlabs')), fake('openai', okResult('openai')));
     expect((await s.transcribe(req)).provider).toBe('openai');
   });
-  it('defaults to ElevenLabs, and falls back to what has a key', async () => {
+  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')));
@@ -153,7 +153,7 @@ describe('SpeechService', () => {
   });
   it('says what to set when nothing is configured', async () => {
     const s = withProviders(new SpeechService());
-    await expect(s.transcribe(req)).rejects.toThrow(/ELEVENLABS_API_KEY or OPENAI_API_KEY/);
+    await expect(s.transcribe(req)).rejects.toThrow(/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 () => {

package/src/speech/index.ts

@@ -1,7 +1,7 @@
 /**
  * `@startsimpli/llm/speech` — pluggable speech-to-text.
  *
- *   const speech = new SpeechService();            // SPEECH_PROVIDER or ElevenLabs, fallback to OpenAI
+ *   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)`.
@@ -13,5 +13,6 @@ export type {
 } from './types';
 export { ElevenLabsSpeechProvider, createElevenLabsSpeechProvider } from './providers/elevenlabs';
 export { OpenAISpeechProvider, createOpenAISpeechProvider } from './providers/openai';
+export type { OpenAISpeechOptions } from './providers/openai';
 export { MockSpeechProvider, setMockSpeechBehavior, resetMockSpeechBehavior } from './providers/mock';
 export { audioExtension, speechHttpError } from './http';

package/src/speech/interface.ts

@@ -15,5 +15,11 @@ import type { TranscribeRequest, TranscriptResult } from './types';
 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

@@ -7,6 +7,12 @@ 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;
@@ -21,8 +27,10 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
   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;
@@ -32,6 +40,11 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
     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;
@@ -42,8 +55,8 @@ export class ElevenLabsSpeechProvider implements ISpeechProvider {
     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 bias list on models that take it.
-    for (const term of request.hints ?? []) form.append('keyterms', term);
+    // 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`,

package/src/speech/providers/openai.ts

@@ -1,8 +1,12 @@
 /**
  * OpenAI speech-to-text. Env: OPENAI_API_KEY (the same key the text provider uses).
  *
- * `gpt-4o-transcribe` for plain text; per-word timings are only offered by
+ * 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: name, base
+ * URL, default model, word-timing model and price table.
  */
 import type { ISpeechProvider } from '../interface';
 import { assertAudio, audioBlob, speechFetch } from '../http';
@@ -12,17 +16,39 @@ 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 = 'openai';
+  readonly name: string;
   readonly capabilities = { transcribe: true };
-  readonly defaultModel = 'gpt-4o-transcribe';
+  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;
@@ -32,10 +58,14 @@ export class OpenAISpeechProvider implements ISpeechProvider {
     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 ? 'whisper-1' : this.defaultModel);
+    const model = request.model ?? (wantWords ? this.wordModel : this.defaultModel);
     const { blob, filename } = audioBlob(request);
     const form = new FormData();
     form.append('file', blob, filename);

package/src/speech/service.ts

@@ -1,5 +1,5 @@
 import { LLMProviderError } from '../errors';
-import { ProviderRegistry, pickProvider } from '../providers/registry';
+import { ProviderRegistry } from '../providers/registry';
 import type { ISpeechProvider } from './interface';
 import { createElevenLabsSpeechProvider } from './providers/elevenlabs';
 import { MockSpeechProvider } from './providers/mock';
@@ -11,8 +11,8 @@ import type { SpeechServiceConfig, TranscribeRequest, TranscriptResult } from '.
  * `registerSpeechProvider('name', factory)` — no edit to `SpeechService`.
  */
 export const speechProviders = new ProviderRegistry<ISpeechProvider>()
-  .register('elevenlabs', () => createElevenLabsSpeechProvider())
-  .register('openai', () => createOpenAISpeechProvider());
+  .register('openai', () => createOpenAISpeechProvider())
+  .register('elevenlabs', () => createElevenLabsSpeechProvider());
 
 export function registerSpeechProvider(name: string, factory: () => ISpeechProvider | null): void {
   speechProviders.register(name, factory);
@@ -22,8 +22,8 @@ const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve,
 
 /**
  * Provider-agnostic speech. Pick a vendor with `preferredProvider` or the
- * `SPEECH_PROVIDER` env var; with neither it prefers ElevenLabs and falls back
- * to whatever else has a key. A retryable failure is retried with backoff, and
+ * `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.
  */
@@ -34,7 +34,7 @@ export class SpeechService {
   constructor(config: SpeechServiceConfig = {}) {
     const env: Record<string, string | undefined> = typeof process !== 'undefined' ? process.env : {};
     this.config = {
-      preferredProvider: config.preferredProvider ?? env.SPEECH_PROVIDER ?? 'elevenlabs',
+      preferredProvider: config.preferredProvider ?? env.SPEECH_PROVIDER ?? '',
       maxRetries: config.maxRetries ?? 2,
       fallback: config.fallback ?? true,
       retryDelayMs: config.retryDelayMs ?? 500,
@@ -52,12 +52,18 @@ export class SpeechService {
     return [...this.providers].filter(([, p]) => p.isAvailable() && p.capabilities.transcribe).map(([n]) => n);
   }
 
-  /** Providers in the order they will be tried. */
+  /** Providers in the order they will be tried: the preferred one (if any), then cheapest first. */
   private order(): ISpeechProvider[] {
-    const usable = new Map([...this.providers].filter(([, p]) => p.isAvailable() && p.capabilities.transcribe));
-    const first = pickProvider(usable, this.config.preferredProvider);
+    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, ...[...usable.values()].filter((p) => p !== first)] : [first];
+    return this.config.fallback ? [first, ...byPrice.filter((p) => p !== first)] : [first];
   }
 
   async transcribe(input: TranscribeRequest): Promise<TranscriptResult> {
@@ -68,7 +74,7 @@ export class SpeechService {
     const order = this.order();
     if (!order.length) {
       throw new LLMProviderError(
-        'No speech providers available. Set ELEVENLABS_API_KEY or OPENAI_API_KEY.',
+        'No speech providers available. Set OPENAI_API_KEY or ELEVENLABS_API_KEY.',
         'AUTHENTICATION_ERROR', false,
       );
     }

package/src/speech/types.ts

@@ -48,7 +48,7 @@ export interface TranscriptResult {
 }
 
 export interface SpeechServiceConfig {
-  /** Provider tried first. Default: `SPEECH_PROVIDER`, else `elevenlabs`. */
+  /** 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;