AshBaml.Response (ash_baml v0.2.0)

Wrapper for BAML function responses including usage metadata.

This struct wraps the result of a BAML function call with token usage information, enabling integration with observability systems like AshAgent's response_usage/1.

Fields

:data - The actual BAML function result (struct or primitive)
:usage - Token usage map with :input_tokens, :output_tokens, :total_tokens
:collector - The BamlElixir.Collector reference used for the call
:model_name - LLM model name (e.g., "gpt-4", "claude-3-opus")
:provider - LLM provider (e.g., "openai", "anthropic")
:client_name - BAML client name used for the call
:timing - Timing information map with :duration_ms, :start_time_utc_ms, :time_to_first_token_ms
:num_attempts - Number of LLM call attempts (tracks retries/fallbacks)
:function_name - BAML function name that was called
:request_id - Unique identifier for this request
:raw_response - Raw LLM text output before BAML parsing
:http_response_body - Full HTTP response body JSON string (contains thinking blocks)
:tags - Custom metadata tags map
:log_type - Type of call: "call" or "stream"

Example

response = AshBaml.Response.new(result, collector)
response.data           # => %ChatResponse{message: "Hello!"}
response.usage          # => %{input_tokens: 10, output_tokens: 5, total_tokens: 15}
response.model_name     # => "gpt-4"
response.provider       # => "openai"
response.timing         # => %{duration_ms: 234, start_time_utc_ms: 1699123456789}
response.num_attempts   # => 1
response.function_name  # => "ChatAgent"

data = AshBaml.Response.unwrap(response)
usage = AshBaml.Response.usage(response)

Summary

Types

t()

Functions

new(data, collector)

Creates a new Response wrapping BAML function result with usage metadata.

thinking(arg1)

Extracts thinking content from the HTTP response body.

unwrap(data)

Extracts the original data from a Response struct.

usage(response)

Extracts usage metadata from a Response struct.

Types

t()

@type t() :: %AshBaml.Response{
  client_name: String.t() | nil,
  collector: %BamlElixir.Collector{reference: reference()} | nil,
  data: term(),
  function_name: String.t() | nil,
  http_response_body: String.t() | nil,
  log_type: String.t() | nil,
  model_name: String.t() | nil,
  num_attempts: non_neg_integer() | nil,
  provider: String.t() | nil,
  raw_response: String.t() | nil,
  request_id: String.t() | nil,
  tags: map() | nil,
  timing:
    %{
      duration_ms: number(),
      start_time_utc_ms: number(),
      time_to_first_token_ms: number() | nil
    }
    | nil,
  usage:
    %{
      input_tokens: non_neg_integer(),
      output_tokens: non_neg_integer(),
      total_tokens: non_neg_integer()
    }
    | nil
}

Functions

new(data, collector)

Creates a new Response wrapping BAML function result with usage metadata.

Arguments

data - The BAML function result to wrap
collector - The BamlElixir.Collector used for the call (may be nil)

Returns

Returns a %AshBaml.Response{} struct with extracted usage information.

thinking(arg1)

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

Extracts thinking content from the HTTP response body.

Extended thinking models return content blocks with type "thinking". This parses the http_response_body JSON to extract that content.

Arguments

response - A %AshBaml.Response{} struct

Returns

Returns the thinking content as a string, or nil if no thinking content is present.

unwrap(data)

@spec unwrap(t() | term()) :: term()

Extracts the original data from a Response struct.

This is a convenience function that handles both Response structs and raw data, making it safe to use in contexts where you're unsure if the data has been wrapped.

Arguments

response - Either a %AshBaml.Response{} struct or raw data

Returns

Returns the unwrapped data.

Examples

iex> response = %AshBaml.Response{data: "hello"}
iex> AshBaml.Response.unwrap(response)
"hello"

iex> AshBaml.Response.unwrap("hello")
"hello"

usage(response)

@spec usage(t()) :: map() | nil

Extracts usage metadata from a Response struct.

Arguments

response - A %AshBaml.Response{} struct

Returns

Returns a map with :input_tokens, :output_tokens, and :total_tokens, or nil if usage information is unavailable.

Example

iex> response = %AshBaml.Response{usage: %{input_tokens: 10, output_tokens: 5, total_tokens: 15}}
iex> AshBaml.Response.usage(response)
%{input_tokens: 10, output_tokens: 5, total_tokens: 15}