riffer 0.7.0 → 0.9.0

data/docs_providers/06_CUSTOM_PROVIDERS.md

@@ -0,0 +1,304 @@
+# Creating Custom Providers
+
+You can create custom providers to connect Riffer to other LLM services.
+
+## Basic Structure
+
+Extend `Riffer::Providers::Base` and implement the required methods:
+
+```ruby
+class Riffer::Providers::MyProvider < Riffer::Providers::Base
+  def initialize(**options)
+    # Initialize your client
+    @api_key = options[:api_key] || ENV['MY_PROVIDER_API_KEY']
+    @client = MyProviderClient.new(api_key: @api_key)
+  end
+
+  private
+
+  def perform_generate_text(messages, model:, **options)
+    # Convert messages to provider format
+    formatted = convert_messages(messages)
+
+    # Call your provider's API
+    response = @client.generate(
+      model: model,
+      messages: formatted,
+      **options
+    )
+
+    # Return a Riffer::Messages::Assistant
+    Riffer::Messages::Assistant.new(
+      response.text,
+      tool_calls: extract_tool_calls(response)
+    )
+  end
+
+  def perform_stream_text(messages, model:, **options)
+    Enumerator.new do |yielder|
+      formatted = convert_messages(messages)
+
+      @client.stream(model: model, messages: formatted, **options) do |chunk|
+        # Yield appropriate stream events
+        case chunk.type
+        when :text
+          yielder << Riffer::StreamEvents::TextDelta.new(chunk.content)
+        when :text_done
+          yielder << Riffer::StreamEvents::TextDone.new(chunk.content)
+        when :tool_call
+          yielder << Riffer::StreamEvents::ToolCallDone.new(
+            item_id: chunk.id,
+            call_id: chunk.id,
+            name: chunk.name,
+            arguments: chunk.arguments
+          )
+        end
+      end
+    end
+  end
+
+  def convert_messages(messages)
+    messages.map do |msg|
+      case msg
+      when Riffer::Messages::System
+        {role: "system", content: msg.content}
+      when Riffer::Messages::User
+        {role: "user", content: msg.content}
+      when Riffer::Messages::Assistant
+        convert_assistant(msg)
+      when Riffer::Messages::Tool
+        {role: "tool", tool_call_id: msg.tool_call_id, content: msg.content}
+      end
+    end
+  end
+
+  def convert_assistant(msg)
+    # Handle tool calls if present
+    {role: "assistant", content: msg.content, tool_calls: msg.tool_calls}
+  end
+
+  def extract_tool_calls(response)
+    return [] unless response.tool_calls
+
+    response.tool_calls.map do |tc|
+      {
+        id: tc.id,
+        call_id: tc.id,
+        name: tc.name,
+        arguments: tc.arguments
+      }
+    end
+  end
+end
+```
+
+## Using depends_on
+
+For lazy loading of external gems:
+
+```ruby
+class Riffer::Providers::MyProvider < Riffer::Providers::Base
+  def initialize(**options)
+    depends_on "my_provider_gem"  # Only loaded when provider is used
+
+    @client = ::MyProviderGem::Client.new(**options)
+  end
+end
+```
+
+## Registering Your Provider
+
+Add your provider to the repository:
+
+```ruby
+# In lib/riffer/providers/repository.rb or your own code
+
+Riffer::Providers::Repository::REPO[:my_provider] = -> { Riffer::Providers::MyProvider }
+```
+
+Or create a custom repository:
+
+```ruby
+module MyApp
+  module Providers
+    def self.find(identifier)
+      case identifier.to_sym
+      when :my_provider
+        Riffer::Providers::MyProvider
+      else
+        Riffer::Providers::Repository.find(identifier)
+      end
+    end
+  end
+end
+```
+
+## Using Your Provider
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'my_provider/model-name'
+end
+```
+
+## Tool Support
+
+Convert tools to your provider's format:
+
+```ruby
+def perform_generate_text(messages, model:, tools: nil, **options)
+  params = {
+    model: model,
+    messages: convert_messages(messages)
+  }
+
+  if tools && !tools.empty?
+    params[:tools] = tools.map { |t| convert_tool(t) }
+  end
+
+  response = @client.generate(**params)
+  # ...
+end
+
+def convert_tool(tool)
+  {
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters_schema
+  }
+end
+```
+
+## Stream Events
+
+Use the appropriate stream event classes:
+
+```ruby
+# Text streaming
+Riffer::StreamEvents::TextDelta.new("chunk of text")
+Riffer::StreamEvents::TextDone.new("complete text")
+
+# Tool calls
+Riffer::StreamEvents::ToolCallDelta.new(
+  item_id: "id",
+  name: "tool_name",
+  arguments_delta: '{"partial":'
+)
+Riffer::StreamEvents::ToolCallDone.new(
+  item_id: "id",
+  call_id: "call_id",
+  name: "tool_name",
+  arguments: '{"complete":"args"}'
+)
+
+# Reasoning (if supported)
+Riffer::StreamEvents::ReasoningDelta.new("thinking...")
+Riffer::StreamEvents::ReasoningDone.new("complete reasoning")
+```
+
+## Error Handling
+
+Raise appropriate Riffer errors:
+
+```ruby
+def perform_generate_text(messages, model:, **options)
+  response = @client.generate(...)
+
+  if response.error?
+    raise Riffer::Error, "Provider error: #{response.error_message}"
+  end
+
+  # ...
+rescue MyProviderGem::AuthError => e
+  raise Riffer::ArgumentError, "Authentication failed: #{e.message}"
+end
+```
+
+## Complete Example
+
+```ruby
+# lib/riffer/providers/anthropic.rb
+
+class Riffer::Providers::Anthropic < Riffer::Providers::Base
+  def initialize(**options)
+    depends_on "anthropic"
+
+    api_key = options[:api_key] || ENV['ANTHROPIC_API_KEY']
+    @client = ::Anthropic::Client.new(api_key: api_key)
+  end
+
+  private
+
+  def perform_generate_text(messages, model:, tools: nil, **options)
+    system_message = extract_system(messages)
+    conversation = messages.reject { |m| m.is_a?(Riffer::Messages::System) }
+
+    params = {
+      model: model,
+      messages: convert_messages(conversation),
+      system: system_message,
+      max_tokens: options[:max_tokens] || 4096
+    }
+
+    if tools && !tools.empty?
+      params[:tools] = tools.map { |t| convert_tool(t) }
+    end
+
+    response = @client.messages.create(**params)
+    extract_assistant_message(response)
+  end
+
+  def perform_stream_text(messages, model:, tools: nil, **options)
+    Enumerator.new do |yielder|
+      # Similar implementation with streaming
+    end
+  end
+
+  def extract_system(messages)
+    system_msg = messages.find { |m| m.is_a?(Riffer::Messages::System) }
+    system_msg&.content
+  end
+
+  def convert_messages(messages)
+    messages.map do |msg|
+      case msg
+      when Riffer::Messages::User
+        {role: "user", content: msg.content}
+      when Riffer::Messages::Assistant
+        {role: "assistant", content: msg.content}
+      when Riffer::Messages::Tool
+        {role: "user", content: [{type: "tool_result", tool_use_id: msg.tool_call_id, content: msg.content}]}
+      end
+    end
+  end
+
+  def convert_tool(tool)
+    {
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.parameters_schema
+    }
+  end
+
+  def extract_assistant_message(response)
+    text = ""
+    tool_calls = []
+
+    response.content.each do |block|
+      case block.type
+      when "text"
+        text = block.text
+      when "tool_use"
+        tool_calls << {
+          id: block.id,
+          call_id: block.id,
+          name: block.name,
+          arguments: block.input.to_json
+        }
+      end
+    end
+
+    Riffer::Messages::Assistant.new(text, tool_calls: tool_calls)
+  end
+end
+```

data/lib/riffer/agent.rb

@@ -5,10 +5,18 @@ 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
 
@@ -16,79 +24,97 @@ 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
 
-    # Gets or sets provider options passed to the provider client
-    # @param options [Hash, nil] the options to set, or nil to get
-    # @return [Hash] the provider options
+    # 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
-    # @param options [Hash, nil] the options to set, or nil to get
-    # @return [Hash] the model options
+    # 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
-    # @param tools_or_lambda [Array<Class>, Proc, nil] tools array or lambda returning tools
-    # @return [Array<Class>, Proc, nil] the tools configuration
+    # 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
 
@@ -100,10 +126,12 @@ class Riffer::Agent
     @model_name = model_name
   end
 
-  # Generates a response from the agent
-  # @param prompt_or_messages [String, Array<Hash, Riffer::Messages::Base>]
-  # @param tool_context [Object, nil] optional context object passed to all tool calls
-  # @return [String]
+  # 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
@@ -111,7 +139,7 @@ class Riffer::Agent
 
     loop do
       response = call_llm
-      @messages << response
+      add_message(response)
 
       break unless has_tool_calls?(response)
 
@@ -121,10 +149,12 @@ class Riffer::Agent
     extract_final_response
   end
 
-  # Streams a response from the agent
-  # @param prompt_or_messages [String, Array<Hash, Riffer::Messages::Base>]
-  # @param tool_context [Object, nil] optional context object passed to all tool calls
-  # @return [Enumerator] an enumerator yielding stream events
+  # 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
@@ -160,7 +190,7 @@ class Riffer::Agent
         end
 
         response = Riffer::Messages::Assistant.new(accumulated_content, tool_calls: accumulated_tool_calls)
-        @messages << response
+        add_message(response)
 
         break unless has_tool_calls?(response)
 
@@ -169,8 +199,26 @@ class Riffer::Agent
     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
@@ -217,13 +265,13 @@ class Riffer::Agent
   def execute_tool_calls(response)
     response.tool_calls.each do |tool_call|
       result = execute_tool_call(tool_call)
-      @messages << Riffer::Messages::Tool.new(
-        result[:content],
+      add_message(Riffer::Messages::Tool.new(
+        result.content,
         tool_call_id: tool_call[:id],
         name: tool_call[:name],
-        error: result[:error],
-        error_type: result[:error_type]
-      )
+        error: result.error_message,
+        error_type: result.error_type
+      ))
     end
   end
 
@@ -231,31 +279,23 @@ class Riffer::Agent
     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
-      }
+      return Riffer::Tools::Response.error(
+        "Unknown tool '#{tool_call[:name]}'",
+        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}
+      tool_instance.call_with_validation(context: @tool_context, **arguments)
+    rescue Riffer::TimeoutError => e
+      Riffer::Tools::Response.error(e.message, type: :timeout_error)
     rescue Riffer::ValidationError => e
-      {
-        content: "Validation error: #{e.message}",
-        error: e.message,
-        error_type: :validation_error
-      }
+      Riffer::Tools::Response.error(e.message, type: :validation_error)
     rescue => e
-      {
-        content: "Error executing tool: #{e.message}",
-        error: e.message,
-        error_type: :execution_error
-      }
+      Riffer::Tools::Response.error("Error executing tool: #{e.message}", type: :execution_error)
     end
   end
 

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