riffer 0.47.2 → 0.49.0

data/lib/riffer/messages/{file_part.rb → user/file_part.rb}

@@ -4,9 +4,7 @@
 require "base64"
 require "uri"
 
-# Represents a file attachment (image or document) — from a URL (+from_url+) or
-# raw base64 data (+new+).
-class Riffer::Messages::FilePart
+class Riffer::Messages::User::FilePart
   # @rbs @url_string: String?
   # @rbs @data: String?
   # @rbs @downloaded_data: String?
@@ -28,17 +26,12 @@ class Riffer::Messages::FilePart
   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 # @dynamic media_type
 
-  # The filename, if available.
   attr_reader :filename #: String? # @dynamic filename
 
-  # The expected SHA-256 of the file contents, if the caller supplied one.
   attr_reader :sha256 #: String? # @dynamic sha256
 
-  # Raises Riffer::ArgumentError unless +data+ or +url+ is given and
-  # +media_type+ is supported.
   #--
   #: (media_type: String, ?data: String?, ?filename: String?, ?url: String?, ?sha256: String?) -> void
   def initialize(media_type:, data: nil, filename: nil, url: nil, sha256: nil)
@@ -59,26 +52,16 @@ class Riffer::Messages::FilePart
     @url_string = url
   end
 
-  # 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?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::FilePart
+  #: (String, ?media_type: String?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::User::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.fetch(ext) { raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" }
-    end
-
-    new(url: url, media_type: media_type, filename: filename, sha256: sha256)
+    new(url: url, media_type: media_type || detect_media_type(url), filename: filename, sha256: sha256)
   end
 
-  # Builds a FilePart from a +{url:, media_type:}+ or +{data:, media_type:}+ hash,
-  # or returns +file+ unchanged when it is already a FilePart. Raises
-  # Riffer::ArgumentError on an invalid hash.
   #--
-  #: ((Hash[Symbol, untyped] | Riffer::Messages::FilePart)) -> Riffer::Messages::FilePart
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::User::FilePart)) -> Riffer::Messages::User::FilePart
   def self.from_hash(file)
-    return file if file.is_a?(Riffer::Messages::FilePart)
+    return file if file.is_a?(Riffer::Messages::User::FilePart)
 
     url = file[:url]
     data = file[:data]
@@ -87,7 +70,7 @@ class Riffer::Messages::FilePart
     sha256 = file[:sha256]
 
     if url
-      from_url(url, media_type: media_type, filename: filename, sha256: sha256)
+      new(url: url, data: data, media_type: media_type || detect_media_type(url), filename: filename, sha256: sha256)
     elsif data && media_type
       new(data: data, media_type: media_type, filename: filename, sha256: sha256)
     else
@@ -95,8 +78,14 @@ class Riffer::Messages::FilePart
     end
   end
 
-  # 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) -> String
+  def self.detect_media_type(url)
+    ext = ::File.extname(URI.parse(url).path.to_s).downcase
+    MEDIA_TYPES.fetch(ext) { raise Riffer::ArgumentError, "Cannot detect media type from URL; provide media_type explicitly" }
+  end
+  private_class_method :detect_media_type
+
   #--
   #: () -> String?
   def data
@@ -120,60 +109,47 @@ class Riffer::Messages::FilePart
     @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.
-  #
   #--
   #: () -> String?
   def url
     @url_string
   end
 
-  # Returns true if the source was a URL.
-  #
   #--
   #: () -> bool
   def url?
     !@url_string.nil?
   end
 
-  # Returns true if the file is an image.
-  #
   #--
   #: () -> bool
   def image?
     media_type.start_with?("image/")
   end
 
-  # Returns true if the file is a document (not an image).
-  #
   #--
   #: () -> bool
   def document?
     !image?
   end
 
-  # Serializes the FilePart to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
     hash = { media_type: media_type } #: Hash[Symbol, untyped]
+    # Downloaded data is left out so persisted history stays free of megabytes
+    # of base64; the in-memory cache still spares refetching on every turn.
     hash[:data] = @data if @data
     hash[:url] = @url_string if @url_string
     hash[:filename] = filename if filename

data/lib/riffer/messages/user.rb

@@ -1,13 +1,20 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a user message in a conversation.
 class Riffer::Messages::User < Riffer::Messages::Base
-  # File attachments for this message.
-  attr_reader :files #: Array[Riffer::Messages::FilePart] # @dynamic files
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::User)) -> Riffer::Messages::User
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::User)
+
+    files = (msg[:files] || []).map { |f| Riffer::Messages::User::FilePart.from_hash(f) }
+    new(msg[:content], id: msg[:id], files: files)
+  end
+
+  attr_reader :files #: Array[Riffer::Messages::User::FilePart] # @dynamic files
 
   #--
-  #: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
+  #: (String, ?id: String?, ?files: Array[Riffer::Messages::User::FilePart]) -> void
   def initialize(content, id: nil, files: [])
     super(content, id: id)
     @files = files

data/lib/riffer/params/boolean.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Sentinel type for declaring boolean parameters — Ruby has no +Boolean+ class
-# (+true+/+false+ are +TrueClass+/+FalseClass+).
-#
-#   required :verbose, Riffer::Params::Boolean
-#
+# Ruby has no +Boolean+ class, so params declare booleans with this sentinel.
 module Riffer::Params::Boolean
 end

data/lib/riffer/params/param.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# A single parameter definition, handling type validation and JSON Schema
-# generation.
 class Riffer::Params::Param
-  # Maps Ruby types to JSON Schema type strings
   TYPE_MAPPINGS = {
     String => "string",
     Integer => "integer",
@@ -16,11 +13,8 @@ class Riffer::Params::Param
     Hash => "object",
   }.freeze #: Hash[Module, String]
 
-  # Primitive types allowed for the <tt>of:</tt> keyword on Array params
   PRIMITIVE_TYPES = (TYPE_MAPPINGS.keys - [Array, Hash]).freeze #: Array[Module]
 
-  # Maps JSON Schema type strings back to Ruby types (inverse of TYPE_MAPPINGS),
-  # collapsing the three boolean spellings onto Riffer::Params::Boolean.
   JSON_TYPE_MAPPINGS = {
     "string" => String,
     "integer" => Integer,
@@ -30,32 +24,22 @@ class Riffer::Params::Param
     "object" => Hash,
   }.freeze #: Hash[String, Module]
 
-  # The parameter name.
   attr_reader :name #: Symbol # @dynamic name
 
-  # The Ruby type.
   attr_reader :type #: Module # @dynamic type
 
-  # Whether the parameter is required.
   attr_reader :required #: bool # @dynamic required
 
-  # The parameter description, if any.
   attr_reader :description #: String? # @dynamic description
 
-  # Allowed values, if constrained.
   attr_reader :enum #: Array[untyped]? # @dynamic enum
 
-  # The default value, if any.
   attr_reader :default #: untyped # @dynamic default
 
-  # Element type for a typed array (+of:+).
   attr_reader :item_type #: Module? # @dynamic item_type
 
-  # Nested Params for object / array-of-object types.
   attr_reader :nested_params #: Riffer::Params? # @dynamic nested_params
 
-  # Reconstructs a Param from a single JSON Schema property. Raises
-  # Riffer::ArgumentError on a type outside the Params-expressible subset.
   #--
   #: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
   def self.from_json_schema(name, schema, required:)
@@ -88,9 +72,6 @@ class Riffer::Params::Param
   end
   private_class_method :resolve_nesting
 
-  # Resolves a JSON Schema +type+ (or a <tt>[type, "null"]</tt> union) to its
-  # Ruby type. Returns a Module — Riffer::Params::Boolean is a Module, not a
-  # Class. Raises Riffer::ArgumentError on an unsupported type.
   #--
   #: (untyped) -> Module
   def self.json_type_to_ruby(type)
@@ -112,8 +93,6 @@ class Riffer::Params::Param
     @nested_params = nested_params
   end
 
-  # Validates that a value matches the expected type.
-  #
   #--
   #: (untyped) -> bool
   def valid_type?(value)
@@ -128,28 +107,20 @@ class Riffer::Params::Param
     end
   end
 
-  # Returns the JSON Schema type name for this parameter.
-  #
   #--
   #: () -> String
   def type_name
     TYPE_MAPPINGS[type] || type.to_s.downcase
   end
 
-  # Converts this parameter to JSON Schema format. When +strict+, optional
-  # params are made nullable (<tt>["type", "null"]</tt>) so strict providers
-  # distinguish absent from present; optional params with an +enum+ use +anyOf+
-  # instead, since providers like Anthropic reject
-  # <tt>{"type": ["string", "null"], "enum": [...]}</tt>. Raises
-  # Riffer::ArgumentError when +strict+ and a Hash param has no block or an
-  # Array param has neither a block nor <tt>of:</tt>, since strict providers
-  # reject objects without +properties+ and arrays without +items+.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)
     validate_strict_shape! if strict
+    # Nullable so strict providers can distinguish absent from present.
     nullable = strict && !required
 
+    # Providers like Anthropic reject a nullable type union combined with enum.
     if nullable && enum
       schema = { anyOf: [{ type: type_name, enum: enum }, { type: "null" }] } #: Hash[Symbol, untyped]
       schema[:description] = description if description
@@ -181,9 +152,22 @@ class Riffer::Params::Param
 
   private
 
+  # +dup+ would leave the copy sharing this one's nested Params, enum list and
+  # default, so defining a parameter or editing either value on one would reach
+  # the other.
+  #--
+  #: (Riffer::Params::Param) -> void
+  def initialize_copy(source)
+    super
+    @nested_params = source.nested_params&.dup
+    @enum = Riffer::Helpers::DeepDup.call(source.enum)
+    @default = Riffer::Helpers::DeepDup.call(source.default)
+  end
+
   #--
   #: () -> void
   def validate_strict_shape!
+    # Strict providers reject objects without properties and arrays without items.
     if type == Hash && nested_params.nil?
       raise Riffer::ArgumentError,
             "#{name}: a Hash param requires a block defining its properties under strict schemas"

data/lib/riffer/params.rb

@@ -1,16 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# A DSL for defining tool parameters and structured-output schemas, used within
-# a Tool's +params+ block.
-#
-#   params do
-#     required :city, String, description: "The city name"
-#     optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
-#   end
-#
 class Riffer::Params
-  # The defined parameters.
   attr_reader :parameters #: Array[Riffer::Params::Param] # @dynamic parameters
 
   #--
@@ -19,13 +10,8 @@ class Riffer::Params
     @parameters = []
   end
 
-  # Reconstructs a Params from a JSON Schema object — the inverse of
-  # +to_json_schema(strict: false)+. Raises Riffer::ArgumentError on features
-  # outside the Params-expressible subset of JSON Schema.
-  #
-  #   schema = params.to_json_schema(strict: false)
-  #   Riffer::Params.from_json_schema(schema) # => equivalent Riffer::Params
-  #
+  # The inverse of +to_json_schema(strict: false)+. Raises Riffer::ArgumentError
+  # on features outside the Params-expressible subset of JSON Schema.
   #--
   #: (Hash[Symbol, untyped]) -> Riffer::Params
   def self.from_json_schema(schema)
@@ -42,8 +28,6 @@ class Riffer::Params
     params
   end
 
-  # Defines a required parameter.
-  #
   #--
   #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
   def required(name, type, description: nil, enum: nil, of: nil, &)
@@ -59,8 +43,6 @@ class Riffer::Params
     )
   end
 
-  # Defines an optional parameter.
-  #
   #--
   #: (Symbol, Module, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
   def optional(name, type, description: nil, enum: nil, default: nil, of: nil, &)
@@ -77,15 +59,6 @@ class Riffer::Params
     )
   end
 
-  # Validates arguments against parameter definitions.
-  #
-  # A Float param accepts an Integer (JSON Schema <tt>"number"</tt> covers
-  # integers) and its value is coerced with +to_f+, so callers always get a
-  # Float. The same holds for the items of an <tt>of: Float</tt> array. No other
-  # type is coerced.
-  #
-  # Raises Riffer::ValidationError if validation fails.
-  #
   #--
   #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def validate(arguments)
@@ -125,11 +98,6 @@ class Riffer::Params
     validated
   end
 
-  # Converts all parameters to JSON Schema format. When +strict+ is true, every
-  # property is listed in +required+ and optional ones are made nullable
-  # instead, satisfying providers that enforce strict structured output schemas.
-  # Raises Riffer::ArgumentError when +strict+ and a Hash param (at any depth)
-  # has no block or an Array param has neither a block nor <tt>of:</tt>.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)
@@ -138,6 +106,8 @@ class Riffer::Params
 
     @parameters.each do |param|
       properties[param.name.to_s] = param.to_json_schema(strict: strict)
+      # Providers enforcing strict structured output require every property in
+      # +required+; strict mode makes optional ones nullable instead.
       required_params << param.name.to_s if strict || param.required
     end
 
@@ -151,6 +121,15 @@ class Riffer::Params
 
   private
 
+  # Without this, +dup+ shares parameters, so defining one on either copy
+  # would reach the other.
+  #--
+  #: (Riffer::Params) -> void
+  def initialize_copy(source)
+    super
+    @parameters = source.parameters.map(&:dup)
+  end
+
   #--
   #: (Module, Module?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def build_nested(type, of, &block)
@@ -224,7 +203,6 @@ class Riffer::Params
     end
   end
 
-  # Returns the array with its valid items coerced by +coerce_value+.
   #--
   #: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
   def validate_typed_array(param, value, errors)
@@ -249,13 +227,11 @@ class Riffer::Params
     end
   end
 
-  # Coerces an already-validated value to the Ruby type its param declares.
-  # Only Float coerces today, because JSON Schema "number" accepts integers and
-  # callers should not get a type that depends on whether the model wrote a
-  # decimal point. Add a branch here rather than inline at a call site.
   #--
   #: (Module, untyped) -> untyped
   def coerce_value(type, value)
+    # JSON Schema "number" accepts integers; callers shouldn't get a type that
+    # depends on whether the model wrote a decimal point.
     return value.to_f if type == Float
 
     value