riffer 0.47.2 → 0.48.0

data/lib/riffer/agent/run.rb

@@ -10,7 +10,7 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def generate(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     run_loop(agent, tags: tags)
@@ -20,7 +20,7 @@ module Riffer::Agent::Run
   # for prompt/files semantics.
   #
   #--
-  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def stream(agent:, prompt: nil, files: nil, tags: {})
     append_user_message(agent, prompt, files: files)
     # The enumerator body runs in its own fiber, where the fiber-local OTEL
@@ -36,16 +36,17 @@ module Riffer::Agent::Run
   private
 
   # Both +generate+ and +stream+ funnel here, so this is the single place raw
-  # +tags+ are normalized. The clean <tt>String => String</tt> map is then
+  # +tags+ are normalized and merged over the default tags (a caller tag wins
+  # on a shared key). The clean <tt>String => String</tt> map is then
   # threaded to every span builder in the run as +riffer.tag.*+ and to each
   # provider call (via +merged_model_options+) for native request-metadata
   # mapping.
   #--
   #: (Riffer::Agent, ?tags: Hash[(String | Symbol), untyped]?, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
   def run_loop(agent, tags: {}, stream_yielder: nil)
-    tags = normalize_tags(tags)
+    tags = default_tags(agent).merge(normalize_tags(tags))
     Riffer::Tracing.in_span(
-      "invoke_agent #{agent.class.identifier}",
+      "invoke_agent #{agent.identifier}",
       attributes: run_span_attributes(agent, tags),
       kind: :internal,
     ) do |span|
@@ -153,6 +154,7 @@ module Riffer::Agent::Run
   def accumulate_streamed_response(agent, stream_yielder, tags = {})
     accumulated_content = +""
     accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
+    accumulated_reasoning = [] #: Array[Riffer::Messages::Assistant::ReasoningPart]
     accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
     accumulated_finish_reason = nil #: Symbol?
     accumulated_finish_reason_raw = nil #: String?
@@ -175,6 +177,8 @@ module Riffer::Agent::Run
           name: event.name,
           arguments: event.arguments,
         )
+      when Riffer::StreamEvents::ReasoningDone
+        accumulated_reasoning << event.part
       when Riffer::StreamEvents::TokenUsageDone
         accumulated_token_usage = event.token_usage
       when Riffer::StreamEvents::FinishReasonDone
@@ -186,6 +190,7 @@ module Riffer::Agent::Run
     Riffer::Messages::Assistant.new(
       accumulated_content,
       tool_calls: accumulated_tool_calls,
+      reasoning: accumulated_reasoning,
       token_usage: accumulated_token_usage,
       finish_reason: accumulated_finish_reason,
       finish_reason_raw: accumulated_finish_reason_raw,
@@ -228,6 +233,7 @@ module Riffer::Agent::Run
       message&.content || "",
       outcome: final_outcome(message, result, interrupted: interrupted, interrupt_reason: interrupt_reason),
       modifications: all_modifications,
+      reasoning: message&.reasoning || [],
       structured_output: result&.object,
       **extra,
     )
@@ -381,6 +387,13 @@ module Riffer::Agent::Run
     opts
   end
 
+  # The tags riffer adds to every run, identifying the agent it's on behalf of.
+  #--
+  #: (Riffer::Agent) -> Hash[String, String]
+  def default_tags(agent)
+    { "kind" => "agent", "agent" => agent.identifier }
+  end
+
   #--
   #: (
   #    Riffer::Agent,
@@ -388,6 +401,7 @@ module Riffer::Agent::Run
   #    outcome: Riffer::Agent::Outcome,
   #    ?tripwire: Riffer::Guardrails::Tripwire?,
   #    ?modifications: Array[Riffer::Guardrails::Modification],
+  #    ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #    ?structured_output: Hash[Symbol, untyped]?,
   #    ?healed_tool_call_ids: Array[String],
   #    ?token_usage: Riffer::Providers::TokenUsage?,
@@ -399,6 +413,7 @@ module Riffer::Agent::Run
     outcome:,
     tripwire: nil,
     modifications: [],
+    reasoning: [],
     structured_output: nil,
     healed_tool_call_ids: [],
     token_usage: nil,
@@ -410,6 +425,7 @@ module Riffer::Agent::Run
       outcome: outcome,
       tripwire: tripwire,
       modifications: modifications,
+      reasoning: reasoning,
       structured_output: structured_output,
       messages: messages.frozen? ? messages : messages.dup.freeze,
       healed_tool_call_ids: healed_tool_call_ids,
@@ -421,12 +437,12 @@ module Riffer::Agent::Run
   # Raises when +files+ are supplied without a +prompt+ — the provider needs
   # text to anchor the attachments.
   #--
-  #: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> void
+  #: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?) -> void
   def append_user_message(agent, prompt, files: nil)
     raise Riffer::ArgumentError, "files: requires a prompt" if files && !files.empty? && prompt.nil?
     return unless prompt
 
-    file_parts = (files || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
+    file_parts = (files || []).map { |f| Riffer::Messages::User::FilePart.from_hash(f) }
     agent.session.add(Riffer::Messages::User.new(prompt, files: file_parts), silent: true)
   end
 
@@ -451,7 +467,7 @@ module Riffer::Agent::Run
   def run_span_attributes(agent, tags = {})
     {
       "gen_ai.operation.name" => "invoke_agent",
-      "gen_ai.agent.name" => agent.class.identifier,
+      "gen_ai.agent.name" => agent.identifier,
       "gen_ai.provider.name" => agent.provider.class.semconv_provider_name,
       "gen_ai.request.model" => agent.model_name,
     }.merge(tag_attributes(tags))

data/lib/riffer/agent/session.rb

@@ -201,6 +201,7 @@ class Riffer::Agent::Session
         attrs.fetch(:content, old.content),
         id: attrs.fetch(:id, old.id),
         tool_calls: attrs.fetch(:tool_calls, old.tool_calls),
+        reasoning: attrs.fetch(:reasoning, old.reasoning),
         token_usage: attrs.fetch(:token_usage, old.token_usage),
         structured_output: attrs.fetch(:structured_output, old.structured_output),
         finish_reason: attrs.fetch(:finish_reason, old.finish_reason),

data/lib/riffer/agent.rb

@@ -28,6 +28,19 @@ class Riffer::Agent
     @config ||= Riffer::Agent::Config.new
   end
 
+  # +identifier+ is cleared because it is configuration here but identity on the
+  # subclass; two classes claiming one raise Riffer::DuplicateIdentifierError at
+  # the next registry lookup.
+  #--
+  #: (Class) -> void
+  def self.inherited(subclass)
+    super
+    copy = config.dup
+    copy.identifier = nil
+    subclass.instance_variable_set(:@config, copy)
+  end
+  private_class_method :inherited
+
   # Gets or sets the agent identifier.
   #
   #--
@@ -148,14 +161,14 @@ class Riffer::Agent
 
   # Generates a response using a new agent instance.
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def self.generate(prompt = nil, files: nil, context: nil, tags: {})
     new(context: context).generate(prompt, files: files, tags: tags)
   end
 
   # Streams a response using a new agent instance.
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def self.stream(prompt = nil, files: nil, context: nil, tags: {})
     new(context: context).stream(prompt, files: files, tags: tags)
   end
@@ -284,6 +297,16 @@ class Riffer::Agent
     @session.set(Riffer::Agent::Session::Repair.prune_orphans(@session.messages))
   end
 
+  # The identifier for this agent: the instance config's identifier when set
+  # (e.g. an agent restored with +Riffer::Agent.from_h+), otherwise the class
+  # identifier.
+  #
+  #--
+  #: () -> String
+  def identifier
+    config.identifier || self.class.identifier
+  end
+
   # Generates a response from the agent.
   #
   # With +prompt+, a new user message is appended (silently — +on_message+ does
@@ -296,10 +319,11 @@ class Riffer::Agent
   # are stamped as +riffer.tag.*+ on every span the call emits. See
   # +docs/AGENTS.md+ for the per-provider mapping. The reserved key
   # +user_id+ also maps to the provider's native user identifier where one
-  # exists.
+  # exists. Riffer adds the default tags +kind+ (+"agent"+) and +agent+ (the
+  # agent identifier); a caller tag with the same key wins.
   #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def generate(prompt = nil, files: nil, tags: {})
     Riffer::Agent::Run.generate(agent: self, prompt: prompt, files: files, tags: tags)
   end
@@ -311,7 +335,7 @@ class Riffer::Agent
   # Raises Riffer::ArgumentError if structured output is configured.
   #
   #--
-  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def stream(prompt = nil, files: nil, tags: {})
     if @structured_output
       raise Riffer::ArgumentError,

data/lib/riffer/config.rb

@@ -115,7 +115,7 @@ class Riffer::Config
     end
   end
 
-  # File-attachment-download policy for +Riffer::Messages::FilePart+ URL sources
+  # File-attachment-download policy for +Riffer::Messages::User::FilePart+ URL sources
   class Files
     # Allow file attachments to be downloaded to send to providers.
     attr_reader :allow_downloads #: bool # @dynamic allow_downloads

data/lib/riffer/evals/evaluator.rb

@@ -15,8 +15,12 @@ class Riffer::Evals::Evaluator
   # @rbs self.@instructions: String?
   # @rbs self.@higher_is_better: bool?
   # @rbs self.@judge_model: String?
+  # @rbs self.@identifier: String?
   # @rbs @judge: Riffer::Evals::Judge?
 
+  # The identifier for an anonymous evaluator class.
+  DEFAULT_IDENTIFIER = "riffer/judge" #: String
+
   class << self
     # Gets or sets the evaluation instructions (criteria and scoring rubric).
     #
@@ -51,6 +55,28 @@ class Riffer::Evals::Evaluator
 
       @judge_model = value.to_s
     end
+
+    # Gets or sets the evaluator identifier, sent as the +agent+ tag on judge
+    # calls. Defaults to the snake_cased class name, or DEFAULT_IDENTIFIER for
+    # an anonymous class.
+    #
+    #--
+    #: (?String?) -> String
+    def identifier(value = nil)
+      return @identifier = value.to_s if value
+
+      @identifier || derived_identifier
+    end
+
+    private
+
+    # Anonymous classes derive an empty identifier.
+    #--
+    #: () -> String
+    def derived_identifier
+      derived = Riffer::Helpers::Identifier.for(self)
+      derived.empty? ? DEFAULT_IDENTIFIER : derived
+    end
   end
 
   # Evaluates an input/output pair. The default calls the judge with the
@@ -94,7 +120,8 @@ class Riffer::Evals::Evaluator
 
   protected
 
-  # Returns a Judge instance configured for this evaluator.
+  # Returns a Judge instance configured for this evaluator. Its calls carry
+  # the +kind+ (+"judge"+) and +agent+ (the evaluator identifier) tags.
   #
   #--
   #: () -> Riffer::Evals::Judge
@@ -106,7 +133,7 @@ class Riffer::Evals::Evaluator
               "No judge model configured. Set judge_model on the evaluator or Riffer.config.evals.judge_model"
       end
 
-      Riffer::Evals::Judge.new(model: model)
+      Riffer::Evals::Judge.new(model: model, tags: { "kind" => "judge", "agent" => self.class.identifier })
     end
   end
 

data/lib/riffer/evals/judge.rb

@@ -30,16 +30,20 @@ class Riffer::Evals::Judge
   # The model string (provider/model format).
   attr_reader :model #: String # @dynamic model
 
+  # The tags passed to the provider on every call.
+  attr_reader :tags #: Hash[String, String] # @dynamic tags
+
   # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   #--
-  #: (model: String) -> void
-  def initialize(model:)
+  #: (model: String, ?tags: Hash[String, String]) -> void
+  def initialize(model:, tags: {})
     provider_name, model_name = model.split("/", 2)
     unless [provider_name, model_name].all? { |part| part.is_a?(String) && !part.strip.empty? }
       raise Riffer::ArgumentError, "Invalid model string: #{model}"
     end
 
     @model = model
+    @tags = tags
   end
 
   # Evaluates an input/output pair using the configured LLM.
@@ -49,12 +53,14 @@ class Riffer::Evals::Judge
     system_message = build_system_message(instructions)
     user_message = build_user_message(input: input, output: output, ground_truth: ground_truth)
 
-    response = provider_instance.generate_text(
+    options = {
       system: system_message,
       prompt: user_message,
       model: model_name,
       tools: [EvaluationTool],
-    )
+    } #: Hash[Symbol, untyped]
+    options[:tags] = tags unless tags.empty?
+    response = provider_instance.generate_text(**options)
 
     parse_tool_response(response)
   end
@@ -111,7 +117,7 @@ class Riffer::Evals::Judge
   def parse_tool_response(response)
     tool_call = response.tool_calls.fetch(0) { raise Riffer::Error, "Invalid judge response: no tool call found" }
 
-    parsed = JSON.parse(tool_call[:arguments], symbolize_names: true)
+    parsed = JSON.parse(tool_call.arguments, symbolize_names: true)
     score = parsed[:score]
     reason = parsed[:reason]
 

data/lib/riffer/files/resolver.rb

@@ -40,7 +40,7 @@ class Riffer::Files::Resolver
     raise Riffer::TooManyFilesError, "Too many files specified in user message"
   end
 
-  #: (Riffer::Messages::FilePart) -> void
+  #: (Riffer::Messages::User::FilePart) -> void
   def resolve_file!(file)
     delivery = @provider.file_delivery(file)
     if delivery == :unsupported
@@ -62,7 +62,7 @@ class Riffer::Files::Resolver
     end
   end
 
-  #: (Riffer::Messages::FilePart) -> void
+  #: (Riffer::Messages::User::FilePart) -> void
   def verify_inline!(file)
     return unless file.sha256
 
@@ -72,7 +72,7 @@ class Riffer::Files::Resolver
   # +cache:+ is false for a :url-delivery provider verifying a sha256 — the
   # request still sends the URL, never the downloaded bytes, so caching them
   # would hold memory nothing reads and let later turns skip re-verifying.
-  #: (Riffer::Messages::FilePart, cache: (false | Symbol)) -> void
+  #: (Riffer::Messages::User::FilePart, cache: (false | Symbol)) -> void
   def download!(file, cache:)
     raise Riffer::FileDownloadsDisabledError, "File attachments are disabled" unless @config.allow_downloads
 

data/lib/riffer/helpers/deep_dup.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Copying for the nested Hashes and Arrays a configuration object holds.
+module Riffer::Helpers::DeepDup
+  extend self
+
+  # Returns +value+ with every Hash and Array rebuilt, so a copy shares no
+  # collection with its source.
+  #
+  # Anything else is returned as-is, which a Class or a Proc needs: +Class#dup+
+  # answers a new anonymous class. One source collection maps to one copy, so
+  # references shared within +value+ stay shared in the result — an +:around+
+  # guardrail registered under two phases is still one registration afterwards.
+  #--
+  #: (untyped) -> untyped
+  def call(value)
+    seen = {} #: Hash[untyped, untyped]
+
+    rebuild(value, seen.compare_by_identity)
+  end
+
+  private
+
+  #--
+  #: (untyped, Hash[untyped, untyped]) -> untyped
+  def rebuild(value, seen)
+    return seen[value] if seen.key?(value)
+
+    case value
+    when Hash
+      copy = seen[value] = {}
+      value.each { |key, entry| copy[key] = rebuild(entry, seen) }
+      copy
+    when Array
+      copy = seen[value] = []
+      value.each { |entry| copy << rebuild(entry, seen) }
+      copy
+    else value
+    end
+  end
+end

data/lib/riffer/messages/assistant/reasoning_part.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Represents one block of model reasoning attached to an assistant message.
+# riffer stores and replays a part verbatim rather than interpreting it, so a
+# provider that requires its own thinking blocks back gets them unchanged.
+class Riffer::Messages::Assistant::ReasoningPart
+  TYPES = %i[text summary encrypted].freeze #: Array[Symbol]
+
+  # What the part carries: readable reasoning (+:text+), a provider-condensed
+  # digest (+:summary+), or an opaque payload (+:encrypted+).
+  attr_reader :type #: Symbol # @dynamic type
+
+  # The reasoning prose, for +:text+ and +:summary+ parts.
+  attr_reader :text #: String? # @dynamic text
+
+  # The opaque payload, for +:encrypted+ parts.
+  attr_reader :data #: String? # @dynamic data
+
+  # The provider's signature over the part, when it issues one.
+  attr_reader :signature #: String? # @dynamic signature
+
+  # The provider's identifier for the part, when it issues one.
+  attr_reader :id #: String? # @dynamic id
+
+  # The wire format of the part, owned by the provider adapter that produced it
+  # (e.g. <tt>"anthropic-claude-v1"</tt>). Adapters replay only the formats they
+  # recognize, so it is never validated here.
+  attr_reader :format #: String? # @dynamic format
+
+  # Builds a ReasoningPart from a hash, or returns +part+ unchanged when it is
+  # already a ReasoningPart.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart)) -> Riffer::Messages::Assistant::ReasoningPart
+  def self.from_hash(part)
+    return part if part.is_a?(Riffer::Messages::Assistant::ReasoningPart)
+
+    new(
+      type: part[:type].to_sym,
+      text: part[:text],
+      data: part[:data],
+      signature: part[:signature],
+      id: part[:id],
+      format: part[:format],
+    )
+  end
+
+  # Raises Riffer::ArgumentError on a +type+ outside TYPES.
+  #--
+  #: (type: Symbol, ?text: String?, ?data: String?, ?signature: String?, ?id: String?, ?format: String?) -> void
+  def initialize(type:, text: nil, data: nil, signature: nil, id: nil, format: nil)
+    unless TYPES.include?(type)
+      raise Riffer::ArgumentError,
+            "type must be one of #{TYPES.inspect}, got #{type.inspect}"
+    end
+
+    @type = type
+    @text = text
+    @data = data
+    @signature = signature
+    @id = id
+    @format = format
+  end
+
+  # Serializes the part to a hash, omitting the fields it doesn't carry.
+  #
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    { type: type, text: text, data: data, signature: signature, id: id, format: format }.compact
+  end
+
+  #--
+  #: (untyped) -> bool
+  def ==(other)
+    other.is_a?(Riffer::Messages::Assistant::ReasoningPart) && to_h == other.to_h
+  end
+
+  #--
+  #: (untyped) -> bool
+  def eql?(other)
+    self == other
+  end
+
+  #--
+  #: () -> Integer
+  def hash
+    to_h.hash
+  end
+end

data/lib/riffer/messages/assistant/tool_call.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Represents one tool invocation the model requested on an assistant message.
+class Riffer::Messages::Assistant::ToolCall
+  # The provider's identifier for the call, echoed back on the tool result.
+  attr_reader :call_id #: String # @dynamic call_id
+
+  # The name of the tool to invoke.
+  attr_reader :name #: String # @dynamic name
+
+  # The JSON-encoded arguments, exactly as the provider emitted them.
+  attr_reader :arguments #: String # @dynamic arguments
+
+  # Builds a ToolCall from a hash, or returns +call+ unchanged when it is
+  # already a ToolCall. Raises Riffer::ArgumentError when the hash is missing
+  # a field.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ToolCall)) -> Riffer::Messages::Assistant::ToolCall
+  def self.from_hash(call)
+    return call if call.is_a?(Riffer::Messages::Assistant::ToolCall)
+
+    if call.values_at(:call_id, :name, :arguments).any?(&:nil?)
+      raise Riffer::ArgumentError, "Tool call hash must include :call_id, :name, and :arguments"
+    end
+
+    new(call_id: call[:call_id], name: call[:name], arguments: call[:arguments])
+  end
+
+  #--
+  #: (call_id: String, name: String, arguments: String) -> void
+  def initialize(call_id:, name:, arguments:)
+    @call_id = call_id
+    @name = name
+    @arguments = arguments
+  end
+
+  # Serializes the call to a hash.
+  #
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    { call_id: call_id, name: name, arguments: arguments }
+  end
+
+  #--
+  #: (untyped) -> bool
+  def ==(other)
+    other.is_a?(Riffer::Messages::Assistant::ToolCall) && to_h == other.to_h
+  end
+
+  #--
+  #: (untyped) -> bool
+  def eql?(other)
+    self == other
+  end
+
+  #--
+  #: () -> Integer
+  def hash
+    to_h.hash
+  end
+end

data/lib/riffer/messages/assistant.rb

@@ -4,11 +4,36 @@
 # Represents an assistant (LLM) message in a conversation; may include tool
 # calls when the LLM requests tool execution.
 class Riffer::Messages::Assistant < Riffer::Messages::Base
-  ToolCall = Struct.new(:call_id, :name, :arguments)
+  # The reasoning part types +reasoning_text+ reads; the rest carry no prose.
+  REASONING_TEXT_TYPES = %i[text summary].freeze #: Array[Symbol]
+
+  # Builds an Assistant message from a hash, or returns +msg+ unchanged when it
+  # is already an Assistant message. Raises Riffer::ArgumentError on an invalid
+  # tool call, reasoning part, or +finish_reason+.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant)) -> Riffer::Messages::Assistant
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::Assistant)
+
+    new(
+      msg[:content],
+      id: msg[:id],
+      tool_calls: (msg[:tool_calls] || []).map { |tc| Riffer::Messages::Assistant::ToolCall.from_hash(tc) },
+      reasoning: (msg[:reasoning] || []).map { |part| Riffer::Messages::Assistant::ReasoningPart.from_hash(part) },
+      token_usage: msg[:token_usage] && Riffer::Providers::TokenUsage.from_hash(msg[:token_usage]),
+      structured_output: msg[:structured_output],
+      finish_reason: msg[:finish_reason]&.to_sym,
+      finish_reason_raw: msg[:finish_reason_raw],
+    )
+  end
 
   # Array of tool calls requested by the assistant.
   attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
 
+  # The model's reasoning blocks for this response, in the order the provider
+  # emitted them.
+  attr_reader :reasoning #: Array[Riffer::Messages::Assistant::ReasoningPart] # @dynamic reasoning
+
   # Token usage data for this response.
   attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
@@ -30,6 +55,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   #    String,
   #    ?id: String?,
   #    ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall],
+  #    ?reasoning: Array[Riffer::Messages::Assistant::ReasoningPart],
   #    ?token_usage: Riffer::Providers::TokenUsage?,
   #    ?structured_output: Hash[Symbol, untyped]?,
   #    ?finish_reason: Symbol?,
@@ -39,6 +65,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     content,
     id: nil,
     tool_calls: [],
+    reasoning: [],
     token_usage: nil,
     structured_output: nil,
     finish_reason: nil,
@@ -51,6 +78,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
 
     super(content, id: id)
     @tool_calls = tool_calls
+    @reasoning = reasoning
     @token_usage = token_usage
     @structured_output = structured_output
     @finish_reason = finish_reason
@@ -75,10 +103,29 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     !@tool_calls.empty?
   end
 
+  #--
+  #: () -> bool
+  def reasoning?
+    !@reasoning.empty?
+  end
+
+  # The readable reasoning across this message's +:text+ and +:summary+ parts,
+  # joined by blank lines, or nil when it carries none.
+  #--
+  #: () -> String?
+  def reasoning_text
+    texts = reasoning.filter_map { |part| part.text if REASONING_TEXT_TYPES.include?(part.type) }
+    texts.empty? ? nil : texts.join("\n\n")
+  end
+
   #--
   #: (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
   def +(other)
-    self.class.new("#{content}\n\n#{other.content}", tool_calls: tool_calls + other.tool_calls)
+    self.class.new(
+      "#{content}\n\n#{other.content}",
+      tool_calls: tool_calls + other.tool_calls,
+      reasoning: reasoning + other.reasoning,
+    )
   end
 
   # Converts the message to a hash.
@@ -89,6 +136,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     hash = { role: role, content: content } #: Hash[Symbol, untyped]
     hash[:id] = id if id
     hash[:tool_calls] = tool_calls.map(&:to_h) unless tool_calls.empty?
+    hash[:reasoning] = reasoning.map(&:to_h) if reasoning?
     hash[:token_usage] = token_usage.to_h if token_usage
     hash[:structured_output] = structured_output if structured_output?
     hash[:finish_reason] = finish_reason if finish_reason