riffer 0.6.1 → 0.8.0

data/docs/05_MESSAGES.md

@@ -0,0 +1,173 @@
+# Messages
+
+Messages represent the conversation between users and the assistant. Riffer uses strongly-typed message objects to ensure consistency and type safety.
+
+## Message Types
+
+### System
+
+System messages provide instructions to the LLM:
+
+```ruby
+msg = Riffer::Messages::System.new("You are a helpful assistant.")
+msg.role     # => :system
+msg.content  # => "You are a helpful assistant."
+msg.to_h     # => {role: :system, content: "You are a helpful assistant."}
+```
+
+System messages are typically set via agent `instructions` and automatically prepended to conversations.
+
+### User
+
+User messages represent input from the user:
+
+```ruby
+msg = Riffer::Messages::User.new("Hello, how are you?")
+msg.role     # => :user
+msg.content  # => "Hello, how are you?"
+msg.to_h     # => {role: :user, content: "Hello, how are you?"}
+```
+
+### Assistant
+
+Assistant messages represent LLM responses, potentially including tool calls:
+
+```ruby
+# Text-only response
+msg = Riffer::Messages::Assistant.new("I'm doing well, thank you!")
+msg.role        # => :assistant
+msg.content     # => "I'm doing well, thank you!"
+msg.tool_calls  # => []
+
+# Response with tool calls
+msg = Riffer::Messages::Assistant.new("", tool_calls: [
+  {id: "call_123", call_id: "call_123", name: "weather_tool", arguments: '{"city":"Tokyo"}'}
+])
+msg.tool_calls  # => [{id: "call_123", ...}]
+msg.to_h        # => {role: "assistant", content: "", tool_calls: [...]}
+```
+
+### Tool
+
+Tool messages contain the results of tool executions:
+
+```ruby
+msg = Riffer::Messages::Tool.new(
+  "The weather in Tokyo is 22C and sunny.",
+  tool_call_id: "call_123",
+  name: "weather_tool"
+)
+msg.role          # => :tool
+msg.content       # => "The weather in Tokyo is 22C and sunny."
+msg.tool_call_id  # => "call_123"
+msg.name          # => "weather_tool"
+msg.error?        # => false
+
+# Error result
+msg = Riffer::Messages::Tool.new(
+  "API rate limit exceeded",
+  tool_call_id: "call_123",
+  name: "weather_tool",
+  error: "API rate limit exceeded",
+  error_type: :execution_error
+)
+msg.error?      # => true
+msg.error       # => "API rate limit exceeded"
+msg.error_type  # => :execution_error
+```
+
+## Using Messages with Agents
+
+### String Prompts
+
+The simplest way to interact with an agent:
+
+```ruby
+agent = MyAgent.new
+response = agent.generate("Hello!")
+```
+
+This creates a `User` message internally.
+
+### Message Arrays
+
+For multi-turn conversations, pass an array of messages:
+
+```ruby
+messages = [
+  {role: :user, content: "What's the weather?"},
+  {role: :assistant, content: "I'll check that for you."},
+  {role: :user, content: "Thanks, I meant in Tokyo specifically."}
+]
+
+response = agent.generate(messages)
+```
+
+Messages can be hashes or `Riffer::Messages::Base` objects:
+
+```ruby
+messages = [
+  Riffer::Messages::User.new("Hello"),
+  Riffer::Messages::Assistant.new("Hi there!"),
+  Riffer::Messages::User.new("How are you?")
+]
+
+response = agent.generate(messages)
+```
+
+### Accessing Message History
+
+After calling `generate` or `stream`, access the full conversation:
+
+```ruby
+agent = MyAgent.new
+agent.generate("Hello!")
+
+agent.messages.each do |msg|
+  puts "[#{msg.role}] #{msg.content}"
+end
+# [system] You are a helpful assistant.
+# [user] Hello!
+# [assistant] Hi there! How can I help you today?
+```
+
+## Tool Call Structure
+
+Tool calls in assistant messages have this structure:
+
+```ruby
+{
+  id: "item_123",       # Item identifier
+  call_id: "call_456",  # Call identifier for response matching
+  name: "weather_tool", # Tool name
+  arguments: '{"city":"Tokyo"}'  # JSON string of arguments
+}
+```
+
+When creating tool result messages, use the `id` as `tool_call_id`.
+
+## Message Emission
+
+Agents can emit messages as they're added during generation via the `on_message` callback. This is useful for persistence or real-time logging. Only agent-generated messages (Assistant, Tool) are emitted—not inputs (System, User).
+
+See [Agents - on_message](03_AGENTS.md#on_message) for details.
+
+## Base Class
+
+All messages inherit from `Riffer::Messages::Base`:
+
+```ruby
+class Riffer::Messages::Base
+  attr_reader :content
+
+  def role
+    raise NotImplementedError
+  end
+
+  def to_h
+    {role: role, content: content}
+  end
+end
+```
+
+Subclasses implement `role` and optionally extend `to_h` with additional fields.

data/docs/06_STREAM_EVENTS.md

@@ -0,0 +1,191 @@
+# Stream Events
+
+When streaming responses, Riffer emits typed events that represent incremental updates from the LLM.
+
+## Using Streaming
+
+Use `stream` instead of `generate` to receive events as they arrive:
+
+```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[Complete]"
+  when Riffer::StreamEvents::ToolCallDelta
+    # Tool call being built
+  when Riffer::StreamEvents::ToolCallDone
+    puts "[Tool: #{event.name}]"
+  end
+end
+```
+
+## Event Types
+
+### TextDelta
+
+Emitted when incremental text content is received:
+
+```ruby
+event = Riffer::StreamEvents::TextDelta.new("Hello ")
+event.role     # => "assistant"
+event.content  # => "Hello "
+event.to_h     # => {role: "assistant", content: "Hello "}
+```
+
+Use this to display text in real-time as it streams.
+
+### TextDone
+
+Emitted when text generation is complete:
+
+```ruby
+event = Riffer::StreamEvents::TextDone.new("Hello, how can I help you?")
+event.role     # => "assistant"
+event.content  # => "Hello, how can I help you?"
+event.to_h     # => {role: "assistant", content: "Hello, how can I help you?"}
+```
+
+Contains the complete final text.
+
+### ToolCallDelta
+
+Emitted when tool call arguments are being streamed:
+
+```ruby
+event = Riffer::StreamEvents::ToolCallDelta.new(
+  item_id: "item_123",
+  name: "weather_tool",
+  arguments_delta: '{"city":'
+)
+event.role             # => "assistant"
+event.item_id          # => "item_123"
+event.name             # => "weather_tool"
+event.arguments_delta  # => '{"city":'
+```
+
+The `name` may only be present in the first delta. Accumulate `arguments_delta` to build the complete arguments.
+
+### ToolCallDone
+
+Emitted when a tool call is complete:
+
+```ruby
+event = Riffer::StreamEvents::ToolCallDone.new(
+  item_id: "item_123",
+  call_id: "call_456",
+  name: "weather_tool",
+  arguments: '{"city":"Tokyo"}'
+)
+event.role       # => "assistant"
+event.item_id    # => "item_123"
+event.call_id    # => "call_456"
+event.name       # => "weather_tool"
+event.arguments  # => '{"city":"Tokyo"}'
+```
+
+Contains the complete tool call information.
+
+### ReasoningDelta
+
+Emitted when reasoning/thinking content is streamed (OpenAI with reasoning enabled):
+
+```ruby
+event = Riffer::StreamEvents::ReasoningDelta.new("Let me think about ")
+event.role     # => "assistant"
+event.content  # => "Let me think about "
+```
+
+### ReasoningDone
+
+Emitted when reasoning is complete:
+
+```ruby
+event = Riffer::StreamEvents::ReasoningDone.new("Let me think about this step by step...")
+event.role     # => "assistant"
+event.content  # => "Let me think about this step by step..."
+```
+
+## Streaming with Tools
+
+When an agent uses tools during streaming, the flow is:
+
+1. Text events stream in (`TextDelta`, `TextDone`)
+2. If tool calls are present: `ToolCallDelta` events, then `ToolCallDone`
+3. Agent executes tools internally
+4. Agent sends results back to LLM
+5. More text events stream in
+6. Repeat until no more tool calls
+
+```ruby
+agent.stream("What's the weather in Tokyo?").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::ToolCallDone
+    puts "\n[Calling #{event.name}...]"
+  when Riffer::StreamEvents::TextDone
+    puts "\n"
+  end
+end
+```
+
+## Complete Example
+
+```ruby
+class WeatherAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a weather assistant.'
+  uses_tools [WeatherTool]
+end
+
+agent = WeatherAgent.new
+text_buffer = ""
+
+agent.stream("What's the weather in Tokyo and New York?").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+    text_buffer += event.content
+
+  when Riffer::StreamEvents::TextDone
+    # Final text available
+    puts "\n---"
+    puts "Complete response: #{event.content}"
+
+  when Riffer::StreamEvents::ToolCallDelta
+    # Could show "typing..." indicator
+
+  when Riffer::StreamEvents::ToolCallDone
+    puts "\n[Tool: #{event.name}(#{event.arguments})]"
+
+  when Riffer::StreamEvents::ReasoningDelta
+    # Show thinking process if desired
+    print "[thinking] #{event.content}"
+
+  when Riffer::StreamEvents::ReasoningDone
+    puts "\n[reasoning complete]"
+  end
+end
+```
+
+## Base Class
+
+All events inherit from `Riffer::StreamEvents::Base`:
+
+```ruby
+class Riffer::StreamEvents::Base
+  attr_reader :role
+
+  def initialize(role: "assistant")
+    @role = role
+  end
+
+  def to_h
+    raise NotImplementedError
+  end
+end
+```

data/docs/07_CONFIGURATION.md

@@ -0,0 +1,195 @@
+# Configuration
+
+Riffer uses a centralized configuration system for provider credentials and settings.
+
+## Global Configuration
+
+Use `Riffer.configure` to set up provider credentials:
+
+```ruby
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+  config.amazon_bedrock.region = 'us-east-1'
+  config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
+  config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
+end
+```
+
+## Accessing Configuration
+
+Access the current configuration via `Riffer.config`:
+
+```ruby
+Riffer.config.openai.api_key
+# => "sk-..."
+
+Riffer.config.amazon_bedrock.region
+# => "us-east-1"
+
+Riffer.config.anthropic.api_key
+# => "sk-ant-..."
+```
+
+## Provider-Specific Configuration
+
+### OpenAI
+
+| Option    | Description         |
+| --------- | ------------------- |
+| `api_key` | Your OpenAI API key |
+
+```ruby
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+```
+
+### Amazon Bedrock
+
+| Option      | Description                                  |
+| ----------- | -------------------------------------------- |
+| `region`    | AWS region (e.g., `us-east-1`)               |
+| `api_token` | Optional bearer token for API authentication |
+
+```ruby
+Riffer.configure do |config|
+  config.amazon_bedrock.region = 'us-east-1'
+  config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']  # Optional
+end
+```
+
+When `api_token` is not set, the provider uses standard AWS IAM authentication.
+
+### Anthropic
+
+| Option    | Description            |
+| --------- | ---------------------- |
+| `api_key` | Your Anthropic API key |
+
+```ruby
+Riffer.configure do |config|
+  config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
+end
+```
+
+## Agent-Level Configuration
+
+Override global configuration at the agent level:
+
+### provider_options
+
+Pass options directly to the provider client:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+
+  # Override API key for this agent only
+  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
+end
+```
+
+### model_options
+
+Pass options to each LLM request:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+
+  # These options are sent with every generate/stream call
+  model_options temperature: 0.7, reasoning: 'medium'
+end
+```
+
+## Common Model Options
+
+### OpenAI
+
+| Option        | Description                                      |
+| ------------- | ------------------------------------------------ |
+| `temperature` | Sampling temperature (0.0-2.0)                   |
+| `max_tokens`  | Maximum tokens in response                       |
+| `top_p`       | Nucleus sampling parameter                       |
+| `reasoning`   | Reasoning effort level (`low`, `medium`, `high`) |
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  model_options temperature: 0.7, reasoning: 'medium'
+end
+```
+
+### Amazon Bedrock
+
+| Option        | Description                |
+| ------------- | -------------------------- |
+| `temperature` | Sampling temperature       |
+| `max_tokens`  | Maximum tokens in response |
+| `top_p`       | Nucleus sampling parameter |
+| `top_k`       | Top-k sampling parameter   |
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'
+  model_options temperature: 0.7, max_tokens: 4096
+end
+```
+
+### Anthropic
+
+| Option        | Description                                 |
+| ------------- | ------------------------------------------- |
+| `temperature` | Sampling temperature                        |
+| `max_tokens`  | Maximum tokens in response                  |
+| `top_p`       | Nucleus sampling parameter                  |
+| `top_k`       | Top-k sampling parameter                    |
+| `thinking`    | Extended thinking config hash (Claude 3.7+) |
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'anthropic/claude-3-5-sonnet-20241022'
+  model_options temperature: 0.7, max_tokens: 4096
+end
+
+# With extended thinking (Claude 3.7+)
+class ReasoningAgent < Riffer::Agent
+  model 'anthropic/claude-3-7-sonnet-20250219'
+  model_options thinking: {type: "enabled", budget_tokens: 10000}
+end
+```
+
+## Environment Variables
+
+Recommended pattern for managing credentials:
+
+```ruby
+# config/initializers/riffer.rb (Rails)
+# or at application startup
+
+Riffer.configure do |config|
+  config.openai.api_key = ENV.fetch('OPENAI_API_KEY') { raise 'OPENAI_API_KEY not set' }
+
+  if ENV['BEDROCK_REGION']
+    config.amazon_bedrock.region = ENV['BEDROCK_REGION']
+    config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
+  end
+end
+```
+
+## Multiple Configurations
+
+For different environments or use cases, use agent-level overrides:
+
+```ruby
+class ProductionAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  provider_options api_key: ENV['PRODUCTION_OPENAI_KEY']
+end
+
+class DevelopmentAgent < Riffer::Agent
+  model 'openai/gpt-4o-mini'
+  provider_options api_key: ENV['DEV_OPENAI_KEY']
+  model_options temperature: 0.0  # Deterministic for testing
+end
+```