riffer 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8f9dc7979fb2338edff2e1c6fb7a6a0281126e95ac8b12bd9e268385dd56263
-  data.tar.gz: a92ec2768bcb0efc3524945f5a69b685ca16dbba40ee852d6c24efdfbde883fd
+  metadata.gz: ace7d52275897dc91ce42de1acc67db3de289c55953a56fa833a0f92f9c48c7c
+  data.tar.gz: ddee9798fb18502bd0e0e14e61d899a3cb24b240a6e6f9ab95b00199f03f7b59
 SHA512:
-  metadata.gz: 62f476d0a84c1ac94520eebf8e11d7773299e0c87a56d9ea473dfbde310ec9a905da9f3446b2a76e5d282e5f52dcf82857397836f3d300d93cab222aceb12065
-  data.tar.gz: 5518dd2966cb8d62553778fe6428d3e339bfe78293dd0eaed4a82b5500f80d2e78ee6f4648c46f62fffd258c293e7894e624ff117a668fab7f5d3a908d246cae
+  metadata.gz: 6c32731c0ac374bcc90fddd3c1cf071e3e2a1a2e2ae197ffcf98aace5acc4402c38d24657b2d3c211dfbf8d951a48ab9e94087a4b3accb2e763eb6202fa07312
+  data.tar.gz: da8b8ba45b0a5e08e4f2c7b212ddba5761fd2673d1c89fea695b1cb2d60e9ba1f7a01d9138f0eed33b406a7c7e116eb219e1f7a4919a7a4183cfe2dc97f59622

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.6.1"
+  ".": "0.8.0"
 }

data/AGENTS.md

@@ -0,0 +1,28 @@
+# Riffer
+
+Ruby gem framework for building AI-powered agents with LLM provider adapters.
+
+## Quick Reference
+
+- **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`)
+
+## Topic Guides
+
+- [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
+
+## Commands
+
+| 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.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)
+
+
+### 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

@@ -2,24 +2,7 @@
 
 The all-in-one Ruby framework for building AI-powered applications and agents.
 
-[![Gem Version](https://badge.fury.io/rb/riffer.svg)](https://badge.fury.io/rb/riffer) ⚠️ Work in progress
-
-## Overview
-
-Riffer is a comprehensive Ruby framework designed to simplify the development of AI-powered applications and agents. It provides a complete toolkit for integrating artificial intelligence capabilities into your Ruby projects.
-
-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::*`).
-
-## Features
-
-- Minimal, well-documented core for building AI agents
-- Provider abstraction (OpenAI) for pluggable providers
-- Streaming support and structured stream events
-- Message converters and helpers for robust message handling
+[![Gem Version](https://badge.fury.io/rb/riffer.svg)](https://badge.fury.io/rb/riffer)
 
 ## Requirements
 
@@ -39,43 +22,50 @@ Or add to your application's Gemfile:
 gem 'riffer'
 ```
 
-Install the development branch directly from GitHub:
-
-```ruby
-gem 'riffer', git: 'https://github.com/janeapp/riffer.git'
-```
-
 ## Quick Start
 
-Basic usage with the OpenAI provider:
-
 ```ruby
 require 'riffer'
 
-# Configure OpenAI API key (recommended to use ENV)
+# Configure your provider
 Riffer.configure do |config|
   config.openai.api_key = ENV['OPENAI_API_KEY']
 end
 
+# Define an agent
 class EchoAgent < Riffer::Agent
-  model 'openai/gpt-5-mini' # provider/model
+  model 'openai/gpt-4o'
   instructions 'You are an assistant that repeats what the user says.'
 end
 
+# Use the agent
 agent = EchoAgent.new
 puts agent.generate('Hello world')
-# => "Hello world"
 ```
 
-Streaming example:
+## Documentation
 
-```ruby
-agent = EchoAgent.new
-agent.stream('Tell me a story').each do |event|
-  print event.content
-end
+For comprehensive documentation, see the [docs](docs/) directory:
+
+- [Overview](docs/01_OVERVIEW.md) - Core concepts and architecture
+- [Getting Started](docs/02_GETTING_STARTED.md) - Installation and first steps
+- [Agents](docs/03_AGENTS.md) - Building AI agents
+- [Tools](docs/04_TOOLS.md) - Creating tools for agents
+- [Messages](docs/05_MESSAGES.md) - Message types and formats
+- [Stream Events](docs/06_STREAM_EVENTS.md) - Streaming responses
+- [Configuration](docs/07_CONFIGURATION.md) - Framework configuration
+- [Providers](docs_providers/01_PROVIDERS.md) - LLM provider adapters
+
+### API Reference
+
+Generate the full API documentation with:
+
+```bash
+bundle exec rake docs
 ```
 
+Then open `doc/index.html` in your browser.
+
 ## Development
 
 After checking out the repo, run:
@@ -121,4 +111,4 @@ Licensed under the MIT License. See `LICENSE.txt` for details.
 
 ## Maintainers
 
-- Jake Bottrall — https://github.com/bottrall
+- Jake Bottrall - https://github.com/bottrall

data/Rakefile

@@ -14,7 +14,7 @@ RDoc::Task.new do |rdoc|
   rdoc.main = "README.md"
 
   # Explicitly include top-level docs and the library
-  rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt")
+  rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt", "docs/**/*.md", "docs_providers/**/*.md")
   rdoc.rdoc_files.include("lib/**/*.rb")
 
   # Use Markdown where available and ensure UTF-8

data/docs/01_OVERVIEW.md

@@ -0,0 +1,106 @@
+# Overview
+
+Riffer is a Ruby framework for building AI-powered applications and agents. It provides a complete toolkit for integrating Large Language Models (LLMs) into your Ruby projects.
+
+## Core Concepts
+
+### Agent
+
+The Agent is the central orchestrator for AI interactions. It manages messages, calls the LLM provider, and handles tool execution.
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a helpful assistant.'
+end
+```
+
+See [Agents](03_AGENTS.md) for details.
+
+### Tool
+
+Tools are callable functions that agents can invoke to interact with external systems. They have structured parameter definitions and automatic validation.
+
+```ruby
+class WeatherTool < Riffer::Tool
+  description "Gets the weather for a city"
+
+  params do
+    required :city, String, description: "The city name"
+  end
+
+  def call(context:, city:)
+    WeatherAPI.fetch(city)
+  end
+end
+```
+
+See [Tools](04_TOOLS.md) for details.
+
+### Provider
+
+Providers are adapters that connect to LLM services. Riffer supports:
+
+- **OpenAI** - GPT models via the OpenAI API
+- **Amazon Bedrock** - Claude and other models via AWS Bedrock
+- **Test** - Mock provider for testing
+
+See [Providers](providers/01_PROVIDERS.md) for details.
+
+### Messages
+
+Messages represent the conversation between user and assistant. Riffer uses strongly-typed message objects:
+
+- `Riffer::Messages::System` - System instructions
+- `Riffer::Messages::User` - User input
+- `Riffer::Messages::Assistant` - LLM responses
+- `Riffer::Messages::Tool` - Tool execution results
+
+See [Messages](05_MESSAGES.md) for details.
+
+### Stream Events
+
+When streaming responses, Riffer emits typed events:
+
+- `TextDelta` - Incremental text chunks
+- `TextDone` - Complete text
+- `ToolCallDelta` - Incremental tool call arguments
+- `ToolCallDone` - Complete tool call
+
+See [Stream Events](06_STREAM_EVENTS.md) for details.
+
+## Architecture
+
+```
+User Request
+     |
+     v
++------------+
+|   Agent    |  <-- Manages conversation flow
++------------+
+     |
+     v
++------------+
+|  Provider  |  <-- Calls LLM API
++------------+
+     |
+     v
++------------+
+|    LLM     |  <-- Returns response
++------------+
+     |
+     v
++------------+
+|   Tool?    |  <-- Execute if tool call present
++------------+
+     |
+     v
+Response
+```
+
+## Next Steps
+
+- [Getting Started](02_GETTING_STARTED.md) - Quick start guide
+- [Agents](03_AGENTS.md) - Agent configuration and usage
+- [Tools](04_TOOLS.md) - Creating tools
+- [Configuration](07_CONFIGURATION.md) - Global configuration