@startsimpli/llm 0.4.30 → 0.4.31

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 };
+}

package/src/refine/types.ts

@@ -0,0 +1,54 @@
+import type { TokenUsage } from '../types';
+
+/** One line a gate reports. A bare string is a defect; `level: 'info'` is information and never fails the gate. */
+export type GateFinding = string | { text: string; level?: 'defect' | 'info' };
+
+/** Gates see the step's result and a caller-owned context. They may be async (a render check, a validator service). */
+export type RefineGate<T, C = unknown> = (result: T, context: C) => GateFinding[] | Promise<GateFinding[]>;
+
+/** The failures one gate found; a report is the list of gates that failed, empty when every gate passed. */
+export interface GateFailure { gate: string; failures: string[] }
+
+export interface GateNote { gate: string; text: string }
+
+/** What the step is handed on every try. Data only: the step decides how to put it in a prompt. */
+export interface StepInput<T> {
+  /** 1-based try number. */
+  n: number;
+  /** The previous try's result, or null on the first try and after a try that produced none. */
+  previous: T | null;
+  /** The previous try's gate report; empty on the first try. */
+  failures: GateFailure[];
+}
+
+export interface StepOutput<T> {
+  /** The revised result, or null when the reply could not be read. */
+  result: T | null;
+  /** What the step rejected in the reply (parse / schema errors). They count as failures of the `rejectedGate` gate. */
+  errors?: string[];
+  /** Model that answered, for the usage tally. */
+  model?: string;
+  usage?: TokenUsage;
+  /** USD this try's calls cost, when the step prices them. */
+  costUsd?: number;
+  /** Step calls this try made (more than one only for a step that regenerates parts). Default 1. */
+  calls?: number;
+}
+
+/** One call of the model (or several, for a step that regenerates parts of a result). The client is closed over, so it is injectable. */
+export type RefineStep<T> = (input: StepInput<T>) => Promise<StepOutput<T>>;
+
+export interface RefineCost { usd: number; promptTokens: number; completionTokens: number; cachedTokens: number }
+
+export interface RefineAttempt<T> {
+  n: number;
+  result: T | null;
+  /** Empty = every gate passed. */
+  report: GateFailure[];
+  /** Informational gate lines; never sent back to the step. */
+  notes: GateNote[];
+  cost: RefineCost;
+  passed: boolean;
+  seconds: number;
+  calls: number;
+}

package/src/speech/captions/cues.ts

@@ -0,0 +1,108 @@
+import type { CaptionWord, Cue, CueOptions } from './types';
+
+const CLAUSE_END = [',', ';', ':', '.', '?', '!'];
+const endsClause = (token: string) => CLAUSE_END.some((c) => token.endsWith(c));
+/** Length in code points, as Python counts. */
+const len = (s: string) => [...s].length;
+
+/**
+ * Index k of the last token (not the final one) that ends a clause with at least two tokens before the cut, else null.
+ * A cue that has to end early ends there instead of in the middle of a clause.
+ */
+function clauseCut(tokens: string[]): number | null {
+  if (endsClause(tokens[tokens.length - 1])) return null;
+  for (let k = tokens.length - 2; k > 0; k -= 1) if (endsClause(tokens[k])) return k;
+  return null;
+}
+
+/** Words -> cues of at most `maxWords` words and `maxChars` characters, also split at a silence over `maxGap`. */
+export function cuesFromWords(words: CaptionWord[], options: CueOptions = {}): Cue[] {
+  const { maxWords = 7, maxChars = 42, maxGap = 0.6, clauseBreaks = false } = options;
+  const cues: Cue[] = [];
+  let cur: CaptionWord[] = [];
+  const flush = (upto?: number) => {
+    const part = upto ? cur.slice(0, upto) : [...cur];
+    if (part.length) {
+      cues.push({ start: part[0].start, end: part[part.length - 1].end, text: part.map((w) => w.text).join(' ') });
+      cur = cur.slice(part.length);
+    }
+  };
+  for (const w of words) {
+    if (cur.length) {
+      const tooLong = len([...cur, w].map((x) => x.text).join(' ')) > maxChars;
+      const gap = w.start - cur[cur.length - 1].end;
+      if (cur.length >= maxWords || tooLong || gap > maxGap) {
+        const k = clauseBreaks && gap <= maxGap ? clauseCut(cur.map((x) => x.text)) : null;
+        flush(k !== null ? k + 1 : undefined);
+      }
+    }
+    cur.push(w);
+  }
+  flush();
+  return cues;
+}
+
+/** Text with no timings: spread evenly over [0, duration], each chunk weighted by its character count. */
+export function cuesFromText(text: string, duration: number, options: CueOptions = {}): Cue[] {
+  const { maxWords = 7, maxChars = 42, clauseBreaks = false } = options;
+  const tokens = text.split(/\s+/).filter(Boolean);
+  if (!tokens.length) return [];
+  const chunks: string[][] = [];
+  let cur: string[] = [];
+  for (const t of tokens) {
+    if (cur.length && (cur.length >= maxWords || len([...cur, t].join(' ')) > maxChars)) {
+      const k = clauseBreaks ? clauseCut(cur) : null;
+      chunks.push(k !== null ? cur.slice(0, k + 1) : cur);
+      cur = k !== null ? cur.slice(k + 1) : [];
+    }
+    cur.push(t);
+  }
+  chunks.push(cur);
+  const texts = chunks.map((c) => c.join(' '));
+  const total = texts.reduce((n, t) => n + len(t), 0);
+  let t0 = 0;
+  return texts.map((s, i) => {
+    const t1 = i === texts.length - 1 ? duration : t0 + (duration * len(s)) / total;
+    const cue = { start: t0, end: t1, text: s };
+    t0 = t1;
+    return cue;
+  });
+}
+
+/** One beat's cues: from its word timings when it has them, else from its text; shifted by `offset` seconds. */
+export function cuesForBeat(
+  words: CaptionWord[] | null | undefined, text: string | null | undefined, duration: number,
+  options: CueOptions & { offset?: number } = {},
+): Cue[] {
+  const { offset = 0, ...cueOptions } = options;
+  const cues = words?.length ? cuesFromWords(words, cueOptions) : cuesFromText(text ?? '', duration, cueOptions);
+  return cues.map((c) => ({ start: c.start + offset, end: c.end + offset, text: c.text }));
+}
+
+/**
+ * Cues with each end moved to the next cue's start when the silence between them is at most `maxGapS`, so a caption stays
+ * up across a short pause. Starts never move; 0 returns the cues unchanged. The input is not mutated.
+ */
+export function holdGaps(cues: Cue[], maxGapS: number): Cue[] {
+  const out = cues.map((c) => ({ ...c }));
+  if (maxGapS > 0) {
+    for (let i = 0; i + 1 < out.length; i += 1) {
+      const gap = out[i + 1].start - out[i].end;
+      if (gap > 0 && gap <= maxGapS) out[i].end = out[i + 1].start;
+    }
+  }
+  return out;
+}
+
+/** Round half to even, as Python's `round`. */
+function roundHalfEven(x: number): number {
+  const floor = Math.floor(x);
+  const diff = x - floor;
+  if (diff === 0.5) return floor % 2 === 0 ? floor : floor + 1;
+  return Math.round(x);
+}
+
+/** [first frame, end frame exclusive]: frame i is shown at time i / fps. */
+export function cueFrameRange(cue: Pick<Cue, 'start' | 'end'>, fps: number): [number, number] {
+  return [roundHalfEven(cue.start * fps), roundHalfEven(cue.end * fps)];
+}

package/src/speech/captions/formats.ts

@@ -0,0 +1,33 @@
+import type { Cue } from './types';
+
+function stamp(ms: number, sep: ',' | '.'): string {
+  const pad = (n: number, w = 2) => String(n).padStart(w, '0');
+  return `${pad(Math.floor(ms / 3_600_000))}:${pad(Math.floor(ms / 60_000) % 60)}:${pad(Math.floor(ms / 1000) % 60)}${sep}${pad(ms % 1000, 3)}`;
+}
+
+/** Millisecond start/end; an end that rounds onto its start is lifted one millisecond so the cue stays valid. */
+function span(c: Cue): [number, number] {
+  const start = Math.max(0, Math.round(c.start * 1000));
+  return [start, Math.max(start + 1, Math.round(c.end * 1000))];
+}
+
+const oneBlock = (text: string) => text.split(/\n\s*\n/).map((s) => s.trim()).filter(Boolean).join('\n');
+
+/** SubRip. Cue text keeps its line breaks; blank lines inside a cue are dropped (they would end it). */
+export function toSrt(cues: Cue[]): string {
+  return cues.map((c, i) => {
+    const [a, b] = span(c);
+    return `${i + 1}\n${stamp(a, ',')} --> ${stamp(b, ',')}\n${oneBlock(c.text)}\n`;
+  }).join('\n');
+}
+
+const vttText = (text: string) => oneBlock(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/-->/g, '--&gt;');
+
+/** WebVTT. `&`, `<` and `-->` in cue text are escaped as the spec requires. */
+export function toVtt(cues: Cue[]): string {
+  const body = cues.map((c) => {
+    const [a, b] = span(c);
+    return `${stamp(a, '.')} --> ${stamp(b, '.')}\n${vttText(c.text)}\n`;
+  }).join('\n');
+  return `WEBVTT\n\n${body}`;
+}

package/src/speech/captions/index.ts

@@ -0,0 +1,6 @@
+/** Caption cues from word timings (or bare text), word-alignment checks, SRT / VTT output. Pure: no vendor, no I/O. */
+export { cueFrameRange, cuesForBeat, cuesFromText, cuesFromWords, holdGaps } from './cues';
+export { toSrt, toVtt } from './formats';
+export type { CaptionWord, Cue, CueOptions } from './types';
+export { InvalidWordsError, assertValidWords, captionTiming, splitWhitespaceTokens, wordsAreProportional } from './words';
+export type { CaptionTiming } from './words';

package/src/speech/captions/types.ts

@@ -0,0 +1,18 @@
+import type { TranscriptWord } from '../types';
+
+/** A word with an optional vendor flag: `alignment: 'proportional'` says the times are guesses spread by character count. */
+export type CaptionWord = TranscriptWord & { alignment?: string };
+
+/** A caption on the video timeline, seconds. */
+export interface Cue { start: number; end: number; text: string }
+
+export interface CueOptions {
+  /** Most words in one cue. Default 7. */
+  maxWords?: number;
+  /** Most characters in one cue. Default 42. */
+  maxChars?: number;
+  /** A silence longer than this (seconds) starts a new cue. Default 0.6. */
+  maxGap?: number;
+  /** A cue that must end early ends at its last clause end (comma, full stop, ...) when it holds one. Default off. */
+  clauseBreaks?: boolean;
+}

package/src/speech/captions/words.ts

@@ -0,0 +1,91 @@
+import { pyFloat, repr } from '../repr';
+import type { CaptionWord, Cue } from './types';
+
+/** A transcript that cannot be captioned: empty, or its times run backwards. Callers stop; nothing substitutes another. */
+export class InvalidWordsError extends Error {
+  constructor(message: string) { super(message); this.name = 'InvalidWordsError'; }
+}
+
+/** Throws `InvalidWordsError` unless there is at least one word and the words are in time order, each ending after it starts. */
+export function assertValidWords<T extends CaptionWord>(words: T[]): T[] {
+  if (!words.length) throw new InvalidWordsError('transcription returned no words');
+  let prev = -1.0;
+  words.forEach((w, i) => {
+    if (w.end < w.start) throw new InvalidWordsError(`word ${i} (${repr(w.text)}) ends before it starts (${pyFloat(w.start)} > ${pyFloat(w.end)})`);
+    if (w.start < prev) {
+      throw new InvalidWordsError(`words are not in time order: word ${i} (${repr(w.text)}) starts at ${pyFloat(w.start)}, before ${pyFloat(prev)}`);
+    }
+    prev = w.start;
+  });
+  return words;
+}
+
+const round3 = (n: number) => Math.round(n * 1000) / 1000;
+
+/** A token holding spaces becomes several words sharing its time evenly; an all-space token is dropped. */
+export function splitWhitespaceTokens(words: CaptionWord[]): CaptionWord[] {
+  const out: CaptionWord[] = [];
+  for (const w of words) {
+    const parts = w.text.split(/\s+/).filter(Boolean);
+    if (parts.length <= 1) {
+      if (parts.length) out.push({ ...w, text: parts[0] });
+      continue;
+    }
+    const step = (w.end - w.start) / parts.length;
+    parts.forEach((p, i) => out.push({ ...w, text: p, start: round3(w.start + i * step), end: round3(w.start + (i + 1) * step) }));
+  }
+  return out;
+}
+
+const median = (xs: number[]) => {
+  const s = [...xs].sort((a, b) => a - b);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+
+/**
+ * True when the words say so (`alignment: 'proportional'`) or, unflagged, when seconds-per-character barely changes from one
+ * word to the next (median relative step). Real vendor alignments step by 30% and more; characters spread evenly by 0%.
+ */
+export function wordsAreProportional(words: CaptionWord[], options: { stepMax?: number; minWords?: number } = {}): boolean {
+  const { stepMax = 0.02, minWords = 8 } = options;
+  const flags = new Set(words.map((w) => w.alignment).filter(Boolean));
+  if (flags.size) return flags.has('proportional');
+  const rate = words.filter((w) => w.end > w.start).map((w) => (w.end - w.start) / Math.max(1, [...w.text].length));
+  if (rate.length < minWords) return false;
+  const mean = rate.reduce((a, b) => a + b, 0) / rate.length;
+  if (mean <= 0) return false;
+  const steps = rate.slice(1).map((r, i) => Math.abs(r - rate[i]));
+  return steps.length > 0 && median(steps) / mean < stepMax;
+}
+
+export type CaptionTiming =
+  | { measured: false; pass: null; n: number; reason: string }
+  | { measured: true; n: number; max_abs_start_err_ms: number; median_abs_start_err_ms: number; max_abs_end_err_ms: number; pass: boolean };
+
+/**
+ * Each caption covers the next `text.split().length` words; compare its start and end with those words'. Proportional words
+ * make the error 0 by construction, which is not a pass: it is `measured: false`. Report keys match the Python review reports.
+ */
+export function captionTiming(captions: Cue[], words: CaptionWord[], options: { maxStartErrMs?: number } = {}): CaptionTiming {
+  const { maxStartErrMs = 250 } = options;
+  if (wordsAreProportional(words)) {
+    return { measured: false, pass: null, n: captions.length, reason: 'word times are proportional guesses (no forced alignment), so caption timing cannot be checked against them' };
+  }
+  let i = 0;
+  const startErr: number[] = [];
+  const endErr: number[] = [];
+  for (const c of captions) {
+    const k = Math.max(1, c.text.split(/\s+/).filter(Boolean).length);
+    const part = words.slice(i, i + k);
+    i += k;
+    if (!part.length) break;
+    startErr.push(Math.abs(c.start - part[0].start) * 1000);
+    endErr.push(Math.abs(c.end - part[part.length - 1].end) * 1000);
+  }
+  if (!startErr.length) return { measured: true, n: 0, max_abs_start_err_ms: 0, median_abs_start_err_ms: 0, max_abs_end_err_ms: 0, pass: false };
+  return {
+    measured: true, n: startErr.length, max_abs_start_err_ms: Math.max(...startErr), median_abs_start_err_ms: median(startErr),
+    max_abs_end_err_ms: Math.max(...endErr), pass: Math.max(...startErr) <= maxStartErrMs,
+  };
+}

package/src/speech/captions-cli.ts

@@ -0,0 +1,50 @@
+import { writeFile } from 'node:fs/promises';
+
+import {
+  InvalidWordsError, assertValidWords, cueFrameRange, cuesForBeat, holdGaps, toSrt, toVtt,
+  type CaptionWord,
+} from './captions';
+
+export interface CaptionsOutcome { exitCode: 0 | 1 | 2; output: unknown }
+
+const FORMATS = ['json', 'srt', 'vtt'];
+
+/** The Python side names a word's text `word`; either spelling is read. */
+const toWord = (w: Record<string, any>): CaptionWord => {
+  const { word, text, ...rest } = w;
+  return { ...rest, text: text ?? word } as CaptionWord;
+};
+
+/**
+ * `startsimpli-speech captions [--format json|srt|vtt] [--out FILE]` — caption cues from word timings or bare text:
+ *   {"words":[{"text"|"word","start","end"}] | "text" + "duration", "offset"?, "clauseBreaks"?, "maxWords"?, "maxChars"?,
+ *    "maxGap"?, "holdGapS"?, "fps"?}
+ * Output `{format, cues, content?, frames?, path?}`: `content` is the SRT / VTT text (also written to --out), `frames` the
+ * [first, end) frame of each cue when `fps` is given. Unusable words are `{error: {code: "INVALID_WORDS"}}`, exit 1.
+ */
+export async function runCaptions(body: Record<string, any>, flags: Record<string, string>): Promise<CaptionsOutcome> {
+  const usage = (message: string): CaptionsOutcome => ({ exitCode: 2, output: { error: { code: 'USAGE', message } } });
+  const format = flags.format ?? 'json';
+  if (!FORMATS.includes(format)) return usage(`--format must be ${FORMATS.join(', ')}, got "${format}"`);
+  const words: CaptionWord[] | undefined = Array.isArray(body.words) ? body.words.map(toWord) : undefined;
+  if (!words?.length && !(typeof body.text === 'string' && typeof body.duration === 'number')) {
+    return usage('captions needs "words" (timed), or "text" and "duration" in the request');
+  }
+  try {
+    if (words?.length) assertValidWords(words);
+    let cues = cuesForBeat(words, body.text, body.duration ?? 0, {
+      offset: body.offset, clauseBreaks: body.clauseBreaks, maxWords: body.maxWords, maxChars: body.maxChars, maxGap: body.maxGap,
+    });
+    if (typeof body.holdGapS === 'number') cues = holdGaps(cues, body.holdGapS);
+    const output: Record<string, unknown> = { format, cues };
+    if (typeof body.fps === 'number') output.frames = cues.map((c) => cueFrameRange(c, body.fps));
+    if (format !== 'json') {
+      output.content = format === 'srt' ? toSrt(cues) : toVtt(cues);
+      if (flags.out) { await writeFile(flags.out, output.content as string); output.path = flags.out; }
+    }
+    return { exitCode: 0, output };
+  } catch (error) {
+    if (error instanceof InvalidWordsError) return { exitCode: 1, output: { error: { code: 'INVALID_WORDS', message: error.message } } };
+    throw error;
+  }
+}

package/src/speech/cli.ts

@@ -16,6 +16,8 @@ import { extname } from 'node:path';
 
 import { LLMProviderError } from '../errors';
 import { SpeechService } from './service';
+import { runCaptions } from './captions-cli';
+import { runVoices } from './voices-cli';
 import type { SynthesizeRequest, TranscribeRequest } from './types';
 
 export interface CliIO {
@@ -36,9 +38,9 @@ const MIME_BY_EXT: Record<string, string> = {
   '.wav': 'audio/wav', '.flac': 'audio/flac',
 };
 
-const FLAGS = new Set(['in', 'out', 'provider', 'model', 'voice', 'format', 'voice-settings', 'language']);
+const FLAGS = new Set(['in', 'out', 'provider', 'model', 'voice', 'format', 'voice-settings', 'language', 'library', 'expiring', 'today']);
 
-const USAGE = 'usage: startsimpli-speech <synthesize|transcribe> [--in request.json] [--out audio-file] '
+const USAGE = 'usage: startsimpli-speech <synthesize|transcribe|voices resolve|captions> [--in request.json] [--out audio-file] '
   + '[--provider NAME] [--model ID] [--voice ID] [--format FMT] [--voice-settings JSON] [--language CODE]';
 
 class UsageError extends Error {}
@@ -70,6 +72,15 @@ async function readRequest(flags: Record<string, string>, io: CliIO): Promise<Re
 export async function runCli(argv: string[], io: CliIO): Promise<CliOutcome> {
   try {
     const [command, ...rest] = argv;
+    if (command === 'voices') {
+      const [sub, ...flagArgs] = rest;
+      const flags = parseFlags(flagArgs);
+      return runVoices(sub, sub === 'resolve' ? await readRequest(flags, io) : {}, flags);
+    }
+    if (command === 'captions') {
+      const flags = parseFlags(rest);
+      return runCaptions(await readRequest(flags, io), flags);
+    }
     if (command !== 'synthesize' && command !== 'transcribe') throw new UsageError(USAGE);
     const flags = parseFlags(rest);
     const body = await readRequest(flags, io);

package/src/speech/index.ts

@@ -20,3 +20,5 @@ export type { OpenAISpeechOptions } from './providers/openai';
 export { MockSpeechProvider, setMockSpeechBehavior, resetMockSpeechBehavior } from './providers/mock';
 export { audioExtension, speechHttpError } from './http';
 export { wordsFromCharacters } from './alignment';
+export * from './voices';
+export * from './captions';

package/src/speech/repr.ts

@@ -0,0 +1,14 @@
+/** Python-style repr of a string, null or string list, so messages read the same as the Python code's (shared goldens compare messages). */
+export function repr(value: unknown): string {
+  if (value === null || value === undefined) return 'None';
+  if (Array.isArray(value)) return `[${value.map(repr).join(', ')}]`;
+  const s = String(value);
+  const quote = s.includes("'") && !s.includes('"') ? '"' : "'";
+  const body = s.replace(/\\/g, '\\\\').replace(new RegExp(quote, 'g'), `\\${quote}`).replace(/\n/g, '\\n');
+  return `${quote}${body}${quote}`;
+}
+
+/** Python `str(float)` for a finite number: integers keep their `.0`. */
+export function pyFloat(n: number): string {
+  return Number.isInteger(n) ? `${n}.0` : String(n);
+}