riffer 0.7.0 → 0.8.0

data/README.md

@@ -2,26 +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`).
-- **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
-- 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
+[![Gem Version](https://badge.fury.io/rb/riffer.svg)](https://badge.fury.io/rb/riffer)
 
 ## Requirements
 
@@ -41,121 +22,49 @@ 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:
-
-```ruby
-agent = EchoAgent.new
-agent.stream('Tell me a story').each do |event|
-  print event.content
-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:
+## Documentation
 
-```ruby
-class DynamicAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+For comprehensive documentation, see the [docs](docs/) directory:
 
-  uses_tools ->(context) {
-    tools = [WeatherLookupTool]
-    tools << AdminTool if context&.dig(:current_user)&.admin?
-    tools
-  }
-end
+- [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
 
-agent = DynamicAgent.new
-agent.generate("Do admin things", tool_context: { current_user: current_user })
-```
+### API Reference
 
-Pass context to tools using `tool_context`:
+Generate the full API documentation with:
 
-```ruby
-agent.generate("Look up my city", tool_context: { user_id: current_user.id })
+```bash
+bundle exec rake docs
 ```
 
-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.
+Then open `doc/index.html` in your browser.
 
 ## Development
 
@@ -202,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

data/docs/02_GETTING_STARTED.md

@@ -0,0 +1,128 @@
+# Getting Started
+
+This guide walks you through installing Riffer and creating your first AI agent.
+
+## Installation
+
+Add Riffer to your Gemfile:
+
+```ruby
+gem 'riffer'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install riffer
+```
+
+## Provider Setup
+
+Riffer requires an LLM provider. Install the provider gem for your chosen service:
+
+### OpenAI
+
+```ruby
+gem 'openai'
+```
+
+Configure your API key:
+
+```ruby
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+```
+
+### Amazon Bedrock
+
+```ruby
+gem 'aws-sdk-bedrockruntime'
+```
+
+Configure your credentials:
+
+```ruby
+Riffer.configure do |config|
+  config.amazon_bedrock.region = 'us-east-1'
+  # Optional: Use bearer token auth instead of IAM
+  config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
+end
+```
+
+## Creating Your First Agent
+
+Define an agent by subclassing `Riffer::Agent`:
+
+```ruby
+require 'riffer'
+
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+
+class GreetingAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a friendly assistant. Greet the user warmly.'
+end
+
+agent = GreetingAgent.new
+response = agent.generate('Hello!')
+puts response
+# => "Hello! It's wonderful to meet you..."
+```
+
+## Streaming Responses
+
+Use `stream` for real-time output:
+
+```ruby
+agent = GreetingAgent.new
+
+agent.stream('Tell me a story').each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::TextDone
+    puts "\n[Done]"
+  end
+end
+```
+
+## Adding Tools
+
+Tools let agents interact with external systems:
+
+```ruby
+class TimeTool < Riffer::Tool
+  description "Gets the current time"
+
+  def call(context:)
+    Time.now.strftime('%Y-%m-%d %H:%M:%S')
+  end
+end
+
+class TimeAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You can tell the user the current time.'
+  uses_tools [TimeTool]
+end
+
+agent = TimeAgent.new
+puts agent.generate("What time is it?")
+# => "The current time is 2024-01-15 14:30:00."
+```
+
+## Next Steps
+
+- [Agents](03_AGENTS.md) - Agent configuration options
+- [Tools](04_TOOLS.md) - Creating tools with parameters
+- [Messages](05_MESSAGES.md) - Message types and history
+- [Stream Events](06_STREAM_EVENTS.md) - Streaming event types
+- [Providers](providers/01_PROVIDERS.md) - Provider-specific guides

data/docs/03_AGENTS.md

@@ -0,0 +1,226 @@
+# Agents
+
+Agents are the central orchestrator in Riffer. They manage the conversation flow, call LLM providers, and handle tool execution.
+
+## Defining an Agent
+
+Create an agent by subclassing `Riffer::Agent`:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a helpful assistant.'
+end
+```
+
+## Configuration Methods
+
+### model
+
+Sets the provider and model in `provider/model` format:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'           # OpenAI
+  # or
+  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'  # Bedrock
+  # or
+  model 'test/any'                # Test provider
+end
+```
+
+### instructions
+
+Sets system instructions for the agent:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are an expert Ruby programmer. Provide concise answers.'
+end
+```
+
+### identifier
+
+Sets a custom identifier (defaults to snake_case class name):
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  identifier 'custom_agent_name'
+end
+
+MyAgent.identifier  # => "custom_agent_name"
+```
+
+### uses_tools
+
+Registers tools the agent can use:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  uses_tools [WeatherTool, TimeTool]
+end
+```
+
+Tools can also be resolved dynamically with a lambda:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+
+  uses_tools ->(context) {
+    tools = [PublicTool]
+    tools << AdminTool if context&.dig(:user)&.admin?
+    tools
+  }
+end
+```
+
+### provider_options
+
+Passes options to the provider client:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
+end
+```
+
+### model_options
+
+Passes options to each LLM request:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  model_options reasoning: 'medium', temperature: 0.7
+end
+```
+
+## Instance Methods
+
+### generate
+
+Generates a response synchronously:
+
+```ruby
+agent = MyAgent.new
+
+# With a string prompt
+response = agent.generate('Hello')
+
+# With message objects/hashes
+response = agent.generate([
+  {role: 'user', content: 'Hello'},
+  {role: 'assistant', content: 'Hi there!'},
+  {role: 'user', content: 'How are you?'}
+])
+
+# With tool context
+response = agent.generate('Look up my orders', tool_context: {user_id: 123})
+```
+
+### stream
+
+Streams a response as an Enumerator:
+
+```ruby
+agent = MyAgent.new
+
+agent.stream('Tell me a story').each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::TextDone
+    puts "\n"
+  when Riffer::StreamEvents::ToolCallDone
+    puts "[Tool: #{event.name}]"
+  end
+end
+```
+
+### messages
+
+Access the message history after a generate/stream call:
+
+```ruby
+agent = MyAgent.new
+agent.generate('Hello')
+
+agent.messages.each do |msg|
+  puts "#{msg.role}: #{msg.content}"
+end
+```
+
+### on_message
+
+Registers a callback to receive messages as they're added during generation:
+
+```ruby
+agent.on_message do |message|
+  case message.role
+  when :assistant
+    puts "[Assistant] #{message.content}"
+  when :tool
+    puts "[Tool:#{message.name}] #{message.content}"
+  end
+end
+```
+
+Multiple callbacks can be registered. Returns `self` for method chaining:
+
+```ruby
+agent
+  .on_message { |msg| persist_message(msg) }
+  .on_message { |msg| log_message(msg) }
+  .generate('Hello')
+```
+
+Works with both `generate` and `stream`. Only emits agent-generated messages (Assistant, Tool), not inputs (System, User).
+
+## Class Methods
+
+### find
+
+Find an agent class by identifier:
+
+```ruby
+agent_class = Riffer::Agent.find('my_agent')
+agent = agent_class.new
+```
+
+### all
+
+List all agent subclasses:
+
+```ruby
+Riffer::Agent.all.each do |agent_class|
+  puts agent_class.identifier
+end
+```
+
+## Tool Execution Flow
+
+When an agent receives a response with tool calls:
+
+1. Agent detects `tool_calls` in the assistant message
+2. For each tool call:
+   - Finds the matching tool class
+   - Validates arguments against the tool's parameter schema
+   - Calls the tool's `call` method with `context` and arguments
+   - Creates a Tool message with the result
+3. Sends the updated message history back to the LLM
+4. Repeats until no more tool calls
+
+## Error Handling
+
+Tool execution errors are captured and sent back to the LLM:
+
+- `unknown_tool` - Tool not found in registered tools
+- `validation_error` - Arguments failed validation
+- `execution_error` - Tool raised an exception
+
+The LLM can use this information to retry or respond appropriately.