ALLM.TranscriptionResponse (allm v0.6.1)

A speech-to-text response. Layer A serializable data.

iex> resp = ALLM.TranscriptionResponse.new(text: "The quick brown fox.")
iex> resp.text
"The quick brown fox."

Fields

:text: the transcript, as plain text.
:spans: the transcript's words or tokens as ALLM.TranscriptSpan.t/0 values, in order, carrying start and end times when the request set timestamps: true and log-probabilities when it set logprobs: true. nil means neither flag was set; [] means a flag was set and nothing was spoken. Segment-level timestamps, speaker labels and subtitle formats are not modelled, and the provider's full body stays on :raw for callers who need them. mean_logprob/1 summarizes the spans.
:language: the spoken language as the provider reports it, not normalized, or nil.
:duration_seconds: billed audio seconds, when the provider bills transcription by duration.
:id, :request_id, :model, :provider: provider correlation.
:usage: an ALLM.Usage.t/0, never nil. Providers that bill in tokens populate it, and a response carrying no counters holds %ALLM.Usage{} with every field nil. Billed seconds go in :duration_seconds rather than Usage.extra, because a typed field survives a JSON round-trip without its keys turning from atoms into strings.
:raw: the provider's response body.
:metadata: caller-owned.

A transcript produced by a general-purpose model prompted to transcribe, rather than by a dedicated speech model, is not guaranteed to be verbatim.

Summary

Functions

mean_logprob(transcription_response)

The mean log-probability of the response's spoken units, or nil.

new(opts \\ [])

Build a %TranscriptionResponse{} from keyword opts.

Types

t()

@type t() :: %ALLM.TranscriptionResponse{
  duration_seconds: number() | nil,
  id: String.t() | nil,
  language: String.t() | nil,
  metadata: map(),
  model: String.t() | nil,
  provider: atom() | nil,
  raw: term(),
  request_id: String.t() | nil,
  spans: [ALLM.TranscriptSpan.t()] | nil,
  text: String.t(),
  usage: ALLM.Usage.t()
}

Functions

mean_logprob(transcription_response)

@spec mean_logprob(t()) :: float() | nil

The mean log-probability of the response's spoken units, or nil.

Averages :logprob over the spans whose :kind is :word or :token and whose :logprob is a number. :spacing and :audio_event spans are left out because they are not spoken units, and some providers copy the next word's log-probability onto the spacing before it, which would count that word twice. Returns nil when :spans is nil or no span qualifies.

Examples

iex> spans = [
...>   ALLM.TranscriptSpan.new(text: "quick", kind: :word, logprob: -0.25),
...>   ALLM.TranscriptSpan.new(text: " ", kind: :spacing, logprob: -0.25),
...>   ALLM.TranscriptSpan.new(text: "fox", kind: :word, logprob: -0.5)
...> ]
iex> ALLM.TranscriptionResponse.mean_logprob(ALLM.TranscriptionResponse.new(spans: spans))
-0.375

iex> ALLM.TranscriptionResponse.mean_logprob(ALLM.TranscriptionResponse.new())
nil

new(opts \\ [])

@spec new(keyword()) :: t()

Build a %TranscriptionResponse{} from keyword opts.

Unknown keys raise KeyError via struct!/2.

Examples

iex> resp = ALLM.TranscriptionResponse.new()
iex> {resp.text, resp.usage}
{"", %ALLM.Usage{}}