riffer 0.6.0 → 0.7.0

data/lib/riffer/tool.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Riffer::Tool is the base class for all tools in the Riffer framework.
+#
+# Provides a DSL for defining tool description and parameters.
+#
+# @abstract Subclasses must implement the `call` method.
+#
+# @example
+#   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
+#
+# @see Riffer::Agent
+class Riffer::Tool
+  class << self
+    include Riffer::Helpers::ClassNameConverter
+
+    # Gets or sets the tool description
+    # @param value [String, nil] the description to set, or nil to get
+    # @return [String, 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
+    # @param value [String, nil] the identifier to set, or nil to get
+    # @return [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
+
+    # Defines parameters using the Params DSL
+    # @yield the parameter definition block
+    # @return [Riffer::Tools::Params, 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
+    # @return [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
+  # @param context [Object, nil] optional context passed from the agent
+  # @param kwargs [Hash] the tool arguments
+  # @return [Object] the tool result
+  # @raise [NotImplementedError] if not implemented by subclass
+  def call(context:, **kwargs)
+    raise NotImplementedError, "#{self.class} must implement #call"
+  end
+
+  # Executes the tool with validation (used by Agent)
+  # @param context [Object, nil] context passed from the agent
+  # @param kwargs [Hash] the tool arguments
+  # @return [Object] the tool result
+  # @raise [Riffer::ValidationError] if validation fails
+  def call_with_validation(context:, **kwargs)
+    params_builder = self.class.params
+    validated_args = params_builder ? params_builder.validate(kwargs) : kwargs
+    call(context: context, **validated_args)
+  end
+end

data/lib/riffer/tools/param.rb

@@ -0,0 +1,65 @@
+# 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.
+#
+# @api private
+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
+  # @param name [Symbol] the parameter name
+  # @param type [Class] the expected Ruby type
+  # @param required [Boolean] whether the parameter is required
+  # @param description [String, nil] optional description for the parameter
+  # @param enum [Array, nil] optional list of allowed values
+  # @param default [Object, 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
+  # @param value [Object] the value to validate
+  # @return [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
+  # @return [String] the JSON Schema type
+  def type_name
+    TYPE_MAPPINGS[type] || type.to_s.downcase
+  end
+
+  # Converts this parameter to JSON Schema format
+  # @return [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,112 @@
+# 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.
+#
+# @example
+#   params do
+#     required :city, String, description: "The city name"
+#     optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
+#   end
+#
+# @api private
+class Riffer::Tools::Params
+  attr_reader :parameters
+
+  def initialize
+    @parameters = []
+  end
+
+  # Defines a required parameter
+  # @param name [Symbol] the parameter name
+  # @param type [Class] the expected Ruby type
+  # @param description [String, nil] optional description
+  # @param enum [Array, nil] optional list of allowed values
+  # @return [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
+  # @param name [Symbol] the parameter name
+  # @param type [Class] the expected Ruby type
+  # @param description [String, nil] optional description
+  # @param enum [Array, nil] optional list of allowed values
+  # @param default [Object, nil] default value when not provided
+  # @return [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
+  # @param arguments [Hash] the arguments to validate
+  # @return [Hash] validated arguments with defaults applied
+  # @raise [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
+  # @return [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,4 @@
+# frozen_string_literal: true
+
+module Riffer::Tools
+end

data/lib/riffer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Riffer
-  VERSION = "0.6.0"
+  VERSION = "0.7.0"
 end

data/lib/riffer.rb

@@ -26,6 +26,10 @@ module Riffer
   # @api public
   class ArgumentError < ::ArgumentError; end
 
+  # Validation error for tool parameter validation
+  # @api public
+  class ValidationError < Error; end
+
   # Provides configuration and versioning methods for Riffer
   #
   # @!group Configuration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: riffer
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jake Bottrall
@@ -143,8 +143,8 @@ files:
 - ".release-please-manifest.json"
 - ".ruby-version"
 - ".standard.yml"
+- AGENTS.md
 - CHANGELOG.md
-- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
@@ -175,6 +175,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