Deterministic, scripted adapter for speech-to-text testing. Implements ALLM.TranscriptionAdapter and ALLM.TranscriptionStreamAdapter.

Layer B — runtime. FakeTranscription is the canonical testing transcription adapter; it ships in lib/ (not test/support/) because users need it for their own application tests, mirroring ALLM.Providers.FakeSpeech and ALLM.Providers.FakeModeration.

What FakeTranscription is (and isn't)

FakeTranscription never listens to the audio. It measures :audio to run the resolvable and size gates every ALLM.TranscriptionAdapter must run, and reads :model and :metadata to round-trip them onto the response. It has no MIME gate: accepted MIME types are a real provider's concern.

Size cap

max_audio_bytes/0 returns 1024, deliberately small so a test crosses the boundary cheaply. The gate measures against adapter_opts[:max_audio_bytes] || max_audio_bytes(). A real adapter that hands a scripted call off to this Fake passes its own cap under that key, so a scripted run with a real multi-kilobyte clip is not rejected by the Fake's small default.

Default transcript (no script)

With no script — adapter_opts[:transcription_script] absent or [] — the response carries text: "" and usage: %ALLM.Usage{}.

Spent script

A non-empty script whose cursor has run off the end does NOT fall back to the default — it returns

{:error, %ALLM.Error.TranscriptionAdapterError{
   reason: :unknown,
   metadata: %{cause: :transcription_script_exhausted}}}

Script shapes

opts[:adapter_opts][:transcription_script] accepts a list of script entries. See script/1 for the full grammar.

adapter_opts: [
  transcription_script: [
    {:ok, "The quick brown fox."},
    {:ok, %ALLM.TranscriptionResponse{...}},
    {:error, %ALLM.Error.TranscriptionAdapterError{reason: :rate_limited}},
    {:retry_until_call, 3}
  ]
]

{:retry_until_call, n} returns a synthetic %ALLM.Error.TranscriptionAdapterError{reason: :rate_limited, retry_after_ms: 0} for the first n - 1 calls against this entry, then advances to the next entry on call n. Consecutive entries of this shape chain. n must be a positive integer: any other budget raises ArgumentError naming the entry when a call reaches it, whether or not the script went through script/1.

Span flags

With timestamps: true or logprobs: true on the request, a text entry (and the no-script default) is split on whitespace into one :word ALLM.TranscriptSpan per word: word i spans i * 0.5 to (i + 1) * 0.5 seconds with logprob -0.1. Times are kept only under timestamps: true and the logprob only under logprobs: true; a flag counts only when it is exactly true. Blank text gives spans: []; with both flags off spans is nil and no stream event carries a :spans key.

iex> req = ALLM.TranscriptionRequest.new(
...>   audio: ALLM.Audio.from_binary(<<0>>, "audio/mpeg"), logprobs: true)
iex> opts = [adapter_opts: [transcription_script: [{:ok, "hi there"}]]]
iex> {:ok, resp} = ALLM.Providers.FakeTranscription.transcribe(req, opts)
iex> for s <- resp.spans, do: {s.text, s.start_seconds, s.logprob}
[{"hi", nil, -0.1}, {"there", nil, -0.1}]

On the stream path the one committed segment carries the same spans and :transcription_completed carries them under :spans ([] when nothing was committed). A scripted %TranscriptionResponse{} is the escape hatch: its own :spans is returned (or streamed) as scripted, whatever the flags say.

adapter_opts[:span_flags], when present, is the list of flags the caller's adapter supports. A set flag outside it is refused with {:error, %ALLM.Error.TranscriptionAdapterError{reason: :unsupported_feature, metadata: %{field: flag}}} after the audio (or sample-rate) gate and before the script is consulted, so the refusal does not advance the cursor; :timestamps is checked before :logprobs. The error's :provider is nil. Without the key both flags are supported.

iex> req = ALLM.TranscriptionRequest.new(
...>   audio: ALLM.Audio.from_binary(<<0>>, "audio/mpeg"), timestamps: true)
iex> opts = [adapter_opts: [transcription_script: [{:ok, "hi"}], span_flags: [:logprobs]]]
iex> {:error, err} = ALLM.Providers.FakeTranscription.transcribe(req, opts)
iex> {err.reason, err.metadata.field}
{:unsupported_feature, :timestamps}

Streaming

stream_transcribe/3 resolves its script entry and advances the cursor at call time, before it returns {:ok, stream}, so two calls consume two entries even if neither stream is reduced. Streams are never retried, so on the stream path {:retry_until_call, n} returns a stream holding only the rate-limit error while the entry's visit counter (shared with transcribe/2) is below n. The input is reduced through ALLM.Providers.Support.InputPump, in another process, as a real adapter reduces it. stream_sample_rates/0 is [8_000, 16_000, 24_000].

Cursor behaviour

Multi-call scripts advance a per-process cursor on every call. The cursor lives in the process dictionary at {:allm_fake_transcription_cursor, key_id}, isolated per ExUnit test process (async: true), GC'd on pid-down, zero-setup for the common case. The key_id is chosen by this precedence:

1. adapter_opts[:script_cursor] — an explicit Agent pid (handled separately; see start_script_cursor/0).
2. adapter_opts[:cursor_key] — the engine's stable :id, injected by the façade dispatch chokepoint via ALLM.Engine.put_cursor_key/2.
3. :erlang.phash2(script) — the content-hash fallback for direct adapter calls with no engine.

At the façade the cursor keys on engine identity, so two engines built with content-equal :transcription_script values each read index 0 on their first call, even in the same process. The content-hash footgun remains only for DIRECT adapter calls — ALLM.Providers.FakeTranscription.transcribe(req, opts) invoked without an engine receives no :cursor_key. Workaround for that path: pass distinct adapter_opts[:script_cursor] Agent pids from start_script_cursor/0. The {:retry_until_call, n} visit counter keys on the same identity, so content-equal engines never share a retry budget.

Test-only capture seam

Pass adapter_opts[:capture_pid] with a pid to receive a side-channel message every time transcribe/2 or stream_transcribe/3 is invoked, BEFORE any gate runs and before the script is consulted:

{ALLM.Providers.FakeTranscription, :call, %{request: request, opts: opts}}

Examples

iex> audio = ALLM.Audio.from_binary(<<0, 1, 2>>, "audio/mpeg")
iex> req = ALLM.TranscriptionRequest.new(audio: audio)
iex> opts = [adapter_opts: [transcription_script: [{:ok, "Hello."}]]]
iex> {:ok, resp} = ALLM.Providers.FakeTranscription.transcribe(req, opts)
iex> resp.text
"Hello."