riffer 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8f9dc7979fb2338edff2e1c6fb7a6a0281126e95ac8b12bd9e268385dd56263
-  data.tar.gz: a92ec2768bcb0efc3524945f5a69b685ca16dbba40ee852d6c24efdfbde883fd
+  metadata.gz: 9fcc8c58e4de016fd9b5aeab39242904039dc57af45a3f2bc9cae2f92d6ca1d3
+  data.tar.gz: 000f9e8ef52c7b39977eecc13eabbe3fab61186b035fe9f3f68e18ba0056421f
 SHA512:
-  metadata.gz: 62f476d0a84c1ac94520eebf8e11d7773299e0c87a56d9ea473dfbde310ec9a905da9f3446b2a76e5d282e5f52dcf82857397836f3d300d93cab222aceb12065
-  data.tar.gz: 5518dd2966cb8d62553778fe6428d3e339bfe78293dd0eaed4a82b5500f80d2e78ee6f4648c46f62fffd258c293e7894e624ff117a668fab7f5d3a908d246cae
+  metadata.gz: 79e78db4db369e2f37d1783d1ceb1a9ab64a66ad26d7ab644ef66fc075ce16a54ed18092dd892214e0efc8c2ec843ccbe32c9b9a1038331c742ad185daf24c29
+  data.tar.gz: b643bf84aeebb2a68d0dadc6865ff868bafe3fab8e3d4d52772901c619fb9b9d9ca4f2f1ca1be3d693c05de02cb2c003522cce1e1cafc8bac769c716cf70284a

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.1"
+  ".": "0.7.0"
 }

data/AGENTS.md

@@ -0,0 +1,315 @@
+# AI Agent Development Guide
+
+This guide provides comprehensive information for AI coding assistants working with the Riffer codebase.
+
+## Project Overview
+
+Riffer is a Ruby gem framework for building AI-powered applications and agents. It provides a complete toolkit for integrating artificial intelligence capabilities into Ruby projects with a minimal, well-documented core.
+
+Key concepts:
+
+- **Agents** – orchestrate messages, LLM calls, and tool execution (`Riffer::Agent`)
+- **Providers** – adapters that implement text generation and streaming (`Riffer::Providers::*`)
+- **Messages** – typed message objects for system, user, assistant, and tool messages (`Riffer::Messages::*`)
+- **StreamEvents** – structured events for streaming (`Riffer::StreamEvents::*`)
+
+## 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.
+
+Example:
+
+```ruby
+class EchoAgent < Riffer::Agent
+  model 'openai/gpt-5-mini' # provider/model
+  instructions 'You are an assistant that repeats what the user says.'
+end
+
+agent = EchoAgent.new
+puts agent.generate('Hello world')
+```
+
+#### Providers (`lib/riffer/providers/`)
+
+Adapters for LLM APIs. Each provider extends `Riffer::Providers::Base` and implements:
+
+- `perform_generate_text(messages, model:)` – returns `Riffer::Messages::Assistant`
+- `perform_stream_text(messages, model:)` – returns an `Enumerator` yielding stream events
+
+Providers are registered in `Riffer::Providers::Repository::REPO` with identifiers (e.g., `openai`, `amazon_bedrock`).
+
+#### Messages (`lib/riffer/messages/`)
+
+Typed message objects that extend `Riffer::Messages::Base`:
+
+- `System` – system instructions
+- `User` – user input
+- `Assistant` – AI responses
+- `Tool` – tool execution results
+
+The `Converter` module handles hash-to-object conversion.
+
+#### StreamEvents (`lib/riffer/stream_events/`)
+
+Structured events for streaming responses:
+
+- `TextDelta` – incremental text chunks
+- `TextDone` – completion signals
+- `ReasoningDelta` – reasoning process chunks
+- `ReasoningDone` – reasoning completion
+
+### 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/`
+- Zeitwerk for autoloading – file structure must match module/class names
+
+## Code Style & Standards
+
+### Ruby Version
+
+- Minimum Ruby version: 3.2.0
+- Use modern Ruby 3.x features and syntax
+
+### Code Formatting
+
+- Use StandardRB for linting and formatting
+- All Ruby files must include `# frozen_string_literal: true` at the top
+- Follow StandardRB conventions (2-space indentation, double quotes for strings)
+- Custom RuboCop rules are defined in `.standard.yml`
+
+### Testing
+
+- Use Minitest for all tests with the spec DSL
+- Test files go in `test/` directory with `*_test.rb` suffix
+- Tests must pass before committing
+- Use Minitest assertions: `assert_equal`, `assert_instance_of`, `refute_nil`, etc.
+- Prefer using `setup` and `teardown` methods for test setup/cleanup
+
+#### Test Structure
+
+```ruby
+# frozen_string_literal: true
+
+require "test_helper"
+
+describe Riffer::Feature do
+  describe "#method_name" do
+    before do
+      # setup code
+    end
+
+    it "does something expected" do
+      result = Riffer::Feature.method_name(args)
+      assert_equal expected, result
+    end
+
+    it "handles edge case" do
+      result = Riffer::Feature.method_name(edge_case_args)
+      assert_equal edge_case_expected, result
+    end
+  end
+end
+```
+
+#### Test Coverage
+
+- Test public APIs thoroughly
+- Test edge cases and error conditions
+- Mock external dependencies
+- Keep tests fast and isolated
+- Stick to the single assertion rule where possible
+
+### Documentation
+
+- Use YARD-style comments for public APIs
+- Document parameters with `@param`
+- Document return values with `@return`
+- Document raised errors with `@raise`
+
+### Comments
+
+- Only add comments when the code is ambiguous or not semantically obvious
+- Avoid stating what the code does if it's clear from reading the code itself
+- Use comments to explain **why** something is done, not **what** is being done
+- Comments should add value beyond what the code already expresses
+
+### Error Handling
+
+- Define custom errors as subclasses of `Riffer::Error`
+- Use descriptive error messages
+- Document errors that can be raised
+
+## Project Structure
+
+```
+lib/
+  riffer.rb              # Main entry point, uses Zeitwerk for autoloading
+  riffer/
+    version.rb           # VERSION constant
+    config.rb            # Configuration class
+    core.rb              # Core functionality
+    agent.rb             # Agent class
+    messages.rb          # Messages namespace/module
+    providers.rb         # Providers namespace/module
+    stream_events.rb     # Stream events namespace/module
+    helpers/
+      class_name_converter.rb  # Class name conversion utilities
+      dependencies.rb          # Dependency management
+      validations.rb           # Validation helpers
+    messages/
+      base.rb            # Base message class
+      assistant.rb       # Assistant message
+      converter.rb       # Message converter
+      system.rb          # System message
+      user.rb            # User message
+      tool.rb            # Tool message
+    providers/
+      base.rb            # Base provider class
+      open_ai.rb         # OpenAI provider
+      amazon_bedrock.rb  # Amazon Bedrock provider
+      repository.rb      # Provider registry
+      test.rb            # Test provider
+    stream_events/
+      base.rb            # Base stream event
+      text_delta.rb      # Text delta event
+      text_done.rb       # Text done event
+      reasoning_delta.rb # Reasoning delta event
+      reasoning_done.rb  # Reasoning done event
+test/
+  test_helper.rb         # Minitest configuration with VCR
+  riffer_test.rb         # Main module tests
+  riffer/
+    [feature]_test.rb    # Feature tests mirror lib/riffer/ structure
+```
+
+## Development Workflow
+
+### Autoloading with Zeitwerk
+
+- The project uses Zeitwerk for autoloading
+- File structure must match module/class names
+- No explicit `require` statements needed for lib files
+- Special inflections are configured in `lib/riffer.rb` (e.g., `open_ai.rb` → `OpenAI`)
+
+### Adding New Features
+
+1. Create feature files under `lib/riffer/` following Zeitwerk conventions
+2. File names should be snake_case, class names should be PascalCase
+3. Create corresponding tests in `test/riffer/` mirroring the lib structure
+4. Run tests: `rake test`
+5. Check code style: `rake standard`
+
+### 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
+6. Create corresponding test file in `test/riffer/providers/`
+
+### Dependencies
+
+- Add runtime dependencies in `riffer.gemspec` using `spec.add_dependency`
+- Add development dependencies in `Gemfile`
+- Document significant dependencies in README
+
+### Version Management
+
+- Update version in `lib/riffer/version.rb`
+- Follow Semantic Versioning (MAJOR.MINOR.PATCH)
+- Update CHANGELOG.md with changes
+
+## AI/Agent Development Context
+
+Since Riffer is an AI framework, when working on AI-related features:
+
+- Consider integration with common AI APIs (OpenAI, Anthropic, Amazon Bedrock, etc.)
+- Design for extensibility and plugin architecture
+- Handle API rate limiting and retries
+- Implement proper error handling for external services
+- Consider streaming responses where applicable
+- Think about token counting and cost management
+- Support async/concurrent operations where beneficial
+
+## Commands Reference
+
+```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
+
+# Install gem locally
+bundle exec rake install
+
+# Release new version (maintainers only)
+bundle exec rake release
+```
+
+## Code Patterns
+
+### Module Structure
+
+```ruby
+# frozen_string_literal: true
+
+module Riffer::Feature
+  class MyClass
+    # Implementation
+  end
+end
+```
+
+### Configuration Example
+
+```ruby
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+```
+
+### Streaming Example
+
+```ruby
+agent = EchoAgent.new
+agent.stream('Tell me a story').each do |event|
+  print event.content
+end
+```
+
+## Important Notes
+
+- Always run `rake` (runs both test and standard) before committing
+- Keep the README updated with new features
+- Follow the Code of Conduct in all interactions
+- This gem is MIT licensed – keep license headers consistent

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.7.0](https://github.com/janeapp/riffer/compare/riffer/v0.6.1...riffer/v0.7.0) (2026-01-21)
+
+
+### Features
+
+* tool calling support ([#82](https://github.com/janeapp/riffer/issues/82)) ([0b2676a](https://github.com/janeapp/riffer/commit/0b2676a77e93b3fd55041e66a5c8c0ab6762e3d2))
+
 ## [0.6.1](https://github.com/janeapp/riffer/compare/riffer/v0.6.0...riffer/v0.6.1) (2026-01-16)
 
 

data/README.md

@@ -11,13 +11,15 @@ Riffer is a comprehensive Ruby framework designed to simplify the development of
 Key concepts:
 
 - **Agents** – orchestrate messages, LLM calls, and tool execution (`Riffer::Agent`).
+- **Tools** – define callable functions that agents can use to interact with external systems (`Riffer::Tool`).
 - **Providers** – adapters that implement text generation and streaming (`Riffer::Providers::*`).
 - **Messages** – typed message objects for system, user, assistant, and tool messages (`Riffer::Messages::*`).
 
 ## Features
 
 - Minimal, well-documented core for building AI agents
-- Provider abstraction (OpenAI) for pluggable providers
+- Tool calling support with parameter validation
+- Provider abstraction (OpenAI, Amazon Bedrock) for pluggable providers
 - Streaming support and structured stream events
 - Message converters and helpers for robust message handling
 
@@ -76,6 +78,85 @@ agent.stream('Tell me a story').each do |event|
 end
 ```
 
+### Provider & Model Options
+
+Agents support two optional configuration methods for passing options through to the underlying provider:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a helpful assistant.'
+
+  # Options passed directly to the provider client (e.g., OpenAI::Client)
+  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
+
+  # Options passed to the model invocation (e.g., reasoning, temperature)
+  model_options reasoning: 'medium'
+end
+```
+
+- `provider_options` - Hash of options passed to the provider client during instantiation
+- `model_options` - Hash of options passed to `generate_text` / `stream_text` calls
+
+### Tools
+
+Tools allow agents to interact with external systems. Define a tool by extending `Riffer::Tool`:
+
+```ruby
+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", enum: ["celsius", "fahrenheit"]
+  end
+
+  def call(context:, city:, units: nil)
+    weather = WeatherService.lookup(city, units: units || "celsius")
+    "The weather in #{city} is #{weather.temperature} #{units}."
+  end
+end
+```
+
+Register tools with an agent using `uses_tools`:
+
+```ruby
+class WeatherAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a helpful weather assistant.'
+
+  uses_tools [WeatherLookupTool]
+end
+
+agent = WeatherAgent.new
+puts agent.generate("What's the weather in Toronto?")
+```
+
+Tools can also be dynamically resolved at runtime. The lambda receives `tool_context` when it accepts a parameter, enabling conditional tool resolution based on the current user or request:
+
+```ruby
+class DynamicAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+
+  uses_tools ->(context) {
+    tools = [WeatherLookupTool]
+    tools << AdminTool if context&.dig(:current_user)&.admin?
+    tools
+  }
+end
+
+agent = DynamicAgent.new
+agent.generate("Do admin things", tool_context: { current_user: current_user })
+```
+
+Pass context to tools using `tool_context`:
+
+```ruby
+agent.generate("Look up my city", tool_context: { user_id: current_user.id })
+```
+
+The `context` keyword argument is passed to every tool's `call` method, allowing tools to access shared state like user information, database connections, or API clients.
+
 ## Development
 
 After checking out the repo, run:

data/lib/riffer/agent.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+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.
@@ -40,10 +42,28 @@ class Riffer::Agent
       @instructions = instructions_text
     end
 
-    def reasoning(level = nil)
-      return @reasoning if level.nil?
-      validate_is_string!(level, "reasoning")
-      @reasoning = level
+    # 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
+    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
+    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
+    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
@@ -71,7 +91,6 @@ class Riffer::Agent
     @messages = []
     @model_string = self.class.model
     @instructions_text = self.class.instructions
-    @reasoning = self.class.reasoning
 
     provider_name, model_name = @model_string.split("/", 2)
 
@@ -83,8 +102,11 @@ class Riffer::Agent
 
   # 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]
-  def generate(prompt_or_messages)
+  def generate(prompt_or_messages, tool_context: nil)
+    @tool_context = tool_context
+    @resolved_tools = nil
     initialize_messages(prompt_or_messages)
 
     loop do
@@ -101,26 +123,49 @@ class Riffer::Agent
 
   # 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
-  def stream(prompt_or_messages)
+  def stream(prompt_or_messages, tool_context: nil)
+    @tool_context = tool_context
+    @resolved_tools = nil
     initialize_messages(prompt_or_messages)
 
     Enumerator.new do |yielder|
-      accumulated_content = ""
+      loop do
+        accumulated_content = ""
+        accumulated_tool_calls = []
+        current_tool_call = nil
+
+        call_llm_stream.each do |event|
+          yielder << event
+
+          case event
+          when Riffer::StreamEvents::TextDelta
+            accumulated_content += event.content
+          when Riffer::StreamEvents::TextDone
+            accumulated_content = event.content
+          when Riffer::StreamEvents::ToolCallDelta
+            current_tool_call ||= {item_id: event.item_id, name: event.name, arguments: ""}
+            current_tool_call[:arguments] += event.arguments_delta
+            current_tool_call[:name] ||= event.name
+          when Riffer::StreamEvents::ToolCallDone
+            accumulated_tool_calls << {
+              id: event.item_id,
+              call_id: event.call_id,
+              name: event.name,
+              arguments: event.arguments
+            }
+            current_tool_call = nil
+          end
+        end
 
-      call_llm_stream.each do |event|
-        yielder << event
+        response = Riffer::Messages::Assistant.new(accumulated_content, tool_calls: accumulated_tool_calls)
+        @messages << response
 
-        case event
-        when Riffer::StreamEvents::TextDelta
-          accumulated_content += event.content
-        when Riffer::StreamEvents::TextDone
-          accumulated_content = event.content
-        end
-      end
+        break unless has_tool_calls?(response)
 
-      response = Riffer::Messages::Assistant.new(accumulated_content)
-      @messages << response
+        execute_tool_calls(response)
+      end
     end
   end
 
@@ -140,18 +185,28 @@ class Riffer::Agent
   end
 
   def call_llm
-    provider_instance.generate_text(messages: @messages, model: @model_name, reasoning: @reasoning)
+    provider_instance.generate_text(
+      messages: @messages,
+      model: @model_name,
+      tools: resolved_tools,
+      **self.class.model_options
+    )
   end
 
   def call_llm_stream
-    provider_instance.stream_text(messages: @messages, model: @model_name, reasoning: @reasoning)
+    provider_instance.stream_text(
+      messages: @messages,
+      model: @model_name,
+      tools: resolved_tools,
+      **self.class.model_options
+    )
   end
 
   def provider_instance
     @provider_instance ||= begin
       provider_class = Riffer::Providers::Repository.find(@provider_name)
       raise Riffer::ArgumentError, "Provider not found: #{@provider_name}" unless provider_class
-      provider_class.new
+      provider_class.new(**self.class.provider_options)
     end
   end
 
@@ -161,17 +216,71 @@ class Riffer::Agent
 
   def execute_tool_calls(response)
     response.tool_calls.each do |tool_call|
-      tool_result = execute_tool_call(tool_call)
+      result = execute_tool_call(tool_call)
       @messages << Riffer::Messages::Tool.new(
-        tool_result,
+        result[:content],
         tool_call_id: tool_call[:id],
-        name: tool_call[:name]
+        name: tool_call[:name],
+        error: result[:error],
+        error_type: result[:error_type]
       )
     end
   end
 
   def execute_tool_call(tool_call)
-    "Tool execution not implemented yet"
+    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
+      }
+    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}
+    rescue Riffer::ValidationError => e
+      {
+        content: "Validation error: #{e.message}",
+        error: e.message,
+        error_type: :validation_error
+      }
+    rescue => e
+      {
+        content: "Error executing tool: #{e.message}",
+        error: e.message,
+        error_type: :execution_error
+      }
+    end
+  end
+
+  def resolved_tools
+    @resolved_tools ||= begin
+      config = self.class.uses_tools
+      return [] if config.nil?
+
+      if config.is_a?(Proc)
+        (config.arity == 0) ? config.call : config.call(@tool_context)
+      else
+        config
+      end
+    end
+  end
+
+  def find_tool_class(name)
+    resolved_tools.find { |tool_class| tool_class.name == name }
+  end
+
+  def parse_tool_arguments(arguments)
+    return {} if arguments.nil? || arguments.empty?
+
+    args = arguments.is_a?(String) ? JSON.parse(arguments) : arguments
+    args.transform_keys(&:to_sym)
   end
 
   def extract_final_response