ALLM.ChatResult (allm v0.3.0)

The result of a full chat loop. See spec §5.9.

Layer A — pure serializable data. Carries the final :thread, the :final_response, a list of per-turn :steps, and a :halted_reason atom indicating why the loop stopped.

halted_reason: :completed means the loop terminated normally. Every other atom represents a halt — including :max_turns (spec §20's :max_turns_exceeded), :halt_when, :ask_user, :tool_error, :cancelled, and any custom atom a tool returned via {:halt, atom, _}. Use halted?/1 to check.

Summary

Types

halted_reason()

Reason the chat loop halted. :completed is the normal-exit atom; every other value signals early termination. The type is open (atom() tail) so custom tool-halt reasons surface here without touching the enum.

t()

Functions

halted?(chat_result)

Return true when halted_reason is anything other than :completed.

new(opts)

Build a %ChatResult{} from keyword opts.

Types

halted_reason()

@type halted_reason() ::
  :completed
  | :max_turns
  | :halt_when
  | :ask_user
  | :tool_error
  | :cancelled
  | atom()

Reason the chat loop halted. :completed is the normal-exit atom; every other value signals early termination. The type is open (atom() tail) so custom tool-halt reasons surface here without touching the enum.

t()

@type t() :: %ALLM.ChatResult{
  final_response: ALLM.Response.t(),
  halted_reason: halted_reason(),
  metadata: map(),
  pending_question: String.t() | nil,
  pending_tool_call_id: String.t() | nil,
  steps: [ALLM.StepResult.t()],
  thread: ALLM.Thread.t()
}

Functions

halted?(chat_result)

@spec halted?(t()) :: boolean()

Return true when halted_reason is anything other than :completed.

Examples

iex> ALLM.ChatResult.halted?(ALLM.ChatResult.new(halted_reason: :completed))
false

iex> ALLM.ChatResult.halted?(ALLM.ChatResult.new(halted_reason: :max_turns))
true

new(opts)

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

Build a %ChatResult{} from keyword opts.

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

Examples

iex> cr = ALLM.ChatResult.new(halted_reason: :completed)
iex> cr.halted_reason
:completed
iex> cr.steps
[]