riffer 0.6.1 → 0.8.0

data/lib/riffer/tool.rb

@@ -0,0 +1,120 @@
+# 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.
+#
+# See Riffer::Agent.
+#
+#   class WeatherLookupTool < Riffer::Tool
+#     description "Provides current weather information for a specified city."
+#
+#     params do
+#       required :city, String, description: "The city to look up"
+#       optional :units, String, default: "celsius"
+#     end
+#
+#     def call(context:, city:, units: nil)
+#       # Implementation
+#     end
+#   end
+#
+class Riffer::Tool
+  DEFAULT_TIMEOUT = 10
+
+  class << self
+    include Riffer::Helpers::ClassNameConverter
+
+    # 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.
+    #
+    # 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
+    end
+
+    # Alias for identifier - used by providers
+    alias_method :name, :identifier
+
+    # 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.
+    #
+    # Returns Hash - the JSON Schema.
+    def parameters_schema
+      @params_builder&.to_json_schema || empty_schema
+    end
+
+    private
+
+    def empty_schema
+      {type: "object", properties: {}, required: [], additionalProperties: false}
+    end
+  end
+
+  # 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 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
+
+    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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Riffer::Tools::Param represents a single parameter definition for a tool.
+#
+# Handles type validation and JSON Schema generation for individual parameters.
+class Riffer::Tools::Param
+  # Maps Ruby types to JSON Schema type strings
+  TYPE_MAPPINGS = {
+    String => "string",
+    Integer => "integer",
+    Float => "number",
+    TrueClass => "boolean",
+    FalseClass => "boolean",
+    Array => "array",
+    Hash => "object"
+  }.freeze
+
+  attr_reader :name, :type, :required, :description, :enum, :default
+
+  # 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
+    @required = required
+    @description = description
+    @enum = enum
+    @default = default
+  end
+
+  # 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
+
+    if type == TrueClass || type == FalseClass
+      value == true || value == false
+    else
+      value.is_a?(type)
+    end
+  end
+
+  # 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.
+  #
+  # Returns Hash - the JSON Schema representation.
+  def to_json_schema
+    schema = {type: type_name}
+    schema[:description] = description if description
+    schema[:enum] = enum if enum
+    schema
+  end
+end

data/lib/riffer/tools/params.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Riffer::Tools::Params provides a DSL for defining tool parameters.
+#
+# Used within a Tool's +params+ block to define required and optional parameters.
+#
+#   params do
+#     required :city, String, description: "The city name"
+#     optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
+#   end
+#
+class Riffer::Tools::Params
+  attr_reader :parameters
+
+  def initialize
+    @parameters = []
+  end
+
+  # 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,
+      type: type,
+      required: true,
+      description: description,
+      enum: enum
+    )
+  end
+
+  # 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,
+      type: type,
+      required: false,
+      description: description,
+      enum: enum,
+      default: default
+    )
+  end
+
+  # 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 = []
+
+    @parameters.each do |param|
+      value = arguments[param.name]
+
+      if value.nil? && param.required
+        errors << "#{param.name} is required"
+        next
+      end
+
+      if value.nil?
+        validated[param.name] = param.default
+        next
+      end
+
+      unless param.valid_type?(value)
+        errors << "#{param.name} must be a #{param.type_name}"
+        next
+      end
+
+      if param.enum && !param.enum.include?(value)
+        errors << "#{param.name} must be one of: #{param.enum.join(", ")}"
+        next
+      end
+
+      validated[param.name] = value
+    end
+
+    raise Riffer::ValidationError, errors.join("; ") if errors.any?
+
+    validated
+  end
+
+  # Converts all parameters to JSON Schema format.
+  #
+  # Returns Hash - the JSON Schema representation.
+  def to_json_schema
+    properties = {}
+    required_params = []
+
+    @parameters.each do |param|
+      properties[param.name.to_s] = param.to_json_schema
+      required_params << param.name.to_s if param.required
+    end
+
+    {
+      type: "object",
+      properties: properties,
+      required: required_params,
+      additionalProperties: false
+    }
+  end
+end

data/lib/riffer/tools.rb

@@ -0,0 +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.6.1"
+  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,33 +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
 
-  # Provides configuration and versioning methods for Riffer
-  #
-  # @!group Configuration
+  # Raised when tool parameter validation fails.
+  class ValidationError < Error; end
+
+  # 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.6.1
+  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,16 +153,34 @@ 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"
 - ".standard.yml"
+- AGENTS.md
 - CHANGELOG.md
-- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - 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
@@ -175,6 +208,12 @@ files:
 - lib/riffer/stream_events/reasoning_done.rb
 - lib/riffer/stream_events/text_delta.rb
 - lib/riffer/stream_events/text_done.rb
+- lib/riffer/stream_events/tool_call_delta.rb
+- lib/riffer/stream_events/tool_call_done.rb
+- lib/riffer/tool.rb
+- lib/riffer/tools.rb
+- lib/riffer/tools/param.rb
+- lib/riffer/tools/params.rb
 - lib/riffer/version.rb
 - sig/riffer.rbs
 homepage: https://riffer.ai

data/CLAUDE.md

@@ -1,73 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Riffer is a Ruby gem framework for building AI-powered applications and agents. It uses Zeitwerk for autoloading.
-
-## Commands
-
-```bash
-# Install dependencies
-bin/setup
-
-# Run tests
-bundle exec rake test
-
-# Run a single test file
-bundle exec ruby -Ilib:test test/riffer/agent_test.rb
-
-# Run a specific test by name
-bundle exec ruby -Ilib:test test/riffer/agent_test.rb --name "test_something"
-
-# Check code style
-bundle exec rake standard
-
-# Auto-fix style issues
-bundle exec rake standard:fix
-
-# Run both tests and linting (default task)
-bundle exec rake
-
-# Interactive console
-bin/console
-
-# Generate documentation
-bundle exec rake docs
-```
-
-## Architecture
-
-### Core Components
-
-- **Agent** (`lib/riffer/agent.rb`): Base class for AI agents. Subclass and use DSL methods `model` and `instructions` to configure. Orchestrates message flow, LLM calls, and tool execution via a generate/stream loop.
-
-- **Providers** (`lib/riffer/providers/`): Adapters for LLM APIs. Each provider extends `Riffer::Providers::Base` and implements `perform_generate_text` and `perform_stream_text`. Registered in `Repository` with identifier (e.g., `openai`).
-
-- **Messages** (`lib/riffer/messages/`): Typed message objects (`System`, `User`, `Assistant`, `Tool`). All extend `Base`. The `Converter` module handles hash-to-object conversion.
-
-- **StreamEvents** (`lib/riffer/stream_events/`): Structured events for streaming (`TextDelta`, `TextDone`).
-
-### Key Patterns
-
-- Model strings use `provider/model` format (e.g., `openai/gpt-4`)
-- Configuration via `Riffer.configure { |c| c.openai.api_key = "..." }`
-- Providers use `depends_on` helper for runtime dependency checking
-- Tests use VCR cassettes in `test/fixtures/vcr_cassettes/`
-
-### Adding a New Provider
-
-1. Create `lib/riffer/providers/your_provider.rb` extending `Riffer::Providers::Base`
-2. Implement `perform_generate_text(messages, model:)` returning `Riffer::Messages::Assistant`
-3. Implement `perform_stream_text(messages, model:)` returning an `Enumerator` yielding stream events
-4. Register in `Riffer::Providers::Repository::REPO`
-5. Add provider config to `Riffer::Config` if needed
-
-## Code Style
-
-- Ruby 3.2+ required
-- All files must have `# frozen_string_literal: true`
-- StandardRB for formatting (double quotes, 2-space indent)
-- Minitest with spec DSL for tests
-- YARD-style documentation for public APIs