riffer 0.28.0 → 0.29.1

data/lib/riffer/config.rb

@@ -12,6 +12,8 @@
 #
 #   Riffer.config.anthropic.api_key = "sk-ant-..."
 #
+#   Riffer.config.openrouter.api_key = "sk-or-..."
+#
 #   Riffer.config.evals.judge_model = "anthropic/claude-sonnet-4-20250514"
 #
 class Riffer::Config
@@ -20,6 +22,7 @@ class Riffer::Config
   AzureOpenAI = Struct.new(:api_key, :endpoint, keyword_init: true)
   Gemini = Struct.new(:api_key, :open_timeout, :read_timeout, keyword_init: true)
   OpenAI = Struct.new(:api_key, keyword_init: true)
+  OpenRouter = Struct.new(:api_key, keyword_init: true)
   Evals = Struct.new(:judge_model, keyword_init: true)
   Mcp = Struct.new(:credentials, :discovery_runner, keyword_init: true)
 
@@ -91,6 +94,9 @@ class Riffer::Config
   # OpenAI configuration (Struct with +api_key+).
   attr_reader :openai #: Riffer::Config::OpenAI
 
+  # OpenRouter configuration (Struct with +api_key+).
+  attr_reader :openrouter #: Riffer::Config::OpenRouter
+
   # Evals configuration (Struct with +judge_model+).
   attr_reader :evals #: Riffer::Config::Evals
 
@@ -107,9 +113,9 @@ class Riffer::Config
 
   # Global tool runtime configuration (experimental).
   #
-  # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,
-  # or a Proc. Defaults to <tt>Riffer::ToolRuntime::Inline.new</tt>.
-  attr_reader :tool_runtime #: (singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)
+  # Accepts a Riffer::Tools::Runtime subclass, a Riffer::Tools::Runtime instance,
+  # or a Proc. Defaults to <tt>Riffer::Tools::Runtime::Inline.new</tt>.
+  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
 
   # Sets the global tool runtime.
   #
@@ -117,10 +123,10 @@ class Riffer::Config
   # (ToolRuntime subclass, ToolRuntime instance, or Proc).
   #
   #--
-  #: ((singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)) -> void
+  #: ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> void
   def tool_runtime=(value)
-    valid = (value.is_a?(Class) && value < Riffer::ToolRuntime) || value.is_a?(Riffer::ToolRuntime) || value.is_a?(Proc)
-    raise Riffer::ArgumentError, "tool_runtime must be a Riffer::ToolRuntime subclass, instance, or a Proc" unless valid
+    valid = (value.is_a?(Class) && value < Riffer::Tools::Runtime) || value.is_a?(Riffer::Tools::Runtime) || value.is_a?(Proc)
+    raise Riffer::ArgumentError, "tool_runtime must be a Riffer::Tools::Runtime subclass, instance, or a Proc" unless valid
     @tool_runtime = value
   end
 
@@ -200,9 +206,10 @@ class Riffer::Config
     @azure_openai = AzureOpenAI.new
     @gemini = Gemini.new
     @openai = OpenAI.new
+    @openrouter = OpenRouter.new
     @evals = Evals.new
     @mcp = Mcp.new(credentials: nil, discovery_runner: Riffer::Runner::Sequential.new)
-    @tool_runtime = Riffer::ToolRuntime::Inline.new
+    @tool_runtime = Riffer::Tools::Runtime::Inline.new
     @skills = Skills.new
     @message_id_strategy = :none
     @experimental_history_healing = false

data/lib/riffer/evals/evaluator.rb

@@ -16,6 +16,11 @@
 #   end
 #
 class Riffer::Evals::Evaluator
+  # @rbs self.@instructions: String?
+  # @rbs self.@higher_is_better: bool?
+  # @rbs self.@judge_model: String?
+  # @rbs @judge: Riffer::Evals::Judge?
+
   class << self
     # Gets or sets the evaluation instructions (criteria and scoring rubric).
     #
@@ -31,7 +36,11 @@ class Riffer::Evals::Evaluator
     #--
     #: (?bool?) -> bool
     def higher_is_better(value = nil)
-      return @higher_is_better.nil? || @higher_is_better if value.nil?
+      if value.nil?
+        current = @higher_is_better
+        return true if current.nil?
+        return current
+      end
       @higher_is_better = value
     end
 
@@ -87,8 +96,14 @@ class Riffer::Evals::Evaluator
     return input if input.is_a?(String)
 
     input.map do |msg|
-      role = msg.is_a?(Hash) ? (msg[:role] || msg["role"]) : msg.role
-      content = msg.is_a?(Hash) ? (msg[:content] || msg["content"]) : msg.content
+      if msg.is_a?(Hash)
+        hash = msg #: Hash[untyped, untyped]
+        role = hash[:role] || hash["role"]
+        content = hash[:content] || hash["content"]
+      else
+        role = msg.role
+        content = msg.content
+      end
       "#{role}: #{content}"
     end.join("\n\n")
   end

data/lib/riffer/evals/judge.rb

@@ -19,6 +19,11 @@ require "json"
 #   result[:reason] # => "The response is relevant..."
 #
 class Riffer::Evals::Judge
+  # @rbs @provider_options: Hash[Symbol, untyped]
+  # @rbs @provider_instance: Riffer::Providers::Base?
+  # @rbs @provider_name: String?
+  # @rbs @model_name: String?
+
   # Internal tool for structured evaluation output.
   class EvaluationTool < Riffer::Tool
     identifier "evaluation"
@@ -30,7 +35,7 @@ class Riffer::Evals::Judge
     end
 
     #--
-    #: (context: Hash[Symbol, untyped]?, score: Float, reason: String) -> Riffer::Tools::Response
+    #: (context: Riffer::Agent::Context?, score: Float, reason: String) -> Riffer::Tools::Response
     def call(context:, score:, reason:)
       json({score: score, reason: reason})
     end
@@ -94,7 +99,7 @@ class Riffer::Evals::Judge
   #--
   #: (input: String, output: String, ?ground_truth: String?) -> String
   def build_user_message(input:, output:, ground_truth: nil)
-    parts = []
+    parts = [] #: Array[String]
     parts << "## Input\n\n#{input}"
     parts << "## Output\n\n#{output}"
     parts << "## Ground Truth\n\n#{ground_truth}" if ground_truth

data/lib/riffer/evals/run_result.rb

@@ -40,7 +40,8 @@ class Riffer::Evals::RunResult
       end
     end
 
-    totals.each_with_object({}) do |(evaluator, total), hash|
+    averages = {} #: Hash[singleton(Riffer::Evals::Evaluator), Float]
+    totals.each_with_object(averages) do |(evaluator, total), hash|
       hash[evaluator] = total / counts[evaluator]
     end
   end

data/lib/riffer/evals/scenario_result.rb

@@ -47,7 +47,8 @@ class Riffer::Evals::ScenarioResult
   #--
   #: () -> Hash[singleton(Riffer::Evals::Evaluator), Float]
   def scores
-    results.each_with_object({}) do |result, hash|
+    acc = {} #: Hash[singleton(Riffer::Evals::Evaluator), Float]
+    results.each_with_object(acc) do |result, hash|
       hash[result.evaluator] = result.score
     end
   end

data/lib/riffer/guardrails/runner.rb

@@ -80,7 +80,8 @@ class Riffer::Guardrails::Runner
   #--
   #: (Hash[Symbol, untyped]) -> Riffer::Guardrail
   def instantiate_guardrail(config)
-    config[:class].new(**config[:options])
+    options = config[:options] #: Hash[Symbol, untyped]
+    config[:class].new(**options)
   end
 
   #--
@@ -101,7 +102,7 @@ class Riffer::Guardrails::Runner
     when :before
       guardrail.process_input(data, context: context)
     when :after
-      guardrail.process_output(data, messages: messages, context: context)
+      guardrail.process_output(data, messages: messages || [], context: context)
     else
       raise Riffer::Error, "Unexpected guardrail phase: #{phase}. Valid phases: #{Riffer::Guardrails::PHASES.join(", ")}"
     end

data/lib/riffer/helpers/call_or_value.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Resolves the "Proc-or-value" idiom: if +thing+ is a Proc, calls it
+# (passing +context+ when its arity is non-zero); otherwise returns
+# +thing+ unchanged. When +thing+ is +nil+, returns +default+.
+module Riffer::Helpers::CallOrValue
+  extend self
+
+  #: (untyped, ?context: untyped, ?default: untyped) -> untyped
+  def resolve(thing, context: nil, default: nil)
+    return default if thing.nil?
+    return thing unless thing.is_a?(Proc)
+    thing.arity.zero? ? thing.call : thing.call(context)
+  end
+end

data/lib/riffer/helpers.rb

@@ -6,6 +6,5 @@
 # Helpers provide reusable functionality across the library:
 # - Riffer::Helpers::ClassNameConverter - Class name to path conversion
 # - Riffer::Helpers::Dependencies - Lazy gem dependency loading
-# - Riffer::Helpers::Validations - Input validation
 module Riffer::Helpers
 end

data/lib/riffer/mcp/authenticated_tool.rb

@@ -23,6 +23,9 @@ module Riffer::Mcp::AuthenticatedTool
     tags = matched_tags
 
     Class.new(Riffer::Tool) do
+      # steep cannot type the body of a dynamically created anonymous class:
+      # its ivars and `self` inside define_method are unresolvable.
+      # steep:ignore:start
       @identifier = inner.identifier
 
       define_singleton_method(:name) { inner.name }
@@ -60,6 +63,7 @@ module Riffer::Mcp::AuthenticatedTool
         client = build_call_client(man.endpoint, headers)
         text(client.tools_call(inner.mcp_server_tool_name, kwargs))
       end
+      # steep:ignore:end
     end
   end
 end

data/lib/riffer/mcp/client.rb

@@ -16,6 +16,8 @@
 class Riffer::Mcp::Client
   include Riffer::Helpers::Dependencies
 
+  # @rbs @client: untyped
+
   #--
   #: (endpoint: String, ?headers: (Hash[String, String] | Proc), ?client: untyped?) -> void
   def initialize(endpoint:, headers: {}, client: nil)
@@ -23,7 +25,7 @@ class Riffer::Mcp::Client
     depends_on "faraday"
 
     @client = client || begin
-      resolved_headers = headers.is_a?(Proc) ? headers.call : headers
+      resolved_headers = Riffer::Helpers::CallOrValue.resolve(headers)
       transport = MCP::Client::HTTP.new(url: endpoint, headers: resolved_headers)
       MCP::Client.new(transport: transport)
     end

data/lib/riffer/mcp/registration.rb

@@ -7,6 +7,10 @@
 # +tools/list+ call, then generates tool classes.
 #
 class Riffer::Mcp::Registration
+  # @rbs @cancelled: bool
+  # @rbs @tools: Array[singleton(Riffer::Tool)]
+  # @rbs @mutex: Thread::Mutex
+
   # The manifest that describes this server.
   attr_reader :manifest #: Riffer::Mcp::Manifest
 
@@ -23,7 +27,7 @@ class Riffer::Mcp::Registration
   def initialize(manifest)
     @manifest = manifest
     @cancelled = false
-    @tools = []
+    @tools = [] #: Array[singleton(Riffer::Tool)]
     @mutex = Mutex.new
     run_discovery
   end
@@ -62,8 +66,7 @@ class Riffer::Mcp::Registration
       tools = Riffer::Mcp::ToolFactory.build(@manifest.name, client, tool_defs)
 
       @mutex.synchronize do
-        next if @cancelled
-        @tools = tools.freeze
+        @tools = tools.freeze unless @cancelled
       end
     end
   end

data/lib/riffer/mcp/registry.rb

@@ -6,6 +6,9 @@
 # Keyed by manifest name. All public methods are mutex-guarded.
 #
 module Riffer::Mcp::Registry
+  # @rbs self.@mutex: Thread::Mutex
+  # @rbs self.@store: Hash[String, Riffer::Mcp::Registration]
+
   @mutex = Mutex.new
   @store = {} #: Hash[String, Riffer::Mcp::Registration]
 
@@ -18,7 +21,9 @@ module Riffer::Mcp::Registry
     #--
     #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
     def register(manifest_or_hash)
-      manifest = manifest_or_hash.is_a?(Riffer::Mcp::Manifest) ? manifest_or_hash : Riffer::Mcp::Manifest.new(**manifest_or_hash)
+      # steep cannot verify that an untyped Hash splat supplies Manifest's
+      # required name:/endpoint: keywords; Manifest validates them at runtime.
+      manifest = manifest_or_hash.is_a?(Riffer::Mcp::Manifest) ? manifest_or_hash : Riffer::Mcp::Manifest.new(**manifest_or_hash) # steep:ignore InsufficientKeywordArguments
       registration = Riffer::Mcp::Registration.new(manifest)
       old = @mutex.synchronize do
         previous = @store[manifest.name]

data/lib/riffer/mcp/tool_factory.rb

@@ -31,7 +31,11 @@ module Riffer::Mcp::ToolFactory
   private_class_method def self.build_tool_class(manifest_name, client, td)
     prefixed = "#{sanitize_name_component(manifest_name)}__#{sanitize_name_component(td[:name])}"
 
+    # steep cannot type the body of a dynamically created anonymous class:
+    # its ivars and `self` inside define_method are unresolvable, so the
+    # block is ignored wholesale (cf. AuthenticatedTool.wrap_one).
     Class.new(Riffer::Tool) do
+      # steep:ignore:start
       @mcp_client = client
       @mcp_server_tool_name = td[:name]
       # Set @identifier directly so .identifier does not fall back to
@@ -49,6 +53,7 @@ module Riffer::Mcp::ToolFactory
         )
         text(result)
       end
+      # steep:ignore:end
     end
   end
 end

data/lib/riffer/messages/assistant.rb

@@ -17,13 +17,13 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall]
 
   # Token usage data for this response.
-  attr_reader :token_usage #: Riffer::TokenUsage?
+  attr_reader :token_usage #: Riffer::Providers::TokenUsage?
 
   # Parsed structured output hash, or nil when not applicable.
   attr_reader :structured_output #: Hash[Symbol, untyped]?
 
   #--
-  #: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
+  #: (String, ?id: String?, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall], ?token_usage: Riffer::Providers::TokenUsage?, ?structured_output: Hash[Symbol, untyped]?) -> void
   def initialize(content, id: nil, tool_calls: [], token_usage: nil, structured_output: nil)
     super(content, id: id)
     @tool_calls = tool_calls
@@ -43,6 +43,12 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     !@structured_output.nil?
   end
 
+  #--
+  #: () -> bool
+  def has_tool_calls?
+    !@tool_calls.empty?
+  end
+
   #--
   #: (Riffer::Messages::Assistant) -> Riffer::Messages::Assistant
   def +(other)
@@ -54,7 +60,7 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    hash = {role: role, content: content}
+    hash = {role: role, content: content} #: Hash[Symbol, untyped]
     hash[:id] = id unless id.nil?
     hash[:tool_calls] = tool_calls.map(&:to_h) unless tool_calls.empty?
     hash[:token_usage] = token_usage.to_h if token_usage

data/lib/riffer/messages/base.rb

@@ -40,6 +40,28 @@ class Riffer::Messages::Base
     raise NotImplementedError, "Subclasses must implement #role"
   end
 
+  # Whether this message carries pending tool calls. Defaults to +false+;
+  # +Riffer::Messages::Assistant+ overrides this when its +tool_calls+
+  # array is non-empty.
+  #
+  #--
+  #: () -> bool
+  def has_tool_calls?
+    false
+  end
+
+  # Merges another same-role message into this one.
+  #
+  # Raises NotImplementedError unless implemented by subclass. Mergeable
+  # message types (+User+, +Assistant+, +System+) override this; +Tool+
+  # messages are never merged.
+  #
+  #--
+  #: (untyped) -> Riffer::Messages::Base
+  def +(other)
+    raise NotImplementedError, "Subclasses must implement #+"
+  end
+
   private
 
   #: () -> String?

data/lib/riffer/messages/converter.rb

@@ -21,19 +21,19 @@ module Riffer::Messages::Converter
     convert_hash_to_message(msg)
   end
 
-  # Converts a hash or FilePart object to a Riffer::FilePart.
+  # Converts a hash or FilePart object to a Riffer::Messages::FilePart.
   #
   # Accepts:
-  # - +Riffer::FilePart+ objects (passed through)
+  # - +Riffer::Messages::FilePart+ objects (passed through)
   # - <tt>{url: "https://...", media_type: "..."}</tt> (URL source)
   # - <tt>{data: "...", media_type: "..."}</tt> (raw base64)
   #
   # Raises Riffer::ArgumentError if the hash format is invalid.
   #
   #--
-  #: ((Hash[Symbol, untyped] | Riffer::FilePart)) -> Riffer::FilePart
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::FilePart)) -> Riffer::Messages::FilePart
   def convert_to_file_part(file)
-    return file if file.is_a?(Riffer::FilePart)
+    return file if file.is_a?(Riffer::Messages::FilePart)
 
     unless file.is_a?(Hash)
       raise Riffer::ArgumentError, "File must be a Hash or FilePart object, got #{file.class}"
@@ -45,9 +45,9 @@ module Riffer::Messages::Converter
     filename = file[:filename]
 
     if url
-      Riffer::FilePart.from_url(url, media_type: media_type)
+      Riffer::Messages::FilePart.from_url(url, media_type: media_type)
     elsif data && media_type
-      Riffer::FilePart.new(data: data, media_type: media_type, filename: filename)
+      Riffer::Messages::FilePart.new(data: data, media_type: media_type, filename: filename)
     else
       raise Riffer::ArgumentError, "File hash must include :url or :data with :media_type"
     end

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

@@ -10,11 +10,13 @@ require "uri"
 # - URLs (stored and passed to providers that support them via +from_url+)
 # - Raw base64 data (via +new+)
 #
-#   file = Riffer::FilePart.from_url("https://example.com/doc.pdf", media_type: "application/pdf")
+#   file = Riffer::Messages::FilePart.from_url("https://example.com/doc.pdf", media_type: "application/pdf")
 #   file.url?        # => true
 #   file.document?   # => true
 #
-class Riffer::FilePart
+class Riffer::Messages::FilePart
+  # @rbs @url_string: String?
+
   MEDIA_TYPES = {
     ".jpg" => "image/jpeg",
     ".jpeg" => "image/jpeg",
@@ -63,10 +65,10 @@ class Riffer::FilePart
   # Raises Riffer::ArgumentError if media_type cannot be detected.
   #
   #--
-  #: (String, ?media_type: String?) -> Riffer::FilePart
+  #: (String, ?media_type: String?) -> Riffer::Messages::FilePart
   def self.from_url(url, media_type: nil)
     unless media_type
-      ext = ::File.extname(URI.parse(url).path).downcase
+      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
@@ -114,7 +116,7 @@ class Riffer::FilePart
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    hash = {media_type: media_type}
+    hash = {media_type: media_type} #: Hash[Symbol, untyped]
     hash[:data] = @data if @data
     hash[:url] = @url_string if @url_string
     hash[:filename] = filename if filename

data/lib/riffer/messages/tool.rb

@@ -54,7 +54,7 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    hash = {role: role, content: content, tool_call_id: tool_call_id, name: name}
+    hash = {role: role, content: content, tool_call_id: tool_call_id, name: name} #: Hash[Symbol, untyped]
     hash[:id] = id unless id.nil?
     if error?
       hash[:error] = error

data/lib/riffer/messages/user.rb

@@ -8,16 +8,16 @@
 #   msg.content  # => "Hello!"
 #
 #   msg = Riffer::Messages::User.new("Describe this image", files: [file_part])
-#   msg.files    # => [#<Riffer::FilePart ...>]
+#   msg.files    # => [#<Riffer::Messages::FilePart ...>]
 #
 class Riffer::Messages::User < Riffer::Messages::Base
   # File attachments for this message.
-  attr_reader :files #: Array[Riffer::FilePart]
+  attr_reader :files #: Array[Riffer::Messages::FilePart]
 
   # Initializes a user message.
   #
   #--
-  #: (String, ?id: String?, ?files: Array[Riffer::FilePart]) -> void
+  #: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
   def initialize(content, id: nil, files: [])
     super(content, id: id)
     @files = files
@@ -38,7 +38,7 @@ class Riffer::Messages::User < Riffer::Messages::Base
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
-    hash = {role: role, content: content}
+    hash = {role: role, content: content} #: Hash[Symbol, untyped]
     hash[:id] = id unless id.nil?
     hash[:files] = files.map(&:to_h) unless files.empty?
     hash

data/lib/riffer/{boolean.rb → params/boolean.rb}

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Boolean is a sentinel type for declaring boolean parameters.
+# Riffer::Params::Boolean is a sentinel type for declaring boolean parameters.
 #
 # Ruby has no +Boolean+ class (+true+ is +TrueClass+, +false+ is +FalseClass+).
 # Use this module wherever you need a single type that means "boolean":
 #
-#   required :verbose, Riffer::Boolean
+#   required :verbose, Riffer::Params::Boolean
 #
-module Riffer::Boolean
+module Riffer::Params::Boolean
 end

data/lib/riffer/{param.rb → params/param.rb}

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Param represents a single parameter definition.
+# Riffer::Params::Param represents a single parameter definition.
 #
 # Handles type validation and JSON Schema generation for individual parameters.
-class Riffer::Param
+class Riffer::Params::Param
   # Maps Ruby types to JSON Schema type strings
   TYPE_MAPPINGS = {
     String => "string",
     Integer => "integer",
     Float => "number",
-    Riffer::Boolean => "boolean",
+    Riffer::Params::Boolean => "boolean",
     TrueClass => "boolean",
     FalseClass => "boolean",
     Array => "array",
@@ -49,7 +49,7 @@ class Riffer::Param
   def valid_type?(value)
     return true if value.nil? && !required
 
-    if type == Riffer::Boolean || type == TrueClass || type == FalseClass
+    if type == Riffer::Params::Boolean || type == TrueClass || type == FalseClass
       value == true || value == false
     else
       value.is_a?(type)
@@ -80,7 +80,7 @@ class Riffer::Param
     nullable = strict && !required
 
     if nullable && enum
-      schema = {anyOf: [{type: type_name, enum: enum}, {type: "null"}]}
+      schema = {anyOf: [{type: type_name, enum: enum}, {type: "null"}]} #: Hash[Symbol, untyped]
       schema[:description] = description if description
       return schema
     end
@@ -88,7 +88,7 @@ class Riffer::Param
     type = type_name
     type = [type, "null"] if nullable
 
-    schema = {type: type}
+    schema = {type: type} #: Hash[Symbol, untyped]
     schema[:description] = description if description
     schema[:enum] = enum if enum