ExAthena.Result (ExAthena v0.3.0)

Copy Markdown View Source

Canonical run outcome returned by ExAthena.run/2 and ExAthena.Loop.run/2.

Carries the terminal state plus full accounting so consumers can drive retries, billing, and observability off a single uniform shape. Every termination — success OR error — produces a Result, including the caps (:error_max_turns, :error_max_budget_usd, …).

Fields

  • :text — the assistant's final text (may be empty for error terminations).
  • :messages — the full conversation thread.
  • :finish_reason — a ExAthena.Loop.Terminations.subtype/0. See that module for the enumeration and category helpers.
  • :halted_reason — the :halt payload when finish_reason is :error_halted; nil otherwise.
  • :iterations — number of completed loop iterations.
  • :tool_calls_made — total tool calls executed across all iterations.
  • :usage — aggregated token usage %{input_tokens:, output_tokens:, total_tokens:} or nil if the provider didn't report.
  • :cost_usd — aggregated cost in USD, nil if unknown.
  • :duration_ms — wall-clock time from ExAthena.run/2 entry to termination.
  • :model — the model identifier as reported by the provider.
  • :provider — the provider atom / module that served the run.
  • :telemetry — span metadata summarising OTel attrs for the run (Phase 4).

Summary

Types

t()
usage()

Functions

category(result)

Shortcut for ExAthena.Loop.Terminations.category/1 on this Result.

error?(result)

Whether the run ended with an error termination.

success?(result)

Whether the run finished normally (no error termination).

Types

t()

@type t() :: %ExAthena.Result{
  cost_usd: float() | nil,
  duration_ms: non_neg_integer() | nil,
  finish_reason: ExAthena.Loop.Terminations.subtype(),
  halted_reason: term() | nil,
  iterations: non_neg_integer(),
  messages: [ExAthena.Messages.Message.t()],
  model: String.t() | nil,
  provider: atom() | module() | nil,
  telemetry: map(),
  text: String.t() | nil,
  tool_calls_made: non_neg_integer(),
  usage: usage() | nil
}

usage()

@type usage() :: %{
  optional(:input_tokens) => non_neg_integer(),
  optional(:output_tokens) => non_neg_integer(),
  optional(:total_tokens) => non_neg_integer()
}

Functions

category(result)

@spec category(t()) :: :success | :retryable | :capacity | :fatal

Shortcut for ExAthena.Loop.Terminations.category/1 on this Result.

error?(result)

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

Whether the run ended with an error termination.

success?(result)

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

Whether the run finished normally (no error termination).