riffer 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fcc8c58e4de016fd9b5aeab39242904039dc57af45a3f2bc9cae2f92d6ca1d3
-  data.tar.gz: 000f9e8ef52c7b39977eecc13eabbe3fab61186b035fe9f3f68e18ba0056421f
+  metadata.gz: 7aa794200e1e9eef7fff84170952900baa69535798e7bed5b67990a886edc587
+  data.tar.gz: 0cad248bb54b1814b184f4727900f22955cc62abf0b76789ef4099824d05d4c3
 SHA512:
-  metadata.gz: 79e78db4db369e2f37d1783d1ceb1a9ab64a66ad26d7ab644ef66fc075ce16a54ed18092dd892214e0efc8c2ec843ccbe32c9b9a1038331c742ad185daf24c29
-  data.tar.gz: b643bf84aeebb2a68d0dadc6865ff868bafe3fab8e3d4d52772901c619fb9b9d9ca4f2f1ca1be3d693c05de02cb2c003522cce1e1cafc8bac769c716cf70284a
+  metadata.gz: 3dceae48df77f99164eeabd11b9f29e95a980d7efbc2472ee5192512e46467dd6b17f4b2dbf3869eeb9b4a45cee18996fda7bbd6b88813e0563ee22484931ea9
+  data.tar.gz: 9ca7a462a2cdcefa0d5576b1004f5f7d70160c4ac977d4343e81c64eb61621f667f478a2bb9807ad1d348d79dde8238dbadb4f26d69cc52549538a8102ff78a0

data/.agents/architecture.md

@@ -0,0 +1,113 @@
+# 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.
+
+```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
+- Zeitwerk for autoloading - file structure must match module/class names
+
+## 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
+```
+
+## 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
+```

data/.agents/code-style.md

@@ -0,0 +1,42 @@
+# Code Style
+
+## Formatting
+
+- Use StandardRB for linting and formatting
+- Custom rules are defined in `.standard.yml`
+- Run `bundle exec rake standard` to check, `bundle exec rake standard:fix` to auto-fix
+
+## Required Header
+
+All Ruby files must include:
+
+```ruby
+# frozen_string_literal: true
+```
+
+## Error Handling
+
+Define custom errors as subclasses of `Riffer::Error`:
+
+```ruby
+class MyCustomError < Riffer::Error
+end
+```
+
+## Comments
+
+- Only add comments when the code is ambiguous or not semantically obvious
+- Explain **why** something is done, not **what** is being done
+- Comments should add value beyond what the code already expresses
+
+## Module Structure
+
+```ruby
+# frozen_string_literal: true
+
+module Riffer::Feature
+  class MyClass
+    # Implementation
+  end
+end
+```

data/.agents/providers.md

@@ -0,0 +1,46 @@
+# Adding a New Provider
+
+## Steps
+
+1. Create `lib/riffer/providers/your_provider.rb` extending `Riffer::Providers::Base`
+2. Implement required methods (see below)
+3. Register in `Riffer::Providers::Repository::REPO`
+4. Add provider config to `Riffer::Config` if needed
+5. Create tests in `test/riffer/providers/your_provider_test.rb`
+
+## Required Methods
+
+```ruby
+# frozen_string_literal: true
+
+module Riffer
+  module Providers
+    class YourProvider < Base
+      # Returns Riffer::Messages::Assistant
+      def perform_generate_text(messages, model:)
+        # Implementation
+      end
+
+      # Returns Enumerator yielding stream events
+      def perform_stream_text(messages, model:)
+        # Implementation
+      end
+    end
+  end
+end
+```
+
+## Registration
+
+Add to `Riffer::Providers::Repository::REPO`:
+
+```ruby
+REPO = {
+  # ... existing providers
+  your_provider: -> { YourProvider }
+}.freeze
+```
+
+## Dependencies
+
+Use `depends_on` helper for runtime dependency checking if your provider requires external gems.

data/.agents/rdoc.md

@@ -0,0 +1,51 @@
+# RDoc Documentation
+
+Use pure RDoc comments for public APIs (not YARD).
+
+## Parameters
+
+Use definition list syntax (`::`):
+
+```ruby
+# Creates a new agent.
+#
+# name:: String - the agent name
+# options:: Hash - optional configuration
+```
+
+## Return Values
+
+Document with prose:
+
+```ruby
+# Returns String - the agent identifier.
+```
+
+## Exceptions
+
+Document with prose:
+
+```ruby
+# Raises Riffer::ArgumentError if the name is invalid.
+```
+
+## Examples
+
+Include usage examples as indented code blocks:
+
+```ruby
+# Creates a new agent.
+#
+#   agent = MyAgent.new
+#   agent.generate('Hello')
+#
+```
+
+## Internal APIs
+
+Mark internal APIs with `:nodoc:` to exclude from documentation:
+
+```ruby
+def internal_method # :nodoc:
+end
+```

data/.agents/testing.md

@@ -0,0 +1,56 @@
+# Testing
+
+## Framework
+
+Use Minitest with the spec DSL for all tests.
+
+## 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
+```
+
+## Guidelines
+
+- Test files go in `test/` directory with `*_test.rb` suffix
+- Use `before`/`after` blocks for setup and cleanup
+- Stick to the single assertion rule where possible
+- Test edge cases and error conditions
+- Use Minitest assertions: `assert_equal`, `assert_instance_of`, `refute_nil`, etc.
+
+## VCR Cassettes
+
+Record external API interactions in `test/fixtures/vcr_cassettes/`.
+
+## Running Tests
+
+```bash
+# Run all 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"
+```

data/.release-please-manifest.json

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

data/AGENTS.md

@@ -1,315 +1,28 @@
-# AI Agent Development Guide
+# Riffer
 
-This guide provides comprehensive information for AI coding assistants working with the Riffer codebase.
+Ruby gem framework for building AI-powered agents with LLM provider adapters.
 
-## Project Overview
+## Quick Reference
 
-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.
+- **Ruby**: 3.2.0+
+- **Lint + Test**: `bundle exec rake`
+- **Autoloading**: Zeitwerk (file paths must match module/class names)
+- **Model format**: `provider/model` (e.g., `openai/gpt-4`)
 
-Key concepts:
+## Topic Guides
 
-- **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](.agents/architecture.md) - Core components and project structure
+- [Testing](.agents/testing.md) - Minitest spec DSL and VCR cassettes
+- [Code Style](.agents/code-style.md) - StandardRB and comment conventions
+- [RDoc](.agents/rdoc.md) - Documentation format for public APIs
+- [Providers](.agents/providers.md) - Adding new LLM provider adapters
 
-## Architecture
+## Commands
 
-### 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
+| Command | Description |
+|---------|-------------|
+| `bundle exec rake` | Run tests + lint (default) |
+| `bundle exec rake test` | Run tests only |
+| `bundle exec rake standard` | Check code style |
+| `bundle exec rake standard:fix` | Auto-fix style issues |
+| `bin/console` | Interactive console |

data/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.9.0](https://github.com/janeapp/riffer/compare/riffer/v0.8.0...riffer/v0.9.0) (2026-01-28)
+
+
+### Features
+
+* implement Riffer::Tools::Response for consistent tool result handling ([#91](https://github.com/janeapp/riffer/issues/91)) ([df44f1f](https://github.com/janeapp/riffer/commit/df44f1fe8ff0b5bea73a2df8d6c0b8359e6c47f3))
+
+## [0.8.0](https://github.com/janeapp/riffer/compare/riffer/v0.7.0...riffer/v0.8.0) (2026-01-26)
+
+
+### Features
+
+* add anthropic provider support ([#89](https://github.com/janeapp/riffer/issues/89)) ([338674e](https://github.com/janeapp/riffer/commit/338674e794535b2559ce4dca5d36e09e9512b94c))
+* add on_message callback for real-time message emission ([#87](https://github.com/janeapp/riffer/issues/87)) ([92e6f91](https://github.com/janeapp/riffer/commit/92e6f919b9facee9a2fb6234c1bdd69b525dbf21))
+* add timeout functionality to tools ([#86](https://github.com/janeapp/riffer/issues/86)) ([3b7d9af](https://github.com/janeapp/riffer/commit/3b7d9afeed829001de0f6524694c193d54f1e7af))
+* better docs ([#84](https://github.com/janeapp/riffer/issues/84)) ([630580a](https://github.com/janeapp/riffer/commit/630580ae08a86dfa5ab1f75ebb229db7cff6344d))
+
 ## [0.7.0](https://github.com/janeapp/riffer/compare/riffer/v0.6.1...riffer/v0.7.0) (2026-01-21)