@spec prepare_request(
  ALLM.SpeechRequest.t(),
  keyword()
) :: {:ok, Req.Request.t()} | {:error, ALLM.Error.SpeechAdapterError.t()}

Return an unfired Req.Request configured exactly as synthesize/2 would fire it, for callers who add headers, middleware or their own retry loop.

The pre-flight gates run first, so this is defined only for an input that passes them. Under opts[:adapter_opts][:speech_script] it returns a stub error instead of delegating to ALLM.Providers.FakeSpeech.

Examples

iex> req = ALLM.SpeechRequest.new(input: "Hi.")
iex> {:ok, http} = ALLM.Providers.OpenAI.Speech.prepare_request(req, api_key: "sk-x")
iex> URI.to_string(http.url)
"https://api.openai.com/v1/audio/speech"

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

Stream speech for request.input from OpenAI as it is synthesized.

Returns {:ok, enumerable} of ALLM.SpeechEvent values, or {:error, %ALLM.Error.SpeechAdapterError{}} from a pre-flight gate. The four gates of synthesize/2 run first, then ALLM.Keys.fetch!/2 (which raises %ALLM.Error.EngineError{reason: :missing_key} by design). No HTTP request is made until the enumerable is reduced.

Injected defaults: the same model ("gpt-4o-mini-tts") and voice ("alloy") as synthesize/2, and the same JSON body.

Options:

• :stream_timeout — milliseconds of silence between two transport messages before the stream ends with {:error, %SpeechAdapterError{reason: :timeout}}. Default 60000. The transport's own receive timeout defaults above it (see ALLM.Providers.Support.Transport).
• :receive_timeout, :request_timeout, :pool_timeout — forwarded to Finch.async_request/3.
• :finch_name — the Finch pool (default ALLM.Finch).
• :finch_module — the module called for async_request/3 and cancel_async_request/1 (default Finch); tests pass ALLM.Test.FinchStub.

Each transport option is read from the top level of opts. ALLM.stream_synthesize/3 hoists an engine's adapter_opts: transport keys (ALLM.Adapter.transport_opts/0) there, as the chat façades do; a direct call passes them at the top level.

Events: :speech_started (with sample_rate 24000 for :pcm and :wav, else nil) once the response headers arrive, one :audio_delta per non-empty body chunk, and :speech_completed with an all-nil usage. A failure ends the stream with one {:error, _}:

• an HTTP error status: the error body is collected until the response ends, then classified as synthesize/2 classifies it (a 401 is :authentication_failed, a string_too_long 400 is :context_length_exceeded), with provider strings redacted;
• a 200 whose content-type is not audio/*: :malformed_response;
• a 200 with no audio bytes: :invalid_request with metadata.cause: :empty_input;
• no transport message within :stream_timeout: :timeout;
• a transport failure: :network_error.

Halting the stream early (Enum.take/2) cancels the HTTP request and removes the request's already-queued messages from the calling process's mailbox. This is best-effort: a message the request process sends while it is being shut down can still arrive afterwards.

opts[:adapter_opts][:speech_script] hands the call to ALLM.Providers.FakeSpeech.stream_synthesize/2 before any gate runs.

Examples

iex> req = ALLM.SpeechRequest.new(input: "Hello.", format: :pcm)
iex> opts = [adapter_opts: [speech_script: [{:ok, "PCM-bytes"}]]]
iex> {:ok, events} = ALLM.Providers.OpenAI.Speech.stream_synthesize(req, opts)
iex> for {:audio_delta, bytes} <- events, into: "", do: bytes
"PCM-bytes"

iex> req = ALLM.SpeechRequest.new(input: "Hi.", format: :mp3, sample_rate: 24_000)
iex> {:error, err} = ALLM.Providers.OpenAI.Speech.stream_synthesize(req, [])
iex> err.reason
:unsupported_feature

iex> req = ALLM.SpeechRequest.new(input: "Hi.", format: :ulaw)
iex> {:error, err} = ALLM.Providers.OpenAI.Speech.stream_synthesize(req, [])
iex> {err.reason, err.metadata.field}
{:unsupported_feature, :format}

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

Synthesize speech from request.input against OpenAI.

Returns {:ok, %ALLM.SpeechResponse{}} or {:error, %ALLM.Error.SpeechAdapterError{}}. The one exception is ALLM.Keys.fetch!/2, which raises %ALLM.Error.EngineError{reason: :missing_key} by design; all four pre-flight gates run ahead of it.

Sample rate: response.sample_rate is 24000 for :pcm and :wav and nil for every other format. A request sample_rate other than nil (or 24000 for :pcm / :wav) is refused with :unsupported_feature before any I/O.

Formats: :ulaw and :alaw are refused with :unsupported_feature and metadata.field: :format before any I/O; OpenAI has no telephony output.

Injected defaults: model is "gpt-4o-mini-tts" and voice is "alloy" when the request leaves them nil, and the receive timeout is 60 s when opts[:request_timeout] is absent.

Retry: this adapter's own ALLM.Retry.run/3 loop retries :timeout under the default policy. :rate_limited, :provider_unavailable and :network_error are retryable too, but only under a caller-supplied opts[:retry] that lists them (as ALLM.synthesize/3's own loop does).

See the module documentation for the gates, the wire-field map and the adapter_opts[:speech_script] test-injection short-circuit.

Examples

iex> req = ALLM.SpeechRequest.new(input: "Hello.")
iex> opts = [adapter_opts: [speech_script: [{:ok, "ID3-bytes"}]]]
iex> {:ok, resp} = ALLM.Providers.OpenAI.Speech.synthesize(req, opts)
iex> ALLM.Audio.to_binary(resp.audio)
{:ok, "ID3-bytes"}

iex> req = ALLM.SpeechRequest.new(input: String.duplicate("a", 4097))
iex> {:error, err} = ALLM.Providers.OpenAI.Speech.synthesize(req, [])
iex> {err.reason, err.metadata}
{:context_length_exceeded, %{count: 4097, max: 4096}}