ALLM.Response (allm v0.3.0)

A single LLM response. See spec §5.5.

Layer A — pure serializable data. Carries the assistant :message, optional top-level :output_text convenience, :tool_calls the model wants invoked, :finish_reason (closed union), and :usage / :raw provider extras.

:output_text exists so callers can read the flat text payload without re-deriving it from :message.content; use text/1 for the canonical fallback behaviour.

Summary

Types

finish_reason()

Canonical finish-reason atom; see spec §5.5.

t()

Functions

new(opts)

Build a %Response{} from keyword opts.

text(response)

Return the flat text of a response: :output_text if set, else the string :content of :message, else nil.

Types

finish_reason()

@type finish_reason() ::
  :stop | :length | :tool_calls | :content_filter | :error | :other

Canonical finish-reason atom; see spec §5.5.

t()

@type t() :: %ALLM.Response{
  finish_reason: finish_reason() | nil,
  id: String.t() | nil,
  message: ALLM.Message.t() | nil,
  metadata: map(),
  model: String.t() | nil,
  output_text: String.t() | nil,
  raw: term(),
  raw_finish_reason: String.t() | nil,
  request_id: String.t() | nil,
  tool_calls: [ALLM.ToolCall.t()],
  usage: ALLM.Usage.t()
}

Functions

new(opts)

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

Build a %Response{} from keyword opts.

Every field is optional. Unknown keys raise ArgumentError via struct!/2.

Examples

iex> resp = ALLM.Response.new(output_text: "hi", finish_reason: :stop)
iex> resp.output_text
"hi"
iex> resp.finish_reason
:stop

text(response)

@spec text(t()) :: String.t() | nil

Return the flat text of a response: :output_text if set, else the string :content of :message, else nil.

A list-shaped message.content (structured parts) returns nil — callers that need to flatten structured parts should do so explicitly.

Examples

iex> ALLM.Response.text(ALLM.Response.new(output_text: "direct"))
"direct"

iex> ALLM.Response.text(ALLM.Response.new(message: %ALLM.Message{role: :assistant, content: "from-msg"}))
"from-msg"

iex> ALLM.Response.text(ALLM.Response.new([]))
nil