ALLM.TranscriptSpan (allm v0.6.1)

Copy Markdown View Source

One timed or scored unit of a transcript: a word, the spacing between two words, a non-speech audio event, or a model token. Layer A serializable data.

iex> span = ALLM.TranscriptSpan.new(text: "fox", kind: :word, start_seconds: 1.2, end_seconds: 1.5, logprob: -0.02)
iex> {span.text, span.kind, span.start_seconds}
{"fox", :word, 1.2}

Spans appear on ALLM.TranscriptionResponse's :spans field and on the :committed_transcript and :transcription_completed events of a streaming transcription, and only when the request opted in with timestamps: true or logprobs: true.

Fields

  • :text: the unit's text, as the provider returned it.
  • :kind: one of kinds/0. :word, :spacing and :audio_event are the units of a word-timed transcript (an :audio_event is a non-speech sound such as laughter). :token is a model token, the unit a token-level log-probability attaches to. :other is any unit a provider labels with a type outside that list.
  • :start_seconds, :end_seconds: where the unit starts and ends in the audio, in seconds. Set only when the request asked for timestamps: true, and nil otherwise, even when the provider sent them. Not checked for start_seconds <= end_seconds; they are the provider's values.
  • :logprob: the natural-log probability the model assigned to the unit, normally zero or negative; a provider can report a tiny positive value for a near-certain unit, so do not assume logprob <= 0. Set only when the request asked for logprobs: true, and nil otherwise, even when the provider sent it.

A requested attribute can still be nil on a span when the provider omitted it for that unit. The output depends on the request, not on which attributes a provider happens to send.

Construction

new/1 is a bare struct!/2 pass-through. :text and :kind are required, so leaving either out raises ArgumentError. Unknown keys raise KeyError. Field values are not checked.

Serializability

Round-trips through :erlang.term_to_binary/1 and through ALLM.Serializer's JSON encoding. A decoded :kind string outside kinds/0 becomes :other rather than raising.

Summary

Types

kind()

What a span measures. See kinds/0.

t()

Functions

kinds()

The closed list of :kind values.

new(opts)

Build a %TranscriptSpan{} from keyword opts.

Types

kind()

@type kind() :: :word | :spacing | :audio_event | :token | :other

What a span measures. See kinds/0.

t()

@type t() :: %ALLM.TranscriptSpan{
  end_seconds: number() | nil,
  kind: kind(),
  logprob: number() | nil,
  start_seconds: number() | nil,
  text: String.t()
}

Functions

kinds()

@spec kinds() :: [kind()]

The closed list of :kind values.

Examples

iex> ALLM.TranscriptSpan.kinds()
[:word, :spacing, :audio_event, :token, :other]

new(opts)

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

Build a %TranscriptSpan{} from keyword opts.

Raises ArgumentError when :text or :kind is missing, and KeyError on an unknown key.

Examples

iex> ALLM.TranscriptSpan.new(text: "hello", kind: :token, logprob: -0.5)
%ALLM.TranscriptSpan{text: "hello", kind: :token, start_seconds: nil, end_seconds: nil, logprob: -0.5}