riffer 0.7.0 → 0.8.0

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,35 @@ 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
+  # 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 Object - the tool result.
+  #
+  # Raises Riffer::ValidationError if validation fails.
+  # Raises Riffer::TimeoutError if execution exceeds the configured timeout.
   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)
+
+    Timeout.timeout(self.class.timeout) do
+      call(context: context, **validated_args)
+    end
+  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.rb

@@ -1,4 +1,9 @@
 # frozen_string_literal: true
 
+# Namespace for tool-related classes in the Riffer framework.
+#
+# Contains:
+# - Riffer::Tools::Params - DSL for defining tool parameters
+# - Riffer::Tools::Param - Individual parameter definition
 module Riffer::Tools
 end

data/lib/riffer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Riffer
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/riffer.rb

@@ -2,15 +2,11 @@
 
 require "zeitwerk"
 
-# :nodoc:
 # Riffer is the main module for the Riffer AI framework.
 #
 # Provides configuration, error classes, and versioning for the gem.
 #
-# @see Riffer::Config
-# @see Riffer::Agent
-# @see Riffer::Providers
-# @see Riffer::Messages
+# See Riffer::Config, Riffer::Agent, Riffer::Providers, and Riffer::Messages.
 loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect(
   "open_ai" => "OpenAI"
@@ -18,37 +14,41 @@ loader.inflector.inflect(
 loader.setup
 
 module Riffer
-  # Base error for Riffer
-  # @api public
+  # Base error class for Riffer.
   class Error < StandardError; end
 
-  # Argument error for Riffer
-  # @api public
+  # Raised when invalid arguments are provided.
   class ArgumentError < ::ArgumentError; end
 
-  # Validation error for tool parameter validation
-  # @api public
+  # Raised when tool parameter validation fails.
   class ValidationError < Error; end
 
-  # Provides configuration and versioning methods for Riffer
-  #
-  # @!group Configuration
+  # Raised when tool execution times out.
+  class TimeoutError < Error; end
+
   class << self
-    # Returns the Riffer configuration
-    # @return [Riffer::Config]
+    # Returns the Riffer configuration.
+    #
+    # Returns Riffer::Config.
     def config
       @config ||= Config.new
     end
 
-    # Yields the configuration for block-based setup
-    # @yieldparam config [Riffer::Config] the configuration object
-    # @return [void]
+    # Yields the configuration for block-based setup.
+    #
+    # Yields config (Riffer::Config) to the block.
+    #
+    #   Riffer.configure do |config|
+    #     config.openai.api_key = ENV['OPENAI_API_KEY']
+    #   end
+    #
     def configure
       yield config if block_given?
     end
 
-    # Returns the gem version
-    # @return [String] the version string
+    # Returns the gem version.
+    #
+    # Returns String.
     def version
       VERSION
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -29,6 +29,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 2.6.0
+- !ruby/object:Gem::Dependency
+  name: anthropic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.16.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.16.3
 - !ruby/object:Gem::Dependency
   name: aws-sdk-bedrockruntime
   requirement: !ruby/object:Gem::Requirement
@@ -139,6 +153,11 @@ extra_rdoc_files:
 - LICENSE.txt
 - README.md
 files:
+- ".agents/architecture.md"
+- ".agents/code-style.md"
+- ".agents/providers.md"
+- ".agents/rdoc.md"
+- ".agents/testing.md"
 - ".release-please-config.json"
 - ".release-please-manifest.json"
 - ".ruby-version"
@@ -149,6 +168,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/01_OVERVIEW.md
+- docs/02_GETTING_STARTED.md
+- docs/03_AGENTS.md
+- docs/04_TOOLS.md
+- docs/05_MESSAGES.md
+- docs/06_STREAM_EVENTS.md
+- docs/07_CONFIGURATION.md
+- docs_providers/01_PROVIDERS.md
+- docs_providers/02_AMAZON_BEDROCK.md
+- docs_providers/03_ANTHROPIC.md
+- docs_providers/04_OPENAI.md
+- docs_providers/05_TEST_PROVIDER.md
+- docs_providers/06_CUSTOM_PROVIDERS.md
 - lib/riffer.rb
 - lib/riffer/agent.rb
 - lib/riffer/config.rb
@@ -165,6 +197,7 @@ files:
 - lib/riffer/messages/user.rb
 - lib/riffer/providers.rb
 - lib/riffer/providers/amazon_bedrock.rb
+- lib/riffer/providers/anthropic.rb
 - lib/riffer/providers/base.rb
 - lib/riffer/providers/open_ai.rb
 - lib/riffer/providers/repository.rb