riffer 0.7.0 → 0.9.0

data/lib/riffer/stream_events/base.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
+# Base class for all streaming events in the Riffer framework.
+#
+# Subclasses must implement the +to_h+ method.
 class Riffer::StreamEvents::Base
+  # The message role (typically :assistant).
+  #
+  # Returns Symbol.
   attr_reader :role
 
-  def initialize(role: "assistant")
+  # Creates a new stream event.
+  #
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(role: :assistant)
     @role = role
   end
 
+  # Converts the event to a hash.
+  #
+  # Raises NotImplementedError if not implemented by subclass.
   def to_h
     raise NotImplementedError, "Subclasses must implement #to_h"
   end

data/lib/riffer/stream_events/reasoning_delta.rb

@@ -1,13 +1,27 @@
 # frozen_string_literal: true
 
+# Represents an incremental reasoning chunk during streaming.
+#
+# Emitted when the LLM produces reasoning/thinking content incrementally.
+# Only available with providers that support reasoning (e.g., OpenAI with reasoning option).
 class Riffer::StreamEvents::ReasoningDelta < Riffer::StreamEvents::Base
+  # The incremental reasoning content.
+  #
+  # Returns String.
   attr_reader :content
 
-  def initialize(content, role: "assistant")
+  # Creates a new reasoning delta event.
+  #
+  # content:: String - the incremental reasoning content
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(content, role: :assistant)
     super(role: role)
     @content = content
   end
 
+  # Converts the event to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: @role, content: @content}
   end

data/lib/riffer/stream_events/reasoning_done.rb

@@ -1,13 +1,27 @@
 # frozen_string_literal: true
 
+# Represents completion of reasoning during streaming.
+#
+# Emitted when the LLM has finished producing reasoning/thinking content.
+# Only available with providers that support reasoning (e.g., OpenAI with reasoning option).
 class Riffer::StreamEvents::ReasoningDone < Riffer::StreamEvents::Base
+  # The complete reasoning content.
+  #
+  # Returns String.
   attr_reader :content
 
-  def initialize(content, role: "assistant")
+  # Creates a new reasoning done event.
+  #
+  # content:: String - the complete reasoning content
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(content, role: :assistant)
     super(role: role)
     @content = content
   end
 
+  # Converts the event to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: @role, content: @content}
   end

data/lib/riffer/stream_events/text_delta.rb

@@ -1,13 +1,26 @@
 # frozen_string_literal: true
 
+# Represents an incremental text chunk during streaming.
+#
+# Emitted when the LLM produces text content incrementally.
 class Riffer::StreamEvents::TextDelta < Riffer::StreamEvents::Base
+  # The incremental text content.
+  #
+  # Returns String.
   attr_reader :content
 
-  def initialize(content, role: "assistant")
+  # Creates a new text delta event.
+  #
+  # content:: String - the incremental text content
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(content, role: :assistant)
     super(role: role)
     @content = content
   end
 
+  # Converts the event to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: @role, content: @content}
   end

data/lib/riffer/stream_events/text_done.rb

@@ -1,13 +1,26 @@
 # frozen_string_literal: true
 
+# Represents completion of text generation during streaming.
+#
+# Emitted when the LLM has finished producing text content.
 class Riffer::StreamEvents::TextDone < Riffer::StreamEvents::Base
+  # The complete text content.
+  #
+  # Returns String.
   attr_reader :content
 
-  def initialize(content, role: "assistant")
+  # Creates a new text done event.
+  #
+  # content:: String - the complete text content
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(content, role: :assistant)
     super(role: role)
     @content = content
   end
 
+  # Converts the event to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: @role, content: @content}
   end

data/lib/riffer/stream_events/tool_call_delta.rb

@@ -3,25 +3,32 @@
 # Riffer::StreamEvents::ToolCallDelta represents an incremental tool call chunk during streaming.
 #
 # Emitted when the LLM is building a tool call, containing partial argument data.
-#
-# @api public
 class Riffer::StreamEvents::ToolCallDelta < Riffer::StreamEvents::Base
-  attr_reader :item_id, :name, :arguments_delta
+  # The tool call item identifier.
+  attr_reader :item_id
+
+  # The tool name (may only be present in first delta).
+  attr_reader :name
+
+  # The incremental arguments JSON fragment.
+  attr_reader :arguments_delta
 
-  # Creates a new tool call delta event
-  # @param item_id [String] the tool call item identifier
-  # @param name [String, nil] the tool name (may only be present in first delta)
-  # @param arguments_delta [String] the incremental arguments JSON fragment
-  # @param role [String] the message role (defaults to "assistant")
-  def initialize(item_id:, arguments_delta:, name: nil, role: "assistant")
+  # Creates a new tool call delta event.
+  #
+  # item_id:: String - the tool call item identifier
+  # name:: String or nil - the tool name (may only be present in first delta)
+  # arguments_delta:: String - the incremental arguments JSON fragment
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(item_id:, arguments_delta:, name: nil, role: :assistant)
     super(role: role)
     @item_id = item_id
     @name = name
     @arguments_delta = arguments_delta
   end
 
-  # Converts the event to a hash
-  # @return [Hash] the event data
+  # Converts the event to a hash.
+  #
+  # Returns Hash - the event data.
   def to_h
     {role: @role, item_id: @item_id, name: @name, arguments_delta: @arguments_delta}.compact
   end

data/lib/riffer/stream_events/tool_call_done.rb

@@ -3,18 +3,27 @@
 # Riffer::StreamEvents::ToolCallDone represents a completed tool call during streaming.
 #
 # Emitted when the LLM has finished building a tool call with complete arguments.
-#
-# @api public
 class Riffer::StreamEvents::ToolCallDone < Riffer::StreamEvents::Base
-  attr_reader :item_id, :call_id, :name, :arguments
+  # The tool call item identifier.
+  attr_reader :item_id
+
+  # The call identifier for response matching.
+  attr_reader :call_id
+
+  # The tool name.
+  attr_reader :name
+
+  # The complete arguments JSON string.
+  attr_reader :arguments
 
-  # Creates a new tool call done event
-  # @param item_id [String] the tool call item identifier
-  # @param call_id [String] the call identifier for response matching
-  # @param name [String] the tool name
-  # @param arguments [String] the complete arguments JSON string
-  # @param role [String] the message role (defaults to "assistant")
-  def initialize(item_id:, call_id:, name:, arguments:, role: "assistant")
+  # Creates a new tool call done event.
+  #
+  # item_id:: String - the tool call item identifier
+  # call_id:: String - the call identifier for response matching
+  # name:: String - the tool name
+  # arguments:: String - the complete arguments JSON string
+  # role:: Symbol - the message role (defaults to :assistant)
+  def initialize(item_id:, call_id:, name:, arguments:, role: :assistant)
     super(role: role)
     @item_id = item_id
     @call_id = call_id
@@ -22,8 +31,9 @@ class Riffer::StreamEvents::ToolCallDone < Riffer::StreamEvents::Base
     @arguments = arguments
   end
 
-  # Converts the event to a hash
-  # @return [Hash] the event data
+  # Converts the event to a hash.
+  #
+  # Returns Hash - the event data.
   def to_h
     {role: @role, item_id: @item_id, call_id: @call_id, name: @name, arguments: @arguments}
   end

data/lib/riffer/stream_events.rb

@@ -1,4 +1,13 @@
 # frozen_string_literal: true
 
+# Namespace for streaming event types in the Riffer framework.
+#
+# When streaming responses, these events are yielded to represent incremental updates:
+# - Riffer::StreamEvents::TextDelta - Incremental text content
+# - Riffer::StreamEvents::TextDone - Complete text content
+# - Riffer::StreamEvents::ToolCallDelta - Incremental tool call arguments
+# - Riffer::StreamEvents::ToolCallDone - Complete tool call
+# - Riffer::StreamEvents::ReasoningDelta - Incremental reasoning content
+# - Riffer::StreamEvents::ReasoningDone - Complete reasoning content
 module Riffer::StreamEvents
 end

data/lib/riffer/tool.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
+require "timeout"
+
 # Riffer::Tool is the base class for all tools in the Riffer framework.
 #
 # Provides a DSL for defining tool description and parameters.
+# Subclasses must implement the +call+ method.
 #
-# @abstract Subclasses must implement the `call` method.
+# See Riffer::Agent.
 #
-# @example
 #   class WeatherLookupTool < Riffer::Tool
 #     description "Provides current weather information for a specified city."
 #
@@ -20,22 +22,27 @@
 #     end
 #   end
 #
-# @see Riffer::Agent
 class Riffer::Tool
+  DEFAULT_TIMEOUT = 10
+
   class << self
     include Riffer::Helpers::ClassNameConverter
 
-    # Gets or sets the tool description
-    # @param value [String, nil] the description to set, or nil to get
-    # @return [String, nil] the tool description
+    # Gets or sets the tool description.
+    #
+    # value:: String or nil - the description to set, or nil to get
+    #
+    # Returns String or nil - the tool description.
     def description(value = nil)
       return @description if value.nil?
       @description = value.to_s
     end
 
-    # Gets or sets the tool identifier/name
-    # @param value [String, nil] the identifier to set, or nil to get
-    # @return [String] the tool identifier (defaults to snake_case class name)
+    # Gets or sets the tool identifier/name.
+    #
+    # value:: String or nil - the identifier to set, or nil to get
+    #
+    # Returns String - the tool identifier (defaults to snake_case class name).
     def identifier(value = nil)
       return @identifier || class_name_to_path(Module.instance_method(:name).bind_call(self)) if value.nil?
       @identifier = value.to_s
@@ -44,17 +51,30 @@ class Riffer::Tool
     # Alias for identifier - used by providers
     alias_method :name, :identifier
 
-    # Defines parameters using the Params DSL
-    # @yield the parameter definition block
-    # @return [Riffer::Tools::Params, nil] the params builder
+    # Gets or sets the tool timeout in seconds.
+    #
+    # value:: Numeric or nil - the timeout to set in seconds, or nil to get
+    #
+    # Returns Numeric - the tool timeout (defaults to 10).
+    def timeout(value = nil)
+      return @timeout || DEFAULT_TIMEOUT if value.nil?
+      @timeout = value.to_f
+    end
+
+    # Defines parameters using the Params DSL.
+    #
+    # Yields to the parameter definition block.
+    #
+    # Returns Riffer::Tools::Params or nil - the params builder.
     def params(&block)
       return @params_builder if block.nil?
       @params_builder = Riffer::Tools::Params.new
       @params_builder.instance_eval(&block)
     end
 
-    # Returns the JSON Schema for the tool's parameters
-    # @return [Hash] the JSON Schema
+    # Returns the JSON Schema for the tool's parameters.
+    #
+    # Returns Hash - the JSON Schema.
     def parameters_schema
       @params_builder&.to_json_schema || empty_schema
     end
@@ -66,23 +86,70 @@ class Riffer::Tool
     end
   end
 
-  # Executes the tool with the given arguments
-  # @param context [Object, nil] optional context passed from the agent
-  # @param kwargs [Hash] the tool arguments
-  # @return [Object] the tool result
-  # @raise [NotImplementedError] if not implemented by subclass
+  # Executes the tool with the given arguments.
+  #
+  # context:: Object or nil - optional context passed from the agent
+  # kwargs:: Hash - the tool arguments
+  #
+  # Returns Object - the tool result.
+  #
+  # Raises NotImplementedError if not implemented by subclass.
   def call(context:, **kwargs)
     raise NotImplementedError, "#{self.class} must implement #call"
   end
 
-  # Executes the tool with validation (used by Agent)
-  # @param context [Object, nil] context passed from the agent
-  # @param kwargs [Hash] the tool arguments
-  # @return [Object] the tool result
-  # @raise [Riffer::ValidationError] if validation fails
+  # Creates a text response. Shorthand for Riffer::Tools::Response.text.
+  #
+  # result:: Object - the tool result (converted via to_s)
+  #
+  # Returns Riffer::Tools::Response.
+  def text(result)
+    Riffer::Tools::Response.text(result)
+  end
+
+  # Creates a JSON response. Shorthand for Riffer::Tools::Response.json.
+  #
+  # result:: Object - the tool result (converted via JSON.generate)
+  #
+  # Returns Riffer::Tools::Response.
+  def json(result)
+    Riffer::Tools::Response.json(result)
+  end
+
+  # Creates an error response. Shorthand for Riffer::Tools::Response.error.
+  #
+  # message:: String - the error message
+  # type:: Symbol - the error type (default: :execution_error)
+  #
+  # Returns Riffer::Tools::Response.
+  def error(message, type: :execution_error)
+    Riffer::Tools::Response.error(message, type: type)
+  end
+
+  # Executes the tool with validation and timeout (used by Agent).
+  #
+  # context:: Object or nil - context passed from the agent
+  # kwargs:: Hash - the tool arguments
+  #
+  # Returns Riffer::Tools::Response - the tool response.
+  #
+  # Raises Riffer::ValidationError if validation fails.
+  # Raises Riffer::TimeoutError if execution exceeds the configured timeout.
+  # Raises Riffer::Error if the tool does not return a Response object.
   def call_with_validation(context:, **kwargs)
     params_builder = self.class.params
     validated_args = params_builder ? params_builder.validate(kwargs) : kwargs
-    call(context: context, **validated_args)
+
+    result = Timeout.timeout(self.class.timeout) do
+      call(context: context, **validated_args)
+    end
+
+    unless result.is_a?(Riffer::Tools::Response)
+      raise Riffer::Error, "#{self.class} must return a Riffer::Tools::Response from #call"
+    end
+
+    result
+  rescue Timeout::Error
+    raise Riffer::TimeoutError, "Tool execution timed out after #{self.class.timeout} seconds"
   end
 end

data/lib/riffer/tools/param.rb

@@ -3,8 +3,6 @@
 # Riffer::Tools::Param represents a single parameter definition for a tool.
 #
 # Handles type validation and JSON Schema generation for individual parameters.
-#
-# @api private
 class Riffer::Tools::Param
   # Maps Ruby types to JSON Schema type strings
   TYPE_MAPPINGS = {
@@ -19,13 +17,14 @@ class Riffer::Tools::Param
 
   attr_reader :name, :type, :required, :description, :enum, :default
 
-  # Creates a new parameter definition
-  # @param name [Symbol] the parameter name
-  # @param type [Class] the expected Ruby type
-  # @param required [Boolean] whether the parameter is required
-  # @param description [String, nil] optional description for the parameter
-  # @param enum [Array, nil] optional list of allowed values
-  # @param default [Object, nil] optional default value for optional parameters
+  # Creates a new parameter definition.
+  #
+  # name:: Symbol - the parameter name
+  # type:: Class - the expected Ruby type
+  # required:: Boolean - whether the parameter is required
+  # description:: String or nil - optional description for the parameter
+  # enum:: Array or nil - optional list of allowed values
+  # default:: Object or nil - optional default value for optional parameters
   def initialize(name:, type:, required:, description: nil, enum: nil, default: nil)
     @name = name.to_sym
     @type = type
@@ -35,9 +34,11 @@ class Riffer::Tools::Param
     @default = default
   end
 
-  # Validates that a value matches the expected type
-  # @param value [Object] the value to validate
-  # @return [Boolean] true if valid, false otherwise
+  # Validates that a value matches the expected type.
+  #
+  # value:: Object - the value to validate
+  #
+  # Returns Boolean - true if valid, false otherwise.
   def valid_type?(value)
     return true if value.nil? && !required
 
@@ -48,14 +49,16 @@ class Riffer::Tools::Param
     end
   end
 
-  # Returns the JSON Schema type name for this parameter
-  # @return [String] the JSON Schema type
+  # Returns the JSON Schema type name for this parameter.
+  #
+  # Returns String - the JSON Schema type.
   def type_name
     TYPE_MAPPINGS[type] || type.to_s.downcase
   end
 
-  # Converts this parameter to JSON Schema format
-  # @return [Hash] the JSON Schema representation
+  # Converts this parameter to JSON Schema format.
+  #
+  # Returns Hash - the JSON Schema representation.
   def to_json_schema
     schema = {type: type_name}
     schema[:description] = description if description

data/lib/riffer/tools/params.rb

@@ -2,15 +2,13 @@
 
 # Riffer::Tools::Params provides a DSL for defining tool parameters.
 #
-# Used within a Tool's `params` block to define required and optional parameters.
+# Used within a Tool's +params+ block to define required and optional parameters.
 #
-# @example
 #   params do
 #     required :city, String, description: "The city name"
 #     optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
 #   end
 #
-# @api private
 class Riffer::Tools::Params
   attr_reader :parameters
 
@@ -18,12 +16,14 @@ class Riffer::Tools::Params
     @parameters = []
   end
 
-  # Defines a required parameter
-  # @param name [Symbol] the parameter name
-  # @param type [Class] the expected Ruby type
-  # @param description [String, nil] optional description
-  # @param enum [Array, nil] optional list of allowed values
-  # @return [void]
+  # Defines a required parameter.
+  #
+  # name:: Symbol - the parameter name
+  # type:: Class - the expected Ruby type
+  # description:: String or nil - optional description
+  # enum:: Array or nil - optional list of allowed values
+  #
+  # Returns void.
   def required(name, type, description: nil, enum: nil)
     @parameters << Riffer::Tools::Param.new(
       name: name,
@@ -34,13 +34,15 @@ class Riffer::Tools::Params
     )
   end
 
-  # Defines an optional parameter
-  # @param name [Symbol] the parameter name
-  # @param type [Class] the expected Ruby type
-  # @param description [String, nil] optional description
-  # @param enum [Array, nil] optional list of allowed values
-  # @param default [Object, nil] default value when not provided
-  # @return [void]
+  # Defines an optional parameter.
+  #
+  # name:: Symbol - the parameter name
+  # type:: Class - the expected Ruby type
+  # description:: String or nil - optional description
+  # enum:: Array or nil - optional list of allowed values
+  # default:: Object or nil - default value when not provided
+  #
+  # Returns void.
   def optional(name, type, description: nil, enum: nil, default: nil)
     @parameters << Riffer::Tools::Param.new(
       name: name,
@@ -52,10 +54,13 @@ class Riffer::Tools::Params
     )
   end
 
-  # Validates arguments against parameter definitions
-  # @param arguments [Hash] the arguments to validate
-  # @return [Hash] validated arguments with defaults applied
-  # @raise [Riffer::ValidationError] if validation fails
+  # Validates arguments against parameter definitions.
+  #
+  # arguments:: Hash - the arguments to validate
+  #
+  # Returns Hash - validated arguments with defaults applied.
+  #
+  # Raises Riffer::ValidationError if validation fails.
   def validate(arguments)
     validated = {}
     errors = []
@@ -91,8 +96,9 @@ class Riffer::Tools::Params
     validated
   end
 
-  # Converts all parameters to JSON Schema format
-  # @return [Hash] the JSON Schema representation
+  # Converts all parameters to JSON Schema format.
+  #
+  # Returns Hash - the JSON Schema representation.
   def to_json_schema
     properties = {}
     required_params = []

data/lib/riffer/tools/response.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Riffer::Tools::Response represents the result of a tool execution.
+#
+# All tools must return a Response object from their +call+ method.
+# Use +Response.success+ for successful results and +Response.error+ for failures.
+#
+#   class MyTool < Riffer::Tool
+#     def call(context:, **kwargs)
+#       result = perform_operation
+#       Riffer::Tools::Response.success(result)
+#     rescue MyError => e
+#       Riffer::Tools::Response.error(e.message)
+#     end
+#   end
+#
+class Riffer::Tools::Response
+  VALID_FORMATS = %i[text json].freeze
+
+  attr_reader :content, :error_message, :error_type
+
+  # Creates a success response.
+  #
+  # result:: Object - the tool result
+  # format:: Symbol - the format (:text or :json; default: :text)
+  #
+  # Returns Riffer::Tools::Response.
+  #
+  # Raises Riffer::ArgumentError if format is invalid.
+  def self.success(result, format: :text)
+    unless VALID_FORMATS.include?(format)
+      raise Riffer::ArgumentError, "Invalid format: #{format}. Must be one of: #{VALID_FORMATS.join(", ")}"
+    end
+
+    content = (format == :json) ? result.to_json : result.to_s
+    new(content: content, success: true)
+  end
+
+  # Creates a success response with text format.
+  #
+  # result:: Object - the tool result (converted via to_s)
+  #
+  # Returns Riffer::Tools::Response.
+  def self.text(result)
+    success(result, format: :text)
+  end
+
+  # Creates a success response with JSON format.
+  #
+  # result:: Object - the tool result (converted via to_json)
+  #
+  # Returns Riffer::Tools::Response.
+  def self.json(result)
+    success(result, format: :json)
+  end
+
+  # Creates an error response.
+  #
+  # message:: String - the error message
+  # type:: Symbol - the error type (default: :execution_error)
+  #
+  # Returns Riffer::Tools::Response.
+  def self.error(message, type: :execution_error)
+    new(content: message, success: false, error_message: message, error_type: type)
+  end
+
+  # Returns true if the response is successful.
+  def success? = @success
+
+  # Returns true if the response is an error.
+  def error? = !@success
+
+  # Returns a hash representation of the response.
+  #
+  # Returns Hash with :content, :error, and :error_type keys.
+  def to_h
+    {content: @content, error: @error_message, error_type: @error_type}
+  end
+
+  private
+
+  def initialize(content:, success:, error_message: nil, error_type: nil)
+    @content = content
+    @success = success
+    @error_message = error_message
+    @error_type = error_type
+  end
+end