riffer 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28ba9aa31a3f79392de37c769531f765a1b32aff4272fd727efeef8eb1435996
-  data.tar.gz: 97328dee069286c025a7478414816b032682e34ce3e1649d1f96634f2fbc0b43
+  metadata.gz: b8dc7ed9ce34f57a7b72ebbe859953e93fd147e90930943e92279d77d94cba2f
+  data.tar.gz: b8b1784bba856ad9207b1582bd75885c18f13b9ff38c6049f1278912417d02fa
 SHA512:
-  metadata.gz: 961a2559a012e481273fe92ac2ae81b4cdb827a00433c74b62c6a3041a78b64b4b374a41ea380ff1874ea11e7c883bddda391276e32bef043134c6fdbefc245e
-  data.tar.gz: dd824a10a31dc4eac9732dac2d864698ec6118f6753001b92a8fadddf8d695e8c28240adf250341d16c5c3f93c8523bd22d81e9f5a0f7f2a9889ef020673e9da
+  metadata.gz: 849e232aa92045fcacbe0ac98433297a1c769c1ff471c91bab4507b72f4a81a59b6d0fd2de1cb354615ac5910de27466ef9f96c3f72cf2bc8e5fa668f510f923
+  data.tar.gz: bfefcc497f720b13cd3032d4a03acff0c26e8fd1b83cf19b15da925aee5c375afa3f3577fb1086c82db857a82d65af60c148110be5c2730e2695e096f10d8906

data/.standard.yml

@@ -1,2 +1 @@
-extend_config:
-  - .rubocop_rspec.yml
+# Standard Ruby configuration

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0](https://github.com/bottrall/riffer/compare/v0.1.0...v0.2.0) (2025-12-28)
+
+
+### Features
+
+* add release and publish workflows ([#35](https://github.com/bottrall/riffer/issues/35)) ([3eb0389](https://github.com/bottrall/riffer/commit/3eb03897d0e96c01ef1857c04b2bafa53e37dde0))
+
 ## [0.1.0] - 2024-12-20
 
 ### Added

data/Rakefile

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require "minitest/test_task"
 
-RSpec::Core::RakeTask.new(:spec)
+Minitest::TestTask.create
 
 require "standard/rake"
 
-task default: %i[spec standard]
+task default: %i[test standard]

data/lib/riffer/agent.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Riffer::Agent is the base class for all agents in the Riffer framework.
+#
+# Provides orchestration for LLM calls, tool use, and message management.
+#
+# @abstract
+# @see Riffer::Messages
+# @see Riffer::Providers
+class Riffer::Agent
+  include Riffer::Messages::Converter
+
+  class << self
+    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
+    def identifier(value = nil)
+      return @identifier 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
+    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
+    def instructions(instructions_text = nil)
+      return @instructions if instructions_text.nil?
+      validate_is_string!(instructions_text, "instructions")
+      @instructions = instructions_text
+    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
+    def find(identifier)
+      subclasses.find { |agent_class| agent_class.identifier == identifier.to_s }
+    end
+
+    # Returns all agent subclasses
+    # @return [Array<Class>] all agent subclasses
+    def all
+      subclasses
+    end
+  end
+
+  # The message history for the agent
+  # @return [Array<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]
+  def initialize
+    @messages = []
+    @model_string = self.class.model
+    @instructions_text = self.class.instructions
+
+    provider_name, model_name = @model_string.split("/", 2)
+
+    raise Riffer::ArgumentError, "Invalid model string: #{@model_string}" unless [provider_name, model_name].all? { |part| part.is_a?(String) && !part.strip.empty? }
+
+    @provider_name = provider_name
+    @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)
+    initialize_messages(prompt_or_messages)
+
+    loop do
+      response = call_llm
+      @messages << response
+
+      break unless has_tool_calls?(response)
+
+      execute_tool_calls(response)
+    end
+
+    extract_final_response
+  end
+
+  private
+
+  def initialize_messages(prompt_or_messages)
+    @messages = []
+    @messages << Riffer::Messages::System.new(@instructions_text) if @instructions_text
+
+    if prompt_or_messages.is_a?(Array)
+      prompt_or_messages.each do |item|
+        @messages << convert_to_message_object(item)
+      end
+    else
+      @messages << Riffer::Messages::User.new(prompt_or_messages)
+    end
+  end
+
+  def call_llm
+    provider_instance.generate_text(messages: @messages, model: @model_name)
+  end
+
+  def provider_instance
+    @provider_instance ||= begin
+      provider_class = Riffer::Providers::Base.find(@provider_name)
+      raise Riffer::ArgumentError, "Provider not found: #{@provider_name}" unless provider_class
+      provider_class.new
+    end
+  end
+
+  def has_tool_calls?(response)
+    response.is_a?(Riffer::Messages::Assistant) && !response.tool_calls.empty?
+  end
+
+  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,
+        tool_call_id: tool_call[:id],
+        name: tool_call[:name]
+      )
+    end
+  end
+
+  def execute_tool_call(tool_call)
+    "Tool execution not implemented yet"
+  end
+
+  def extract_final_response
+    last_assistant_message = @messages.reverse.find { |msg| msg.is_a?(Riffer::Messages::Assistant) }
+    last_assistant_message&.content || ""
+  end
+end

data/lib/riffer/config.rb

@@ -1,11 +1,19 @@
 # frozen_string_literal: true
 
-module Riffer
-  class Config
-    attr_reader :openai
+# 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-..."
+class Riffer::Config
+  # OpenAI configuration
+  # @return [Struct]
+  attr_reader :openai
 
-    def initialize
-      @openai = Struct.new(:api_key).new
-    end
+  # Initializes the configuration
+  # @return [void]
+  def initialize
+    @openai = Struct.new(:api_key).new
   end
 end

data/lib/riffer/core.rb

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

data/lib/riffer/{dependency_helper.rb → helpers/dependencies.rb}

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-module Riffer::DependencyHelper
+module Riffer::Helpers::Dependencies
   class LoadError < ::LoadError; end
-
   class VersionError < ScriptError; end
 
   def depends_on(gem_name, req: true)

data/lib/riffer/helpers/validations.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Riffer::Helpers::Validations
+  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?
+
+    true
+  end
+end

data/lib/riffer/messages/assistant.rb

@@ -1,22 +1,20 @@
 # frozen_string_literal: true
 
-module Riffer::Messages
-  class Assistant < Base
-    attr_reader :tool_calls
+class Riffer::Messages::Assistant < Riffer::Messages::Base
+  attr_reader :tool_calls
 
-    def initialize(content, tool_calls: [])
-      super(content)
-      @tool_calls = tool_calls
-    end
+  def initialize(content, tool_calls: [])
+    super(content)
+    @tool_calls = tool_calls
+  end
 
-    def role
-      "assistant"
-    end
+  def role
+    "assistant"
+  end
 
-    def to_h
-      hash = {role: role, content: content}
-      hash[:tool_calls] = tool_calls unless tool_calls.empty?
-      hash
-    end
+  def to_h
+    hash = {role: role, content: content}
+    hash[:tool_calls] = tool_calls unless tool_calls.empty?
+    hash
   end
 end

data/lib/riffer/messages/base.rb

@@ -1,19 +1,17 @@
 # frozen_string_literal: true
 
-module Riffer::Messages
-  class Base
-    attr_reader :content
+class Riffer::Messages::Base
+  attr_reader :content
 
-    def initialize(content)
-      @content = content
-    end
+  def initialize(content)
+    @content = content
+  end
 
-    def to_h
-      {role: role, content: content}
-    end
+  def to_h
+    {role: role, content: content}
+  end
 
-    def role
-      raise NotImplementedError, "Subclasses must implement #role"
-    end
+  def role
+    raise NotImplementedError, "Subclasses must implement #role"
   end
 end

data/lib/riffer/messages/converter.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Riffer::Messages::Converter
+  def convert_to_message_object(msg)
+    return msg if msg.is_a?(Riffer::Messages::Base)
+
+    unless msg.is_a?(Hash)
+      raise Riffer::ArgumentError, "Message must be a Hash or Message object, got #{msg.class}"
+    end
+
+    convert_hash_to_message(msg)
+  end
+
+  private
+
+  def convert_hash_to_message(hash)
+    role = hash[:role] || hash["role"]
+    content = hash[:content] || hash["content"]
+
+    if role.nil? || role.empty?
+      raise Riffer::ArgumentError, "Message hash must include a 'role' key"
+    end
+
+    case role
+    when "user"
+      Riffer::Messages::User.new(content)
+    when "assistant"
+      tool_calls = hash[:tool_calls] || hash["tool_calls"] || []
+      Riffer::Messages::Assistant.new(content, tool_calls: tool_calls)
+    when "system"
+      Riffer::Messages::System.new(content)
+    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)
+    else
+      raise Riffer::ArgumentError, "Unknown message role: #{role}"
+    end
+  end
+end

data/lib/riffer/messages/system.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-module Riffer::Messages
-  class System < Base
-    def role
-      "system"
-    end
+class Riffer::Messages::System < Riffer::Messages::Base
+  def role
+    "system"
   end
 end

data/lib/riffer/messages/tool.rb

@@ -1,21 +1,19 @@
 # frozen_string_literal: true
 
-module Riffer::Messages
-  class Tool < Base
-    attr_reader :tool_call_id, :name
+class Riffer::Messages::Tool < Riffer::Messages::Base
+  attr_reader :tool_call_id, :name
 
-    def initialize(content, tool_call_id:, name:)
-      super(content)
-      @tool_call_id = tool_call_id
-      @name = name
-    end
+  def initialize(content, tool_call_id:, name:)
+    super(content)
+    @tool_call_id = tool_call_id
+    @name = name
+  end
 
-    def role
-      "tool"
-    end
+  def role
+    "tool"
+  end
 
-    def to_h
-      {role: role, content: content, tool_call_id: tool_call_id, name: name}
-    end
+  def to_h
+    {role: role, content: content, tool_call_id: tool_call_id, name: name}
   end
 end

data/lib/riffer/messages/user.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-module Riffer::Messages
-  class User < Base
-    def role
-      "user"
-    end
+class Riffer::Messages::User < Riffer::Messages::Base
+  def role
+    "user"
   end
 end

data/lib/riffer/providers/base.rb

@@ -1,107 +1,95 @@
 # frozen_string_literal: true
 
-module Riffer::Providers
-  class Base
-    include Riffer::DependencyHelper
+class Riffer::Providers::Base
+  include Riffer::Helpers::Dependencies
+  include Riffer::Messages::Converter
 
-    class << self
-      def identifier(value = nil)
-        return @identifier if value.nil?
+  class << self
+    def identifier(value = nil)
+      return @identifier if value.nil?
 
-        @identifier = value
-      end
-
-      def find_provider(identifier)
-        ensure_providers_loaded
-
-        provider = subclasses.find { |provider_class| provider_class.identifier == identifier }
-
-        raise InvalidInputError, "Provider not found for identifier: #{identifier}" if provider.nil?
+      @identifier = value
+    end
 
-        provider
-      end
+    # 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
+    def find(identifier)
+      ensure_providers_loaded
+      subclasses.find { |provider_class| provider_class.identifier == identifier }
+    end
 
-      private
+    private
 
-      def ensure_providers_loaded
-        return if @providers_loaded
+    def ensure_providers_loaded
+      return if @providers_loaded
 
-        Zeitwerk::Loader.eager_load_namespace(Riffer::Providers)
+      Zeitwerk::Loader.eager_load_namespace(Riffer::Providers)
 
-        @providers_loaded = true
-      end
+      @providers_loaded = true
     end
+  end
 
-    def generate_text(prompt: nil, system: nil, messages: nil, model: nil)
-      validate_input!(prompt: prompt, system: system, messages: messages)
-      normalized_messages = normalize_messages(prompt: prompt, system: system, messages: messages)
-      perform_generate_text(normalized_messages, model: model)
-    end
+  # 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
+  # @return [Riffer::Messages::Assistant] the generated assistant message
+  def generate_text(prompt: nil, system: nil, messages: nil, model: nil)
+    validate_input!(prompt: prompt, system: system, messages: messages)
+    normalized_messages = normalize_messages(prompt: prompt, system: system, messages: messages)
+    validate_normalized_messages!(normalized_messages)
+    perform_generate_text(normalized_messages, model: model)
+  end
 
-    def stream_text(prompt: nil, system: nil, messages: nil, model: nil)
-      validate_input!(prompt: prompt, system: system, messages: messages)
-      normalized_messages = normalize_messages(prompt: prompt, system: system, messages: messages)
-      perform_stream_text(normalized_messages, model: model)
-    end
+  # 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
+  # @return [Enumerator] an enumerator yielding stream events or chunks (provider-specific)
+  def stream_text(prompt: nil, system: nil, messages: nil, model: nil)
+    validate_input!(prompt: prompt, system: system, messages: messages)
+    normalized_messages = normalize_messages(prompt: prompt, system: system, messages: messages)
+    validate_normalized_messages!(normalized_messages)
+    perform_stream_text(normalized_messages, model: model)
+  end
 
-    private
+  private
 
-    def perform_generate_text(messages, model: nil)
-      raise NotImplementedError, "Subclasses must implement #perform_generate_text"
-    end
+  def perform_generate_text(messages, model: nil)
+    raise NotImplementedError, "Subclasses must implement #perform_generate_text"
+  end
 
-    def perform_stream_text(messages, model: nil)
-      raise NotImplementedError, "Subclasses must implement #perform_stream_text"
-    end
+  def perform_stream_text(messages, model: nil)
+    raise NotImplementedError, "Subclasses must implement #perform_stream_text"
+  end
 
-    def validate_input!(prompt:, system:, messages:)
-      if messages.nil?
-        raise InvalidInputError, "prompt is required when messages is not provided" if prompt.nil?
-      else
-        raise InvalidInputError, "cannot provide both prompt and messages" unless prompt.nil?
-        raise InvalidInputError, "cannot provide both system and messages" unless system.nil?
-        raise InvalidInputError, "messages must include at least one user message" unless has_user_message?(messages)
-      end
+  def validate_input!(prompt:, system:, messages:)
+    if messages.nil?
+      raise Riffer::ArgumentError, "prompt is required when messages is not provided" if prompt.nil?
+    else
+      raise Riffer::ArgumentError, "cannot provide both prompt and messages" unless prompt.nil?
+      raise Riffer::ArgumentError, "cannot provide both system and messages" unless system.nil?
     end
+  end
 
-    def normalize_messages(prompt:, system:, messages:)
-      if messages
-        return messages.map { |msg| convert_to_message_object(msg) }
-      end
-
-      result = []
-      result << Riffer::Messages::System.new(system) if system
-      result << Riffer::Messages::User.new(prompt)
-      result
+  def normalize_messages(prompt:, system:, messages:)
+    if messages
+      return messages.map { |msg| convert_to_message_object(msg) }
     end
 
-    def convert_to_message_object(msg)
-      if msg.is_a?(Riffer::Messages::Base)
-        return msg
-      end
-
-      unless msg.is_a?(Hash)
-        raise InvalidInputError, "Message must be a Hash or Message object, got #{msg.class}"
-      end
-
-      case msg[:role]
-      when "user"
-        Riffer::Messages::User.new(msg[:content])
-      when "assistant"
-        Riffer::Messages::Assistant.new(msg[:content], tool_calls: msg[:tool_calls] || [])
-      when "system"
-        Riffer::Messages::System.new(msg[:content])
-      when "tool"
-        Riffer::Messages::Tool.new(msg[:content], tool_call_id: msg[:tool_call_id], name: msg[:name])
-      else
-        raise InvalidInputError, "Unknown message role: #{msg[:role]}"
-      end
-    end
+    result = []
+    result << Riffer::Messages::System.new(system) if system
+    result << Riffer::Messages::User.new(prompt)
+    result
+  end
 
-    def has_user_message?(messages)
-      messages.any? do |msg|
-        msg.is_a?(Riffer::Messages::User) || (msg.is_a?(Hash) && msg[:role] == "user")
-      end
-    end
+  def validate_normalized_messages!(messages)
+    has_user = messages.any? { |msg| msg.is_a?(Riffer::Messages::User) }
+    raise Riffer::ArgumentError, "messages must include at least one user message" unless has_user
   end
 end