riffer 0.43.0 → 0.45.0

data/lib/riffer/files/resolver.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "digest"
+require "base64"
+
+class Riffer::Files::Resolver
+  # @rbs @provider: Riffer::Providers::Base
+  # @rbs @config: Riffer::Config::Files
+
+  #: (provider: Riffer::Providers::Base) -> void
+  def initialize(provider:)
+    @provider = provider
+    @config = Riffer.config.files
+  end
+
+  # Resolves every file in every User message in place - downloading,
+  # verifying, and caching as the provider's capability and each file's
+  # sha256 require.  Raises Riffer::FileError on any file that can't be
+  # resolved
+  #: (Array[Riffer::Messages::Base]) -> void
+  def resolve!(messages)
+    files = messages.flat_map do |message|
+      next [] unless message.is_a?(Riffer::Messages::User)
+
+      check_file_count!(message)
+      message.files
+    end
+
+    @config.runner.map(files, context: nil) { |file| resolve_file!(file) }
+  end
+
+  private
+
+  #: (Riffer::Messages::User) -> void
+  def check_file_count!(message)
+    max = @config.max_per_message
+    return if max.nil? || message.files.size <= max
+
+    raise Riffer::TooManyFilesError, "Too many files specified in user message"
+  end
+
+  #: (Riffer::Messages::FilePart) -> void
+  def resolve_file!(file)
+    delivery = @provider.file_delivery(file)
+    if delivery == :unsupported
+      raise Riffer::FileUnsupportedError,
+            "Provider does not support user message file attachments"
+    end
+    return verify_inline!(file) if file.inline_data?
+
+    case delivery
+    when :url
+      download!(file, cache: false) if file.sha256
+    when :base64
+      file.data ? verify_inline!(file) : download!(file, cache: :base64)
+    when :bytes
+      file.data_bytes ? verify_inline!(file) : download!(file, cache: :bytes)
+    else
+      raise Riffer::ArgumentError,
+            "Unknown file_delivery result #{delivery.inspect} from #{@provider.class}"
+    end
+  end
+
+  #: (Riffer::Messages::FilePart) -> void
+  def verify_inline!(file)
+    return unless file.sha256
+
+    verify_bytes!(file.data_bytes, file.sha256)
+  end
+
+  # +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
+  def download!(file, cache:)
+    raise Riffer::FileDownloadsDisabledError, "File attachments are disabled" unless @config.allow_downloads
+
+    raw = @config.downloader.call(file.url, max_bytes: @config.max_bytes, timeout: @config.timeout)
+    verify_bytes!(raw, file.sha256) if file.sha256
+
+    case cache
+    when :base64
+      file.cache_downloaded_data(Base64.strict_encode64(raw))
+    when :bytes
+      file.cache_data_bytes(raw)
+    when false
+      nil
+    end
+  end
+
+  def verify_bytes!(bytes, sha256)
+    return if Digest::SHA256.hexdigest(bytes) == sha256
+
+    raise Riffer::FileChecksumMismatchError, "File checksum mismatch"
+  end
+end

data/lib/riffer/files.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Riffer::Files
+end

data/lib/riffer/helpers/identifier.rb

@@ -29,13 +29,21 @@ module Riffer::Helpers::Identifier
     cached = klass.instance_variable_get(:@derived_identifier) #: String?
     return cached if cached
 
-    # Tool classes shadow Module#name with the identifier DSL, so the real
-    # class-path name must come from Module's own implementation.
-    real_name = Module.instance_method(:name).bind_call(klass) #: String?
+    real_name = real_name(klass)
     return "" if real_name.nil?
 
     derived = derive(real_name)
     klass.instance_variable_set(:@derived_identifier, derived)
     derived
   end
+
+  # Returns the class-path name of a class or module, or +nil+ when anonymous.
+  # Tool classes shadow Module#name with the identifier DSL, so the real name
+  # must come from Module's own implementation.
+  #
+  #--
+  #: (Module) -> String?
+  def real_name(klass)
+    Module.instance_method(:name).bind_call(klass) #: String?
+  end
 end

data/lib/riffer/messages/file_part.rb

@@ -8,6 +8,9 @@ require "uri"
 # raw base64 data (+new+).
 class Riffer::Messages::FilePart
   # @rbs @url_string: String?
+  # @rbs @data: String?
+  # @rbs @downloaded_data: String?
+  # @rbs @data_bytes: String?
 
   MEDIA_TYPES = {
     ".jpg" => "image/jpeg",
@@ -23,6 +26,7 @@ class Riffer::Messages::FilePart
   }.freeze #: Hash[String, String]
 
   SUPPORTED_MEDIA_TYPES = MEDIA_TYPES.values.uniq.freeze #: Array[String]
+  SHA256_PATTERN = /\A[0-9a-f]{64}\z/i #: Regexp
 
   # The MIME type of the file.
   attr_reader :media_type #: String
@@ -30,17 +34,25 @@ class Riffer::Messages::FilePart
   # The filename, if available.
   attr_reader :filename #: String?
 
+  # The expected SHA-256 of the file contents, if the caller supplied one.
+  attr_reader :sha256 #: String?
+
   # Raises Riffer::ArgumentError unless +data+ or +url+ is given and
   # +media_type+ is supported.
   #--
-  #: (media_type: String, ?data: String?, ?filename: String?, ?url: String?) -> void
-  def initialize(media_type:, data: nil, filename: nil, url: nil)
+  #: (media_type: String, ?data: String?, ?filename: String?, ?url: String?, ?sha256: String?) -> void
+  def initialize(media_type:, data: nil, filename: nil, url: nil, sha256: nil)
     raise Riffer::ArgumentError, "Either data or url must be provided" if data.nil? && url.nil?
     unless SUPPORTED_MEDIA_TYPES.include?(media_type)
       raise Riffer::ArgumentError,
             "Unsupported media type: #{media_type}"
     end
+    unless sha256.nil? || (sha256.is_a?(String) && sha256.match?(SHA256_PATTERN))
+      raise Riffer::ArgumentError,
+            "Invalid sha256: #{sha256}"
+    end
 
+    @sha256 = sha256&.downcase
     @data = data
     @media_type = media_type
     @filename = filename
@@ -50,15 +62,15 @@ class Riffer::Messages::FilePart
   # Creates a FilePart from a URL, detecting +media_type+ from the path
   # extension when omitted. Raises Riffer::ArgumentError if it can't be detected.
   #--
-  #: (String, ?media_type: String?) -> Riffer::Messages::FilePart
-  def self.from_url(url, media_type: nil)
+  #: (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::FilePart
+  def self.from_url(url, media_type: nil, filename: nil, sha256: nil)
     unless media_type
       ext = ::File.extname(URI.parse(url).path.to_s).downcase
       media_type = MEDIA_TYPES[ext]
       raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" unless media_type
     end
 
-    new(url: url, media_type: media_type)
+    new(url: url, media_type: media_type, filename: filename, sha256: sha256)
   end
 
   # Builds a FilePart from a +{url:, media_type:}+ or +{data:, media_type:}+ hash,
@@ -75,18 +87,57 @@ class Riffer::Messages::FilePart
     data = file[:data]
     media_type = file[:media_type]
     filename = file[:filename]
+    sha256 = file[:sha256]
 
     if url
-      from_url(url, media_type: media_type)
+      from_url(url, media_type: media_type, filename: filename, sha256: sha256)
     elsif data && media_type
-      new(data: data, media_type: media_type, filename: filename)
+      new(data: data, media_type: media_type, filename: filename, sha256: sha256)
     else
       raise Riffer::ArgumentError, "File hash must include :url or :data with :media_type"
     end
   end
 
-  # Returns the base64-encoded data, or nil for URL-only sources.
-  attr_reader :data #: String?
+  # The base64-encoded contents - caller-supplied, or filled in by the file
+  # resolver after a download.  Nil for a URL source riffer hasn't fetched.
+  #--
+  #: () -> String?
+  def data
+    @data || @downloaded_data
+  end
+
+  #: () -> String?
+  def data_bytes
+    return @data_bytes if @data_bytes
+
+    encoded = data
+    return nil unless encoded
+
+    @data_bytes = Base64.strict_decode64(encoded.gsub(/\s/, ""))
+  rescue ArgumentError
+    raise Riffer::FileEncodingError, "Invalid base64 data"
+  end
+
+  #: (String) -> void
+  def cache_data_bytes(bytes)
+    @data_bytes = bytes
+  end
+
+  # Whether data was supplied directly, as opposed to filled in later by the
+  # file resolver after a download
+  #: () -> bool
+  def inline_data?
+    !@data.nil?
+  end
+
+  # Caches bytes fetched for a URL source.  Deliberately absent from +to_h+:
+  # the agent loop re-sends history on every turn, so the cache saves refreshing
+  # the same file, while persisted history stays free of megabytes of base64
+  #--
+  #: (String) -> void
+  def cache_downloaded_data(data)
+    @downloaded_data = data
+  end
 
   # Returns the URL if the source was a URL, nil otherwise.
   #
@@ -129,6 +180,7 @@ class Riffer::Messages::FilePart
     hash[:data] = @data if @data
     hash[:url] = @url_string if @url_string
     hash[:filename] = filename if filename
+    hash[:sha256] = sha256 if sha256
     hash
   end
 end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -17,6 +17,9 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     "tool_use" => :tool_calls,
     "guardrail_intervened" => :content_filter,
     "content_filtered" => :content_filter,
+    "malformed_model_output" => :malformed_output,
+    "malformed_tool_use" => :malformed_output,
+    "model_context_window_exceeded" => :context_window,
   }.freeze #: Hash[String, Symbol]
 
   # Returns the skill adapter for the Bedrock model — XML for Anthropic models
@@ -43,6 +46,12 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     depends_on "aws-sdk-bedrockruntime"
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(file)
+    file.url&.start_with?("s3://") ? :url : :bytes
+  end
+
   private
 
   #--
@@ -413,13 +422,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def convert_file_part_to_bedrock_format(file)
     format = bedrock_format(file.media_type)
 
-    source = if file.data
-               { bytes: Base64.decode64(file.data) }
-             elsif file.url&.start_with?("s3://")
-               { s3_location: { uri: file.url } }
-             else
-               raise Riffer::ArgumentError, "Amazon Bedrock only supports S3 URI or base64 data file sources"
-             end
+    source = file.data_bytes ? { bytes: file.data_bytes } : { s3_location: { uri: file.url } }
 
     if file.image?
       { image: { format: format, source: source } }

data/lib/riffer/providers/anthropic.rb

@@ -12,6 +12,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     "max_tokens" => :length,
     "tool_use" => :tool_calls,
     "refusal" => :content_filter,
+    "model_context_window_exceeded" => :context_window,
+    # A paused server-tool turn resumes only by re-sending the response; the
+    # agent loop does not do that, so it has no normalized equivalent.
+    "pause_turn" => :other,
   }.freeze #: Hash[String, Symbol]
 
   # Returns the XML skill adapter for Anthropic/Claude.

data/lib/riffer/providers/base.rb

@@ -48,6 +48,7 @@ class Riffer::Providers::Base
     @current_model = model
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
+    Riffer::Files::Resolver.new(provider: self).resolve!(messages)
     messages = merge_consecutive_messages(messages)
     params = build_request_params(messages, model, options)
 
@@ -84,6 +85,7 @@ class Riffer::Providers::Base
     @current_model = model
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
+    Riffer::Files::Resolver.new(provider: self).resolve!(messages)
     messages = merge_consecutive_messages(messages)
     params = build_request_params(messages, model, options)
 
@@ -102,6 +104,12 @@ class Riffer::Providers::Base
     end
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(_file)
+    :url
+  end
+
   private
 
   #: (String) -> true

data/lib/riffer/providers/finish_reason.rb

@@ -5,7 +5,7 @@
 # wire value. +reason+ carries the same meaning for every provider.
 class Riffer::Providers::FinishReason
   # The normalized vocabulary every provider maps into.
-  VALUES = %i[stop length tool_calls content_filter error other].freeze #: Array[Symbol]
+  VALUES = %i[stop length tool_calls content_filter context_window malformed_output error other].freeze #: Array[Symbol]
 
   # The normalized reason.
   attr_reader :reason #: Symbol

data/lib/riffer/providers/gemini.rb

@@ -17,7 +17,16 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     "PROHIBITED_CONTENT" => :content_filter,
     "SPII" => :content_filter,
     "IMAGE_SAFETY" => :content_filter,
-    "MALFORMED_FUNCTION_CALL" => :error,
+    "IMAGE_PROHIBITED_CONTENT" => :content_filter,
+    "IMAGE_RECITATION" => :content_filter,
+    "LANGUAGE" => :content_filter,
+    "MALFORMED_FUNCTION_CALL" => :malformed_output,
+    "UNEXPECTED_TOOL_CALL" => :malformed_output,
+    "NO_IMAGE" => :error,
+    "TOO_MANY_TOOL_CALLS" => :other,
+    "OTHER" => :other,
+    "IMAGE_OTHER" => :other,
+    "FINISH_REASON_UNSPECIFIED" => :other,
   }.freeze #: Hash[String, Symbol]
 
   # The GenAI semconv well-known provider name.
@@ -27,6 +36,12 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     "gcp.gemini"
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(_file)
+    :base64
+  end
+
   private
 
   #--
@@ -274,11 +289,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   #--
   #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_gemini_format(file)
-    if file.url?
-      raise Riffer::ArgumentError,
-            "Gemini provider does not support URL-based file references. Provide base64-encoded data instead."
-    end
-
     { inlineData: { mimeType: file.media_type, data: file.data } }
   end
 

data/lib/riffer/providers/open_ai.rb

@@ -5,6 +5,21 @@
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_preview" #: String
 
+  # The Responses API has no finish_reason field. The response +status+ is
+  # the primary signal; an +incomplete+ status is only meaningful together
+  # with <tt>incomplete_details.reason</tt>, so that branch nests one level.
+  FINISH_REASONS = {
+    "completed" => :stop,
+    "incomplete" => {
+      "max_output_tokens" => :length,
+      "content_filter" => :content_filter,
+    },
+    "failed" => :error,
+    "cancelled" => :other,
+    "in_progress" => :other,
+    "queued" => :other,
+  }.freeze #: Hash[String, Symbol | Hash[String, Symbol]]
+
   # The GenAI semconv well-known provider name.
   #--
   #: () -> String
@@ -19,6 +34,12 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     depends_on "openai"
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(file)
+    file.image? ? :url : :base64
+  end
+
   private
 
   #--
@@ -127,40 +148,32 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     build_finish_reason(response)
   end
 
-  # The Responses API reports no finish_reason field, so one is derived.
   #--
   #: (untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason(response)
     typed_response = response #: OpenAI::Models::Responses::Response
-    status = typed_response.status
+    status = typed_response.status&.to_s
     return nil unless status
 
-    case status.to_sym
-    when :completed
-      reason = extract_tool_calls(typed_response).empty? ? :stop : :tool_calls
-      Riffer::Providers::FinishReason.new(reason: reason, raw: "completed")
-    when :incomplete
-      incomplete_finish_reason(typed_response)
-    when :failed
-      Riffer::Providers::FinishReason.new(reason: :error, raw: "failed")
-    else
-      Riffer::Providers::FinishReason.new(reason: :other, raw: status.to_s)
-    end
+    detail = finish_detail(typed_response, status)
+    mapping = FINISH_REASONS.fetch(status, :other)
+    reason = mapping.is_a?(Hash) ? mapping.fetch(detail.to_s, :other) : mapping
+    # A completed response signals tool use only through its output items.
+    reason = :tool_calls if reason == :stop && !extract_tool_calls(typed_response).empty?
+
+    Riffer::Providers::FinishReason.new(reason: reason, raw: detail || status)
   end
 
+  # The nested field that names the cause behind an ambiguous status.
   #--
-  #: (untyped) -> Riffer::Providers::FinishReason
-  def incomplete_finish_reason(response)
+  #: (untyped, String) -> String?
+  def finish_detail(response, status)
     typed_response = response #: OpenAI::Models::Responses::Response
-    raw = typed_response.incomplete_details&.reason&.to_s
 
-    reason = case raw
-             when "max_output_tokens" then :length
-             when "content_filter" then :content_filter
-             else :other
-             end
-
-    Riffer::Providers::FinishReason.new(reason: reason, raw: raw || "incomplete")
+    case status
+    when "incomplete" then typed_response.incomplete_details&.reason&.to_s
+    when "failed" then typed_response.error&.code&.to_s
+    end
   end
 
   #--

data/lib/riffer/providers/open_router.rb

@@ -33,6 +33,12 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     depends_on "openai"
   end
 
+  #--
+  #: (Riffer::Messages::FilePart) -> Symbol
+  def file_delivery(file)
+    file.image? ? :url : :base64
+  end
+
   private
 
   #--
@@ -127,18 +133,30 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   #: (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason(response)
     typed_response = response #: OpenAI::Models::Chat::ChatCompletion
-    build_finish_reason(typed_response.choices.first&.finish_reason)
+    choice = typed_response.choices.first
+    build_finish_reason(choice&.finish_reason, native: native_finish_reason(choice))
   end
 
+  # +native+ is the upstream model's own finish reason, which OpenRouter
+  # reports alongside its normalized one; it wins as +raw+ when present.
   #--
-  #: (untyped) -> Riffer::Providers::FinishReason?
-  def build_finish_reason(finish_reason)
+  #: (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
+  def build_finish_reason(finish_reason, native: nil)
     return nil unless finish_reason
 
-    raw = finish_reason.to_s
-    return nil if raw.empty?
+    normalized = finish_reason.to_s
+    return nil if normalized.empty?
 
-    Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(raw, :other), raw: raw)
+    raw = native.to_s.empty? ? normalized : native.to_s
+    Riffer::Providers::FinishReason.new(reason: FINISH_REASONS.fetch(normalized, :other), raw: raw)
+  end
+
+  # +native_finish_reason+ is outside the OpenAI schema, so it is only
+  # reachable through the SDK model's raw data hash.
+  #--
+  #: (untyped) -> untyped
+  def native_finish_reason(choice)
+    choice && choice.to_h[:native_finish_reason]
   end
 
   #--
@@ -181,6 +199,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
       reasoning: +"",
       tool_calls: {},
       finish_reason: nil,
+      native_finish_reason: nil,
     } #: Hash[Symbol, untyped]
 
     # Use stream_raw (not stream) — the latter yields a higher-level
@@ -205,7 +224,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
 
     yielder << Riffer::StreamEvents::TextDone.new(state[:text]) unless state[:text].empty?
     yielder << Riffer::StreamEvents::ReasoningDone.new(state[:reasoning]) unless state[:reasoning].empty?
-    yield_finish_reason(yielder, build_finish_reason(state[:finish_reason]))
+    yield_finish_reason(yielder, build_finish_reason(state[:finish_reason], native: state[:native_finish_reason]))
   end
 
   #--
@@ -222,6 +241,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     end
 
     state[:finish_reason] = choice.finish_reason if choice&.finish_reason
+    state[:native_finish_reason] = native_finish_reason(choice) || state[:native_finish_reason]
 
     emit_tool_call_done_events(state: state, yielder: yielder) if choice && finish_reason_is_tool_calls?(choice)