riffer 0.7.0 → 0.8.0

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

data/lib/riffer/messages/tool.rb

@@ -1,8 +1,44 @@
 # frozen_string_literal: true
 
+# Represents a tool execution result in a conversation.
+#
+#   msg = Riffer::Messages::Tool.new(
+#     "The weather is sunny.",
+#     tool_call_id: "call_123",
+#     name: "weather_tool"
+#   )
+#   msg.role          # => :tool
+#   msg.tool_call_id  # => "call_123"
+#   msg.error?        # => false
+#
 class Riffer::Messages::Tool < Riffer::Messages::Base
-  attr_reader :tool_call_id, :name, :error, :error_type
+  # The ID of the tool call this result responds to.
+  #
+  # Returns String.
+  attr_reader :tool_call_id
 
+  # The name of the tool that was called.
+  #
+  # Returns String.
+  attr_reader :name
+
+  # The error message if the tool execution failed.
+  #
+  # Returns String or nil.
+  attr_reader :error
+
+  # The type of error (:unknown_tool, :validation_error, :execution_error, :timeout_error).
+  #
+  # Returns Symbol or nil.
+  attr_reader :error_type
+
+  # Creates a new tool result message.
+  #
+  # content:: String - the tool execution result
+  # tool_call_id:: String - the ID of the tool call
+  # name:: String - the tool name
+  # error:: String or nil - optional error message
+  # error_type:: Symbol or nil - optional error type
   def initialize(content, tool_call_id:, name:, error: nil, error_type: nil)
     super(content)
     @tool_call_id = tool_call_id
@@ -11,14 +47,21 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
     @error_type = error_type
   end
 
+  # Returns true if the tool execution resulted in an error.
+  #
+  # Returns Boolean.
   def error?
     !@error.nil?
   end
 
+  # Returns :tool.
   def role
-    "tool"
+    :tool
   end
 
+  # Converts the message to a hash.
+  #
+  # Returns Hash with message data including error info if present.
   def to_h
     hash = {role: role, content: content, tool_call_id: tool_call_id, name: name}
     if error?

data/lib/riffer/messages/user.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
+# Represents a user message in a conversation.
+#
+#   msg = Riffer::Messages::User.new("Hello!")
+#   msg.role     # => :user
+#   msg.content  # => "Hello!"
+#
 class Riffer::Messages::User < Riffer::Messages::Base
+  # Returns :user.
   def role
-    "user"
+    :user
   end
 end

data/lib/riffer/messages.rb

@@ -1,4 +1,11 @@
 # frozen_string_literal: true
 
+# Namespace for message types in the Riffer framework.
+#
+# Message objects represent the conversation between users and the assistant:
+# - Riffer::Messages::System - System instructions
+# - Riffer::Messages::User - User input
+# - Riffer::Messages::Assistant - LLM responses
+# - Riffer::Messages::Tool - Tool execution results
 module Riffer::Messages
 end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -2,13 +2,17 @@
 
 require "json"
 
+# Amazon Bedrock provider for Claude and other foundation models.
+#
+# Requires the +aws-sdk-bedrockruntime+ gem to be installed.
+#
+# See https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockRuntime/Client.html
 class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # Initializes the Amazon Bedrock provider.
   #
-  # @param options [Hash] options passed to Aws::BedrockRuntime::Client
-  # @option options [String] :api_token Bearer token for API authentication (requires :region)
-  # @option options [String] :region AWS region
-  # @see https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockRuntime/Client.html
+  # api_token:: String or nil - Bearer token for API authentication
+  # region:: String or nil - AWS region
+  # options:: Hash - additional options passed to Aws::BedrockRuntime::Client
   def initialize(api_token: nil, region: nil, **options)
     depends_on "aws-sdk-bedrockruntime"
 

data/lib/riffer/providers/anthropic.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Anthropic provider for Claude models via the Anthropic API.
+#
+# Requires the +anthropic+ gem to be installed.
+#
+# See https://github.com/anthropics/anthropic-sdk-ruby
+class Riffer::Providers::Anthropic < Riffer::Providers::Base
+  # Initializes the Anthropic provider.
+  #
+  # api_key:: String or nil - Anthropic API key
+  # options:: Hash - additional options passed to Anthropic::Client
+  def initialize(api_key: nil, **options)
+    depends_on "anthropic"
+
+    api_key ||= Riffer.config.anthropic.api_key
+
+    @client = Anthropic::Client.new(api_key: api_key, **options)
+  end
+
+  private
+
+  def perform_generate_text(messages, model:, **options)
+    partitioned_messages = partition_messages(messages)
+    tools = options[:tools]
+
+    max_tokens = options.fetch(:max_tokens, 4096)
+
+    params = {
+      model: model,
+      messages: partitioned_messages[:conversation],
+      max_tokens: max_tokens,
+      **options.except(:tools, :max_tokens)
+    }
+
+    params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
+
+    if tools && !tools.empty?
+      params[:tools] = tools.map { |t| convert_tool_to_anthropic_format(t) }
+    end
+
+    response = @client.messages.create(**params)
+    extract_assistant_message(response)
+  end
+
+  def perform_stream_text(messages, model:, **options)
+    Enumerator.new do |yielder|
+      partitioned_messages = partition_messages(messages)
+      tools = options[:tools]
+
+      max_tokens = options.fetch(:max_tokens, 4096)
+
+      params = {
+        model: model,
+        messages: partitioned_messages[:conversation],
+        max_tokens: max_tokens,
+        **options.except(:tools, :max_tokens)
+      }
+
+      params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
+
+      if tools && !tools.empty?
+        params[:tools] = tools.map { |t| convert_tool_to_anthropic_format(t) }
+      end
+
+      accumulated_text = ""
+      accumulated_reasoning = ""
+      current_tool_use = nil
+
+      stream = @client.messages.stream(**params)
+      stream.each do |event|
+        case event
+        when Anthropic::Streaming::TextEvent
+          accumulated_text += event.text
+          yielder << Riffer::StreamEvents::TextDelta.new(event.text)
+
+        when Anthropic::Streaming::ThinkingEvent
+          accumulated_reasoning += event.thinking
+          yielder << Riffer::StreamEvents::ReasoningDelta.new(event.thinking)
+
+        when Anthropic::Streaming::InputJsonEvent
+          # Tool call JSON delta - we need to track the tool use block
+          if current_tool_use.nil?
+            # Find the current tool use block being built
+            current_tool_use = {id: nil, name: nil, arguments: ""}
+          end
+          current_tool_use[:arguments] += event.partial_json
+          yielder << Riffer::StreamEvents::ToolCallDelta.new(
+            item_id: current_tool_use[:id] || "pending",
+            name: current_tool_use[:name],
+            arguments_delta: event.partial_json
+          )
+
+        when Anthropic::Streaming::ContentBlockStopEvent
+          content_block = event.content_block
+          if content_block.respond_to?(:type)
+            block_type = content_block.type.to_s
+            if block_type == "tool_use"
+              # content_block.input is already a JSON string when streaming
+              arguments = content_block.input.is_a?(String) ? content_block.input : content_block.input.to_json
+              yielder << Riffer::StreamEvents::ToolCallDone.new(
+                item_id: content_block.id,
+                call_id: content_block.id,
+                name: content_block.name,
+                arguments: arguments
+              )
+              current_tool_use = nil
+            elsif block_type == "thinking" && !accumulated_reasoning.empty?
+              yielder << Riffer::StreamEvents::ReasoningDone.new(accumulated_reasoning)
+            end
+          end
+
+        when Anthropic::Streaming::MessageStopEvent
+          yielder << Riffer::StreamEvents::TextDone.new(accumulated_text)
+        end
+      end
+    end
+  end
+
+  def partition_messages(messages)
+    system_prompts = []
+    conversation_messages = []
+
+    messages.each do |message|
+      case message
+      when Riffer::Messages::System
+        system_prompts << {type: "text", text: message.content}
+      when Riffer::Messages::User
+        conversation_messages << {role: "user", content: message.content}
+      when Riffer::Messages::Assistant
+        conversation_messages << convert_assistant_to_anthropic_format(message)
+      when Riffer::Messages::Tool
+        conversation_messages << {
+          role: "user",
+          content: [{
+            type: "tool_result",
+            tool_use_id: message.tool_call_id,
+            content: message.content
+          }]
+        }
+      end
+    end
+
+    {
+      system: system_prompts.empty? ? nil : system_prompts,
+      conversation: conversation_messages
+    }
+  end
+
+  def convert_assistant_to_anthropic_format(message)
+    content = []
+    content << {type: "text", text: message.content} if message.content && !message.content.empty?
+
+    message.tool_calls.each do |tc|
+      content << {
+        type: "tool_use",
+        id: tc[:id] || tc[:call_id],
+        name: tc[:name],
+        input: parse_tool_arguments(tc[:arguments])
+      }
+    end
+
+    {role: "assistant", content: content}
+  end
+
+  def parse_tool_arguments(arguments)
+    return {} if arguments.nil? || arguments.empty?
+    arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+  end
+
+  def extract_assistant_message(response)
+    content_blocks = response.content
+    raise Riffer::Error, "No content returned from Anthropic API" if content_blocks.nil? || content_blocks.empty?
+
+    text_content = ""
+    tool_calls = []
+
+    content_blocks.each do |block|
+      block_type = block.type.to_s
+      case block_type
+      when "text"
+        text_content = block.text
+      when "tool_use"
+        tool_calls << {
+          id: block.id,
+          call_id: block.id,
+          name: block.name,
+          arguments: block.input.to_json
+        }
+      end
+    end
+
+    if text_content.empty? && tool_calls.empty?
+      raise Riffer::Error, "No content returned from Anthropic API"
+    end
+
+    Riffer::Messages::Assistant.new(text_content, tool_calls: tool_calls)
+  end
+
+  def convert_tool_to_anthropic_format(tool)
+    {
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.parameters_schema
+    }
+  end
+end

data/lib/riffer/providers/base.rb

@@ -1,17 +1,21 @@
 # frozen_string_literal: true
 
+# Base class for all LLM providers in the Riffer framework.
+#
+# Subclasses must implement +perform_generate_text+ and +perform_stream_text+.
 class Riffer::Providers::Base
   include Riffer::Helpers::Dependencies
   include Riffer::Messages::Converter
 
   # Generates text using the provider.
   #
-  # @param prompt [String, nil] the user prompt (required when `messages` is not provided)
-  # @param system [String, nil] an optional system message
-  # @param messages [Array<Hash, Riffer::Messages::Base>, nil] optional messages array
-  # @param model [String, nil] optional model string to override the configured model
-  # @param options [Hash] additional options passed to the model invocation
-  # @return [Riffer::Messages::Assistant] the generated assistant message
+  # prompt:: String or nil - the user prompt (required when messages is not provided)
+  # system:: String or nil - an optional system message
+  # messages:: Array or nil - optional messages array
+  # model:: String or nil - optional model string to override the configured model
+  # options:: Hash - additional options passed to the model invocation
+  #
+  # Returns Riffer::Messages::Assistant - the generated assistant message.
   def generate_text(prompt: nil, system: nil, messages: nil, model: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
     normalized_messages = normalize_messages(prompt: prompt, system: system, messages: messages)
@@ -21,12 +25,13 @@ class Riffer::Providers::Base
 
   # Streams text from the provider.
   #
-  # @param prompt [String, nil] the user prompt (required when `messages` is not provided)
-  # @param system [String, nil] an optional system message
-  # @param messages [Array<Hash, Riffer::Messages::Base>, nil] optional messages array
-  # @param model [String, nil] optional model string to override the configured model
-  # @param options [Hash] additional options passed to the model invocation
-  # @return [Enumerator] an enumerator yielding stream events or chunks (provider-specific)
+  # prompt:: String or nil - the user prompt (required when messages is not provided)
+  # system:: String or nil - an optional system message
+  # messages:: Array or nil - optional messages array
+  # model:: String or nil - optional model string to override the configured model
+  # options:: Hash - additional options passed to the model invocation
+  #
+  # Returns Enumerator - an enumerator yielding stream events.
   def stream_text(prompt: nil, system: nil, messages: nil, model: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
     normalized_messages = normalize_messages(prompt: prompt, system: system, messages: messages)

data/lib/riffer/providers/open_ai.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
+# OpenAI provider for GPT models.
+#
+# Requires the +openai+ gem to be installed.
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # Initializes the OpenAI provider.
-  # @param options [Hash] optional client options. Use `:api_key` to override `Riffer.config.openai.api_key`.
+  #
+  # options:: Hash - optional client options
+  #
+  # Use +:api_key+ to override +Riffer.config.openai.api_key+.
   def initialize(**options)
     depends_on "openai"
 

data/lib/riffer/providers/repository.rb

@@ -1,14 +1,19 @@
+# Registry for finding provider classes by identifier.
 class Riffer::Providers::Repository
+  # Mapping of provider identifiers to provider class lambdas.
   REPO = {
-    openai: -> { Riffer::Providers::OpenAI },
     amazon_bedrock: -> { Riffer::Providers::AmazonBedrock },
+    anthropic: -> { Riffer::Providers::Anthropic },
+    openai: -> { Riffer::Providers::OpenAI },
     test: -> { Riffer::Providers::Test }
   }.freeze
 
   class << self
-    # Finds a provider class by identifier
-    # @param identifier [String, Symbol] the identifier to search for
-    # @return [Class, nil] the provider class, or nil if not found
+    # Finds a provider class by identifier.
+    #
+    # identifier:: String or Symbol - the identifier to search for
+    #
+    # Returns Class or nil - the provider class, or nil if not found.
     def find(identifier)
       REPO.fetch(identifier.to_sym, nil)&.call
     end

data/lib/riffer/providers/test.rb

@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
+# Test provider for mocking LLM responses in tests.
+#
+# No external gems required.
 class Riffer::Providers::Test < Riffer::Providers::Base
+  # Array of recorded method calls for assertions.
+  #
+  # Returns Array of Hash.
   attr_reader :calls
 
+  # Initializes the test provider.
+  #
+  # options:: Hash - optional configuration
+  #
+  # Use +:responses+ to pre-configure responses.
   def initialize(**options)
     @responses = options[:responses] || []
     @current_index = 0
@@ -10,14 +21,19 @@ class Riffer::Providers::Test < Riffer::Providers::Base
     @stubbed_responses = []
   end
 
-  # Stubs the next response from the provider
-  # Can be called multiple times to queue responses
-  # @param content [String] the response content
-  # @param tool_calls [Array<Hash>] optional tool calls to include
-  # @example
+  # Stubs the next response from the provider.
+  #
+  # Can be called multiple times to queue responses.
+  #
+  # content:: String - the response content
+  # tool_calls:: Array of Hash - optional tool calls to include
+  #
+  # Returns void.
+  #
   #   provider.stub_response("Hello")
   #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
-  #   provider.stub_response("Final response")  # Queued for after tool execution
+  #   provider.stub_response("Final response")
+  #
   def stub_response(content, tool_calls: [])
     formatted_tool_calls = tool_calls.map.with_index do |tc, idx|
       {
@@ -30,7 +46,9 @@ class Riffer::Providers::Test < Riffer::Providers::Base
     @stubbed_responses << {role: "assistant", content: content, tool_calls: formatted_tool_calls}
   end
 
-  # Clears all stubbed responses
+  # Clears all stubbed responses.
+  #
+  # Returns void.
   def clear_stubs
     @stubbed_responses = []
   end

data/lib/riffer/providers.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
 
+# Namespace for LLM provider adapters in the Riffer framework.
+#
+# Providers connect Riffer to LLM services:
+# - Riffer::Providers::OpenAI - OpenAI GPT models
+# - Riffer::Providers::AmazonBedrock - AWS Bedrock models
+# - Riffer::Providers::Test - Mock provider for testing
 module Riffer::Providers
 end

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