Sycophant.Response (sycophant v0.5.0)

The result of an LLM call.

Contains the generated text or structured object, any tool calls requested by the model, token usage statistics, and an opaque Context that enables conversation continuation.

Continuing Conversations

Use response.context with Context.add/2 to continue the conversation:

{:ok, response} = Sycophant.generate_text("openai:gpt-4o-mini", messages)
ctx = response.context |> Context.add(Message.user("Tell me more"))
{:ok, follow_up} = Sycophant.generate_text("openai:gpt-4o-mini", ctx)

Inspecting History

Use messages/1 to retrieve the full conversation history:

Response.messages(response)
#=> [%Message{role: :user, ...}, %Message{role: :assistant, ...}]

Serialization

Responses support JSON persistence via Sycophant.Serializable.Decoder:

json = Sycophant.Serializable.Decoder.encode(response)
restored = Sycophant.Serializable.Decoder.decode(json)

Summary

Types

finish_reason()

t()

Functions

messages(response)

Returns the full conversation message history from the response context.

reasoning_text(arg1)

Returns the first reasoning content text, if present.

t()

text(response)

Returns the response text.

Types

finish_reason()

@type finish_reason() ::
  :stop
  | :tool_use
  | :max_tokens
  | :content_filter
  | :recitation
  | :error
  | :incomplete
  | :unknown
  | nil

t()

@type t() :: %Sycophant.Response{
  __type__: binary(),
  citations: [
    %Sycophant.Citation{
      __type__: binary(),
      cited_text: nil | binary(),
      document_index: nil | integer(),
      document_title: nil | binary(),
      end_index: nil | integer(),
      file_id: nil | binary(),
      source: nil | binary(),
      start_index: nil | integer(),
      title: nil | binary(),
      type:
        nil
        | :page_location
        | :char_location
        | :content_block_location
        | :web_search_result_location
        | :search_result_location,
      unit: nil | :page | :char | :block,
      url: nil | binary()
    }
  ],
  context:
    nil
    | %Sycophant.Context{
        __type__: binary(),
        messages: [
          %Sycophant.Message{
            __type__: binary(),
            content:
              nil
              | binary()
              | [
                  %Sycophant.Message.Content.Text{
                    __type__: binary(),
                    citations:
                      nil
                      | [
                          %Sycophant.Citation{
                            __type__: binary(),
                            cited_text: nil | binary(),
                            document_index: nil | integer(),
                            document_title: nil | binary(),
                            end_index: nil | integer(),
                            file_id: nil | binary(),
                            source: nil | binary(),
                            start_index: nil | integer(),
                            title: nil | binary(),
                            type:
                              nil
                              | :page_location
                              | :char_location
                              | :content_block_location
                              | :web_search_result_location
                              | :search_result_location,
                            unit: nil | :page | :char | :block,
                            url: nil | binary()
                          }
                        ],
                    text: binary(),
                    type: binary()
                  }
                  | %Sycophant.Message.Content.Image{
                      __type__: binary(),
                      data: nil | binary(),
                      media_type: nil | binary(),
                      type: binary(),
                      url: nil | binary()
                    }
                  | %Sycophant.Message.Content.Document{
                      __type__: binary(),
                      citations: boolean(),
                      data: nil | binary(),
                      file_id: nil | binary(),
                      media_type: nil | binary(),
                      name: nil | binary(),
                      type: binary(),
                      url: nil | binary()
                    }
                  | %Sycophant.Message.Content.Thinking{
                      __type__: binary(),
                      id: nil | binary(),
                      signature: nil | binary(),
                      summary: nil | binary(),
                      text: nil | binary(),
                      type: binary()
                    }
                  | %Sycophant.Message.Content.RedactedThinking{
                      __type__: binary(),
                      data: binary(),
                      type: binary()
                    }
                ],
            metadata: any(),
            role: :user | :assistant | :system | :tool_result,
            tool_call_id: nil | binary(),
            tool_calls:
              nil
              | [
                  %Sycophant.ToolCall{
                    __type__: binary(),
                    arguments: any(),
                    id: binary(),
                    metadata: any(),
                    name: binary()
                  }
                ],
            wire_protocol:
              nil
              | :anthropic_messages
              | :openai_completions
              | :openai_responses
              | :bedrock_converse
              | :google_gemini
          }
        ],
        params: any(),
        stream: nil | any(),
        tools: [any()]
      },
  finish_reason: nil | binary(),
  metadata: any(),
  model: nil | binary(),
  object: nil | any(),
  raw: nil | any(),
  reasoning:
    nil
    | %Sycophant.Reasoning{
        __type__: binary(),
        content: [
          %Sycophant.Message.Content.Thinking{
            __type__: binary(),
            id: nil | binary(),
            signature: nil | binary(),
            summary: nil | binary(),
            text: nil | binary(),
            type: binary()
          }
        ],
        encrypted_content: nil | binary(),
        id: nil | binary()
      },
  text: nil | binary(),
  tool_calls: [
    %Sycophant.ToolCall{
      __type__: binary(),
      arguments: any(),
      id: binary(),
      metadata: any(),
      name: binary()
    }
  ],
  usage:
    nil
    | %Sycophant.Usage{
        __type__: binary(),
        cache_creation_input_tokens: nil | integer(),
        cache_read_cost: nil | float(),
        cache_read_input_tokens: nil | integer(),
        cache_write_cost: nil | float(),
        input_cost: nil | float(),
        input_tokens: nil | integer(),
        output_cost: nil | float(),
        output_tokens: nil | integer(),
        pricing:
          nil
          | %Sycophant.Pricing{
              __type__: binary(),
              components: [
                %Sycophant.Pricing.Component{
                  __type__: binary(),
                  id: nil | binary(),
                  kind: nil | binary(),
                  meter: nil | binary(),
                  notes: nil | binary(),
                  per: nil | integer(),
                  rate: nil | number(),
                  size_class: nil | binary(),
                  tool: nil | binary(),
                  unit: nil | binary()
                }
              ],
              currency: nil | binary()
            },
        reasoning_cost: nil | float(),
        reasoning_tokens: nil | integer(),
        total_cost: nil | float()
      }
}

Functions

messages(response)

@spec messages(t()) :: [Sycophant.Message.t()]

Returns the full conversation message history from the response context.

The list includes all user, assistant, system, and tool result messages exchanged during the conversation.

reasoning_text(arg1)

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

Returns the first reasoning content text, if present.

t()

text(response)

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

Returns the response text.