ALLM.Providers.Support.SpeechAdapter behaviour (allm v0.6.1)

Copy Markdown View Source

The shared half of the bundled ALLM.SpeechAdapter and ALLM.SpeechStreamAdapter implementations that speak HTTP.

Layer B helper, the speech sibling of ALLM.Providers.Support.TranscriptionAdapter. Every bundled speech adapter follows the same contract around its provider-specific request building and decoding:

  • The test-injection hand-off: under opts[:adapter_opts][:speech_script] the call goes to ALLM.Providers.FakeSpeech before any gate runs.
  • Gates run before ALLM.Keys.fetch!/2; the input-shape gate is shared.
  • Each attempt runs inside ALLM.Retry.run/3 under opts[:retry], and marks :rate_limited, :provider_unavailable, :timeout and :network_error as retryable.
  • Jason.DecodeError and transport causes are sanitised before they reach an error.
  • The HTTP stream path (stream_resource/6) is one Stream.resource/3 over Finch.async_request/3, with the same event order, error classification and cancel-and-drain on halt for every provider.

The functions are @doc false seams parameterised by the provider atom (the :provider of every error built here). Where the flow needs the adapter's own steps, the adapter module is an argument and these callbacks are invoked on it: run_gates/2, build_request/2, decode_response/4, to_speech_adapter_error/4, malformed_error/2 and redact_key_material/1, plus, for an adapter that streams, speech_started/4, speech_completed/3 and empty_audio_error/1. An adapter that uses this module declares @behaviour for it alongside ALLM.SpeechAdapter and marks each one @impl, so the compiler reports a missing or misnamed callback.