@spec cursor_index(pid()) :: non_neg_integer()

Read the current cursor index for an Agent-backed cursor.

Examples

iex> pid = ALLM.Providers.FakeSpeech.start_script_cursor()
iex> req = ALLM.SpeechRequest.new(input: "x")
iex> opts = [adapter_opts: [speech_script: [{:ok, "a"}], script_cursor: pid]]
iex> {:ok, _} = ALLM.Providers.FakeSpeech.synthesize(req, opts)
iex> ALLM.Providers.FakeSpeech.cursor_index(pid)
1

@spec script([script_entry()]) :: :ok

Document and validate the script grammar for adapter_opts[:speech_script].

Each entry is one of:

• {:ok, bytes} — return bytes as the audio, with :format set to request.format || :mp3 and the MIME type from ALLM.SpeechResponse.format_to_mime/1. {:ok, ""} is :malformed_response from synthesize/2 and a stream ending with :invalid_request and metadata.cause: :empty_input from the streaming callbacks, the error each real path gives.
• {:ok, %ALLM.SpeechResponse{}} — return the struct verbatim, unless its audio is zero bytes, which fails as {:ok, ""} does.
• {:error, %ALLM.Error.SpeechAdapterError{}} — return the struct verbatim.
• {:events, events} — for the streaming callbacks, emit events verbatim. synthesize/2 answers it with :unknown and metadata.cause: :stream_only_script_entry.
• {:retry_until_call, n} — synthetic :rate_limited for the first n - 1 calls against this entry. Consecutive entries of this shape chain into a layered budget.

Returns :ok when the script is well-formed; raises ArgumentError on the first invalid entry. Validation is opt-in: synthesize/2 does not call it.

Examples

iex> ALLM.Providers.FakeSpeech.script([{:ok, "bytes"}, {:retry_until_call, 2}])
:ok

@spec start_script_cursor() :: pid()

Start an Agent-backed script cursor for cross-process multi-call scripting and for disambiguating content-equal scripts in the same process.

Pass the returned pid as adapter_opts[:script_cursor].

Examples

iex> pid = ALLM.Providers.FakeSpeech.start_script_cursor()
iex> ALLM.Providers.FakeSpeech.cursor_index(pid)
0

@spec stream_synthesize(
  ALLM.SpeechRequest.t(),
  keyword()
) ::
  {:ok, Enumerable.t(ALLM.SpeechEvent.t())}
  | {:error, ALLM.Error.SpeechAdapterError.t()}

Stream a scripted speech request as ALLM.SpeechEvent values.

Runs the same gates as synthesize/2, then resolves and advances the script at call time, before the stream is returned, so two calls consume two entries even if neither stream is reduced. The events are:

• absent script or {:ok, bytes} — :speech_started, the bytes split into adapter_opts[:chunk_bytes] pieces (default 1024) as :audio_delta events, then :speech_completed. The default bytes are "FAKE-AUDIO:" <> input. {:ok, ""} is :speech_started, then :invalid_request with metadata.cause: :empty_input, the error a real stream ends with when it closes without audio (synthesize/2 returns :malformed_response for the same entry).
• {:ok, %SpeechResponse{}} — :speech_started built from the struct, its audio bytes as :audio_delta events, then :speech_completed. Zero-byte audio ends with :invalid_request and metadata.cause: :empty_input, as {:ok, ""} does. Audio that cannot be read (nil, or a missing file) ends with :unknown and metadata.cause: :unreadable_script_audio.
• {:error, err} — :speech_started, then {:error, err}.
• {:events, events} — events, verbatim.
• inside a {:retry_until_call, n} budget — a stream whose only event is a :rate_limited error. Streams are never retried, so the next call is the next visit.
• a spent non-empty script — the synchronous :speech_script_exhausted error.

:speech_started carries format: request.format || :mp3, its MIME type, and sample_rate: request.sample_rate.

Examples

iex> req = ALLM.SpeechRequest.new(input: "Hi.", format: :pcm, sample_rate: 24_000)
iex> opts = [adapter_opts: [speech_script: [{:ok, "abcdef"}], chunk_bytes: 4]]
iex> {:ok, events} = ALLM.Providers.FakeSpeech.stream_synthesize(req, opts)
iex> for {:audio_delta, bytes} <- events, do: bytes
["abcd", "ef"]

@spec stream_synthesize_input(
  ALLM.SpeechRequest.t(),
  Enumerable.t(String.t()),
  keyword()
) ::
  {:ok, Enumerable.t(ALLM.SpeechEvent.t())}
  | {:error, ALLM.Error.SpeechAdapterError.t()}

Stream a scripted speech request whose text arrives as an enumerable of chunks. request.input is ignored.

The request is gated synchronously with ALLM.Validate.speech_request(request, input: :streamed): a shape error (for example an unknown :format) returns {:error, %SpeechAdapterError{reason: :invalid_request}} with the validator's errors on metadata.errors, before the script is consulted and before the input is touched.

The script entry is resolved at call time, as in stream_synthesize/2. The input is reduced lazily, when the stream is, and through ALLM.Providers.Support.InputPump, exactly as a real adapter reduces it, so an input that reads the caller's mailbox fails here the same way.

• absent script — one :audio_delta of "FAKE-AUDIO:" <> chunk per non-empty chunk, then :speech_completed.
• {:ok, bytes} — consumes all the input, then emits bytes in adapter_opts[:chunk_bytes] pieces.
• {:error, err}, {:ok, %SpeechResponse{}}, {:events, events} and {:retry_until_call, n} — as in stream_synthesize/2; the input is not reduced.

Every stream that reduces the input obeys the input invariants of ALLM.SpeechStreamAdapter: "" chunks are skipped; a non-binary or non-UTF-8 chunk ends it with metadata.cause: :invalid_input_chunk; an input with no non-empty chunk ends it with :empty_input; an input that raises ends it with :input_raised and one whose pump dies from an exit signal with :input_crashed, each with a %{kind, message} map (an atom and a string) on the error's :cause. opts[:stream_timeout] (default 60,000 ms) bounds the silence between input chunks and ends the stream with :timeout. adapter_opts[:input_window] (default 8) is the pump's credit window.

Examples

iex> req = ALLM.SpeechRequest.new(input: "")
iex> {:ok, events} = ALLM.Providers.FakeSpeech.stream_synthesize_input(req, ["a", "", "b"], [])
iex> for {:audio_delta, bytes} <- events, do: bytes
["FAKE-AUDIO:a", "FAKE-AUDIO:b"]

@spec synthesize(
  ALLM.SpeechRequest.t(),
  keyword()
) ::
  {:ok, ALLM.SpeechResponse.t()} | {:error, ALLM.Error.SpeechAdapterError.t()}

Execute a scripted speech request.

Gate order, all before the script is consulted:

1. adapter_opts[:capture_pid] side-channel (fires even for rejected calls).
2. input empty or not a binary → {:error, %SpeechAdapterError{reason: :invalid_request}}.

Otherwise reads the script from opts[:adapter_opts][:speech_script], advances the process-local cursor, and interprets the entry. An absent script produces the default audio; a spent non-empty script returns :speech_script_exhausted. Both are described in the module docs.

Propagates opts[:request_id] onto response.request_id, request.model onto response.model, request.sample_rate onto response.sample_rate, request.metadata onto response.metadata, and stamps provider: :fake. {:ok, %SpeechResponse{}} script entries are returned verbatim.

A script entry with no audio bytes, {:ok, ""} or a %SpeechResponse{} whose audio is zero bytes, returns {:error, %SpeechAdapterError{reason: :malformed_response}}, which is what a real adapter's synthesize/2 returns for a successful response with an empty body. The streaming callbacks end the same entry with :invalid_request and metadata.cause: :empty_input instead, as a real stream that closes without audio does; ALLM.SpeechAdapter documents the two mappings.

Examples

iex> req = ALLM.SpeechRequest.new(input: "Hi.", metadata: %{trace: "t1"})
iex> {:ok, resp} = ALLM.Providers.FakeSpeech.synthesize(req, request_id: "rid-1")
iex> {resp.request_id, resp.metadata, resp.provider}
{"rid-1", %{trace: "t1"}, :fake}

iex> {:error, err} = ALLM.Providers.FakeSpeech.synthesize(ALLM.SpeechRequest.new(input: ""), [])
iex> err.reason
:invalid_request