riffer 0.6.1 → 0.8.0

data/lib/riffer/agent.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
+require "json"
+
 # Riffer::Agent is the base class for all agents in the Riffer framework.
 #
 # Provides orchestration for LLM calls, tool use, and message management.
+# Subclass this to create your own agents.
+#
+# See Riffer::Messages and Riffer::Providers.
+#
+#   class MyAgent < Riffer::Agent
+#     model 'openai/gpt-4o'
+#     instructions 'You are a helpful assistant.'
+#   end
+#
+#   agent = MyAgent.new
+#   agent.generate('Hello!')
 #
-# @abstract
-# @see Riffer::Messages
-# @see Riffer::Providers
 class Riffer::Agent
   include Riffer::Messages::Converter
 
@@ -14,64 +24,99 @@ class Riffer::Agent
     include Riffer::Helpers::ClassNameConverter
     include Riffer::Helpers::Validations
 
-    # Gets or sets the agent identifier
-    # @param value [String, nil] the identifier to set, or nil to get
-    # @return [String] the agent identifier
+    # Gets or sets the agent identifier.
+    #
+    # value:: String or nil - the identifier to set, or nil to get
+    #
+    # Returns String - the agent identifier.
     def identifier(value = nil)
       return @identifier || class_name_to_path(name) if value.nil?
       @identifier = value.to_s
     end
 
-    # Gets or sets the model string (e.g., "openai/gpt-4")
-    # @param model_string [String, nil] the model string to set, or nil to get
-    # @return [String] the model string
+    # Gets or sets the model string (e.g., "openai/gpt-4o").
+    #
+    # model_string:: String or nil - the model string to set, or nil to get
+    #
+    # Returns String - the model string.
     def model(model_string = nil)
       return @model if model_string.nil?
       validate_is_string!(model_string, "model")
       @model = model_string
     end
 
-    # Gets or sets the agent instructions
-    # @param instructions_text [String, nil] the instructions to set, or nil to get
-    # @return [String] the agent instructions
+    # Gets or sets the agent instructions.
+    #
+    # instructions_text:: String or nil - the instructions to set, or nil to get
+    #
+    # Returns String - the agent instructions.
     def instructions(instructions_text = nil)
       return @instructions if instructions_text.nil?
       validate_is_string!(instructions_text, "instructions")
       @instructions = instructions_text
     end
 
-    def reasoning(level = nil)
-      return @reasoning if level.nil?
-      validate_is_string!(level, "reasoning")
-      @reasoning = level
+    # Gets or sets provider options passed to the provider client.
+    #
+    # options:: Hash or nil - the options to set, or nil to get
+    #
+    # Returns Hash - the provider options.
+    def provider_options(options = nil)
+      return @provider_options || {} if options.nil?
+      @provider_options = options
+    end
+
+    # Gets or sets model options passed to generate_text/stream_text.
+    #
+    # options:: Hash or nil - the options to set, or nil to get
+    #
+    # Returns Hash - the model options.
+    def model_options(options = nil)
+      return @model_options || {} if options.nil?
+      @model_options = options
+    end
+
+    # Gets or sets the tools used by this agent.
+    #
+    # tools_or_lambda:: Array of Tool classes, Proc, or nil - tools array or lambda returning tools
+    #
+    # Returns Array, Proc, or nil - the tools configuration.
+    def uses_tools(tools_or_lambda = nil)
+      return @tools_config if tools_or_lambda.nil?
+      @tools_config = tools_or_lambda
     end
 
-    # Finds an agent class by identifier
-    # @param identifier [String] the identifier to search for
-    # @return [Class, nil] the agent class, or nil if not found
+    # Finds an agent class by identifier.
+    #
+    # identifier:: String - the identifier to search for
+    #
+    # Returns Class or nil - the agent class, or nil if not found.
     def find(identifier)
       subclasses.find { |agent_class| agent_class.identifier == identifier.to_s }
     end
 
-    # Returns all agent subclasses
-    # @return [Array<Class>] all agent subclasses
+    # Returns all agent subclasses.
+    #
+    # Returns Array of Class - all agent subclasses.
     def all
       subclasses
     end
   end
 
-  # The message history for the agent
-  # @return [Array<Riffer::Messages::Base>]
+  # The message history for the agent.
+  #
+  # Returns Array of Riffer::Messages::Base.
   attr_reader :messages
 
-  # Initializes a new agent
-  # @raise [Riffer::ArgumentError] if the configured model string is invalid (must be "provider/model")
-  # @return [void]
+  # Initializes a new agent.
+  #
+  # Raises Riffer::ArgumentError if the configured model string is invalid
+  # (must be "provider/model" format).
   def initialize
     @messages = []
+    @message_callbacks = []
     @model_string = self.class.model
     @instructions_text = self.class.instructions
-    @reasoning = self.class.reasoning
 
     provider_name, model_name = @model_string.split("/", 2)
 
@@ -81,15 +126,20 @@ class Riffer::Agent
     @model_name = model_name
   end
 
-  # Generates a response from the agent
-  # @param prompt_or_messages [String, Array<Hash, Riffer::Messages::Base>]
-  # @return [String]
-  def generate(prompt_or_messages)
+  # Generates a response from the agent.
+  #
+  # prompt_or_messages:: String or Array - a string prompt or array of message hashes/objects
+  # tool_context:: Object or nil - optional context object passed to all tool calls
+  #
+  # Returns String - the final response content.
+  def generate(prompt_or_messages, tool_context: nil)
+    @tool_context = tool_context
+    @resolved_tools = nil
     initialize_messages(prompt_or_messages)
 
     loop do
       response = call_llm
-      @messages << response
+      add_message(response)
 
       break unless has_tool_calls?(response)
 
@@ -99,33 +149,76 @@ class Riffer::Agent
     extract_final_response
   end
 
-  # Streams a response from the agent
-  # @param prompt_or_messages [String, Array<Hash, Riffer::Messages::Base>]
-  # @return [Enumerator] an enumerator yielding stream events
-  def stream(prompt_or_messages)
+  # Streams a response from the agent.
+  #
+  # prompt_or_messages:: String or Array - a string prompt or array of message hashes/objects
+  # tool_context:: Object or nil - optional context object passed to all tool calls
+  #
+  # Returns Enumerator - an enumerator yielding stream events.
+  def stream(prompt_or_messages, tool_context: nil)
+    @tool_context = tool_context
+    @resolved_tools = nil
     initialize_messages(prompt_or_messages)
 
     Enumerator.new do |yielder|
-      accumulated_content = ""
+      loop do
+        accumulated_content = ""
+        accumulated_tool_calls = []
+        current_tool_call = nil
+
+        call_llm_stream.each do |event|
+          yielder << event
+
+          case event
+          when Riffer::StreamEvents::TextDelta
+            accumulated_content += event.content
+          when Riffer::StreamEvents::TextDone
+            accumulated_content = event.content
+          when Riffer::StreamEvents::ToolCallDelta
+            current_tool_call ||= {item_id: event.item_id, name: event.name, arguments: ""}
+            current_tool_call[:arguments] += event.arguments_delta
+            current_tool_call[:name] ||= event.name
+          when Riffer::StreamEvents::ToolCallDone
+            accumulated_tool_calls << {
+              id: event.item_id,
+              call_id: event.call_id,
+              name: event.name,
+              arguments: event.arguments
+            }
+            current_tool_call = nil
+          end
+        end
 
-      call_llm_stream.each do |event|
-        yielder << event
+        response = Riffer::Messages::Assistant.new(accumulated_content, tool_calls: accumulated_tool_calls)
+        add_message(response)
 
-        case event
-        when Riffer::StreamEvents::TextDelta
-          accumulated_content += event.content
-        when Riffer::StreamEvents::TextDone
-          accumulated_content = event.content
-        end
-      end
+        break unless has_tool_calls?(response)
 
-      response = Riffer::Messages::Assistant.new(accumulated_content)
-      @messages << response
+        execute_tool_calls(response)
+      end
     end
   end
 
+  # Registers a callback to be invoked when messages are added during generation.
+  #
+  # block:: Block - callback receiving a Riffer::Messages::Base subclass
+  #
+  # Raises Riffer::ArgumentError if no block is given.
+  #
+  # Returns self for method chaining.
+  def on_message(&block)
+    raise Riffer::ArgumentError, "on_message requires a block" unless block_given?
+    @message_callbacks << block
+    self
+  end
+
   private
 
+  def add_message(message)
+    @messages << message
+    @message_callbacks.each { |callback| callback.call(message) }
+  end
+
   def initialize_messages(prompt_or_messages)
     @messages = []
     @messages << Riffer::Messages::System.new(@instructions_text) if @instructions_text
@@ -140,18 +233,28 @@ class Riffer::Agent
   end
 
   def call_llm
-    provider_instance.generate_text(messages: @messages, model: @model_name, reasoning: @reasoning)
+    provider_instance.generate_text(
+      messages: @messages,
+      model: @model_name,
+      tools: resolved_tools,
+      **self.class.model_options
+    )
   end
 
   def call_llm_stream
-    provider_instance.stream_text(messages: @messages, model: @model_name, reasoning: @reasoning)
+    provider_instance.stream_text(
+      messages: @messages,
+      model: @model_name,
+      tools: resolved_tools,
+      **self.class.model_options
+    )
   end
 
   def provider_instance
     @provider_instance ||= begin
       provider_class = Riffer::Providers::Repository.find(@provider_name)
       raise Riffer::ArgumentError, "Provider not found: #{@provider_name}" unless provider_class
-      provider_class.new
+      provider_class.new(**self.class.provider_options)
     end
   end
 
@@ -161,17 +264,77 @@ class Riffer::Agent
 
   def execute_tool_calls(response)
     response.tool_calls.each do |tool_call|
-      tool_result = execute_tool_call(tool_call)
-      @messages << Riffer::Messages::Tool.new(
-        tool_result,
+      result = execute_tool_call(tool_call)
+      add_message(Riffer::Messages::Tool.new(
+        result[:content],
         tool_call_id: tool_call[:id],
-        name: tool_call[:name]
-      )
+        name: tool_call[:name],
+        error: result[:error],
+        error_type: result[:error_type]
+      ))
     end
   end
 
   def execute_tool_call(tool_call)
-    "Tool execution not implemented yet"
+    tool_class = find_tool_class(tool_call[:name])
+
+    if tool_class.nil?
+      return {
+        content: "Error: Unknown tool '#{tool_call[:name]}'",
+        error: "Unknown tool '#{tool_call[:name]}'",
+        error_type: :unknown_tool
+      }
+    end
+
+    tool_instance = tool_class.new
+    arguments = parse_tool_arguments(tool_call[:arguments])
+
+    begin
+      result = tool_instance.call_with_validation(context: @tool_context, **arguments)
+      {content: result.to_s, error: nil, error_type: nil}
+    rescue Riffer::TimeoutError => e
+      {
+        content: "Error: #{e.message}",
+        error: e.message,
+        error_type: :timeout_error
+      }
+    rescue Riffer::ValidationError => e
+      {
+        content: "Validation error: #{e.message}",
+        error: e.message,
+        error_type: :validation_error
+      }
+    rescue => e
+      {
+        content: "Error executing tool: #{e.message}",
+        error: e.message,
+        error_type: :execution_error
+      }
+    end
+  end
+
+  def resolved_tools
+    @resolved_tools ||= begin
+      config = self.class.uses_tools
+      return [] if config.nil?
+
+      if config.is_a?(Proc)
+        (config.arity == 0) ? config.call : config.call(@tool_context)
+      else
+        config
+      end
+    end
+  end
+
+  def find_tool_class(name)
+    resolved_tools.find { |tool_class| tool_class.name == name }
+  end
+
+  def parse_tool_arguments(arguments)
+    return {} if arguments.nil? || arguments.empty?
+
+    args = arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+    args.transform_keys(&:to_sym)
   end
 
   def extract_final_response

data/lib/riffer/config.rb

@@ -1,28 +1,36 @@
 # frozen_string_literal: true
 
-# Configuration for the Riffer framework
+# Configuration for the Riffer framework.
 #
 # Provides configuration options for AI providers and other settings.
 #
-# @example Setting the OpenAI API key
 #   Riffer.config.openai.api_key = "sk-..."
 #
-# @example Setting Amazon Bedrock configuration
 #   Riffer.config.amazon_bedrock.region = "us-east-1"
 #   Riffer.config.amazon_bedrock.api_token = "..."
+#
+#   Riffer.config.anthropic.api_key = "sk-ant-..."
+#
 class Riffer::Config
-  # OpenAI configuration
-  # @return [Struct]
-  attr_reader :openai
-
-  # Amazon Bedrock configuration
-  # @return [Struct]
+  # Amazon Bedrock configuration (Struct with +api_token+ and +region+).
+  #
+  # Returns Struct.
   attr_reader :amazon_bedrock
 
-  # Initializes the configuration
-  # @return [void]
+  # Anthropic configuration (Struct with +api_key+).
+  #
+  # Returns Struct.
+  attr_reader :anthropic
+
+  # OpenAI configuration (Struct with +api_key+).
+  #
+  # Returns Struct.
+  attr_reader :openai
+
+  # Initializes the configuration.
   def initialize
-    @openai = Struct.new(:api_key).new
     @amazon_bedrock = Struct.new(:api_token, :region).new
+    @anthropic = Struct.new(:api_key).new
+    @openai = Struct.new(:api_key).new
   end
 end

data/lib/riffer/core.rb

@@ -6,21 +6,21 @@ require "logger"
 #
 # Handles logging and configuration for the framework.
 class Riffer::Core
-  # The logger instance for Riffer
-  # @return [Logger]
+  # The logger instance for Riffer.
+  #
+  # Returns Logger.
   attr_reader :logger
 
-  # Initializes the core object and logger
-  # @return [void]
+  # Initializes the core object and logger.
   def initialize
     @logger = Logger.new($stdout)
     @logger.level = Logger::INFO
     @storage_registry = {}
   end
 
-  # Yields self for configuration
-  # @yieldparam core [Riffer::Core] the core object
-  # @return [void]
+  # Yields self for configuration.
+  #
+  # Yields core (Riffer::Core) to the block.
   def configure
     yield self if block_given?
   end

data/lib/riffer/helpers/class_name_converter.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+# Helper module for converting class names.
 module Riffer::Helpers::ClassNameConverter
-  # Converts a class name to snake_case path format
-  # @param class_name [String] the class name (e.g., "Riffer::Agent")
-  # @return [String] the snake_case path (e.g., "riffer/agent")
+  # Converts a class name to snake_case path format.
+  #
+  # class_name:: String - the class name (e.g., "Riffer::Agent")
+  #
+  # Returns String - the snake_case path (e.g., "riffer/agent").
   def class_name_to_path(class_name)
     class_name
       .to_s

data/lib/riffer/helpers/dependencies.rb

@@ -1,9 +1,27 @@
 # frozen_string_literal: true
 
+# Helper module for lazy loading gem dependencies.
+#
+# Used by providers to load their required gems only when needed.
 module Riffer::Helpers::Dependencies
+  # Raised when a required gem cannot be loaded.
   class LoadError < ::LoadError; end
+
+  # Raised when a gem version requirement is not satisfied.
   class VersionError < ScriptError; end
 
+  # Declares a dependency on a gem.
+  #
+  # Verifies the gem is installed and satisfies version requirements,
+  # then requires it.
+  #
+  # gem_name:: String - the gem name
+  # req:: Boolean or String - true to require the gem, false to skip, or String to require a different lib
+  #
+  # Returns true if successful.
+  #
+  # Raises LoadError if the gem is not installed.
+  # Raises VersionError if the gem version does not satisfy requirements.
   def depends_on(gem_name, req: true)
     gem(gem_name)
 

data/lib/riffer/helpers/validations.rb

@@ -1,6 +1,15 @@
 # frozen_string_literal: true
 
+# Helper module for input validation.
 module Riffer::Helpers::Validations
+  # Validates that a value is a non-empty string.
+  #
+  # value:: Object - the value to validate
+  # name:: String - the name of the value for error messages
+  #
+  # Returns true if valid.
+  #
+  # Raises Riffer::ArgumentError if the value is not a string or is empty.
   def validate_is_string!(value, name = "value")
     raise Riffer::ArgumentError, "#{name} must be a String" unless value.is_a?(String)
     raise Riffer::ArgumentError, "#{name} cannot be empty" if value.strip.empty?

data/lib/riffer/messages/assistant.rb

@@ -1,17 +1,39 @@
 # frozen_string_literal: true
 
+# Represents an assistant (LLM) message in a conversation.
+#
+# May include tool calls when the LLM requests tool execution.
+#
+#   msg = Riffer::Messages::Assistant.new("Hello!")
+#   msg.role        # => :assistant
+#   msg.content     # => "Hello!"
+#   msg.tool_calls  # => []
+#
 class Riffer::Messages::Assistant < Riffer::Messages::Base
+  # Array of tool calls requested by the assistant.
+  #
+  # Each tool call is a Hash with +:id+, +:call_id+, +:name+, and +:arguments+ keys.
+  #
+  # Returns Array of Hash.
   attr_reader :tool_calls
 
+  # Creates a new assistant message.
+  #
+  # content:: String - the message content
+  # tool_calls:: Array of Hash - optional tool calls
   def initialize(content, tool_calls: [])
     super(content)
     @tool_calls = tool_calls
   end
 
+  # Returns :assistant.
   def role
-    "assistant"
+    :assistant
   end
 
+  # Converts the message to a hash.
+  #
+  # Returns Hash with +:role+, +:content+, and optionally +:tool_calls+.
   def to_h
     hash = {role: role, content: content}
     hash[:tool_calls] = tool_calls unless tool_calls.empty?

data/lib/riffer/messages/base.rb

@@ -1,16 +1,31 @@
 # frozen_string_literal: true
 
+# Base class for all message types in the Riffer framework.
+#
+# Subclasses must implement the +role+ method.
 class Riffer::Messages::Base
+  # The message content.
+  #
+  # Returns String.
   attr_reader :content
 
+  # Creates a new message.
+  #
+  # content:: String - the message content
   def initialize(content)
     @content = content
   end
 
+  # Converts the message to a hash.
+  #
+  # Returns Hash with +:role+ and +:content+ keys.
   def to_h
     {role: role, content: content}
   end
 
+  # Returns the message role.
+  #
+  # Raises NotImplementedError if not implemented by subclass.
   def role
     raise NotImplementedError, "Subclasses must implement #role"
   end

data/lib/riffer/messages/converter.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
+# Module for converting hashes to message objects.
+#
+# Included in Agent and Provider classes to handle message normalization.
 module Riffer::Messages::Converter
+  # Converts a hash or message object to a Riffer::Messages::Base subclass.
+  #
+  # msg:: Hash or Riffer::Messages::Base - the message to convert
+  #
+  # Returns Riffer::Messages::Base subclass.
+  #
+  # Raises Riffer::ArgumentError if the message format is invalid.
   def convert_to_message_object(msg)
     return msg if msg.is_a?(Riffer::Messages::Base)
 
@@ -21,15 +31,15 @@ module Riffer::Messages::Converter
       raise Riffer::ArgumentError, "Message hash must include a 'role' key"
     end
 
-    case role
-    when "user"
+    case role.to_sym
+    when :user
       Riffer::Messages::User.new(content)
-    when "assistant"
+    when :assistant
       tool_calls = hash[:tool_calls] || hash["tool_calls"] || []
       Riffer::Messages::Assistant.new(content, tool_calls: tool_calls)
-    when "system"
+    when :system
       Riffer::Messages::System.new(content)
-    when "tool"
+    when :tool
       tool_call_id = hash[:tool_call_id] || hash["tool_call_id"]
       name = hash[:name] || hash["name"]
       Riffer::Messages::Tool.new(content, tool_call_id: tool_call_id, name: name)

data/lib/riffer/messages/system.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
+# Represents a system message (instructions) in a conversation.
+#
+#   msg = Riffer::Messages::System.new("You are a helpful assistant.")
+#   msg.role     # => :system
+#   msg.content  # => "You are a helpful assistant."
+#
 class Riffer::Messages::System < Riffer::Messages::Base
+  # Returns :system.
   def role
-    "system"
+    :system
   end
 end