riffer 0.7.0 → 0.8.0

data/docs_providers/03_ANTHROPIC.md

@@ -0,0 +1,211 @@
+# Anthropic Provider
+
+The Anthropic provider connects to Claude models via the Anthropic API.
+
+## Installation
+
+Add the Anthropic gem to your Gemfile:
+
+```ruby
+gem 'anthropic'
+```
+
+## Configuration
+
+Configure your Anthropic API key:
+
+```ruby
+Riffer.configure do |config|
+  config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
+end
+```
+
+Or per-agent:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'anthropic/claude-4-5-haiku-20251001'
+  provider_options api_key: ENV['ANTHROPIC_API_KEY']
+end
+```
+
+## Supported Models
+
+Use Anthropic model IDs in the `anthropic/model` format:
+
+```ruby
+model 'anthropic/claude-haiku-4-5-20251001'
+model 'anthropic/claude-sonnet-4-5-20250929'
+model 'anthropic/claude-opus-4-5-20251101'
+```
+
+## Model Options
+
+### temperature
+
+Controls randomness:
+
+```ruby
+model_options temperature: 0.7
+```
+
+### max_tokens
+
+Maximum tokens in response:
+
+```ruby
+model_options max_tokens: 4096
+```
+
+### top_p
+
+Nucleus sampling parameter:
+
+```ruby
+model_options top_p: 0.95
+```
+
+### top_k
+
+Top-k sampling parameter:
+
+```ruby
+model_options top_k: 250
+```
+
+### thinking
+
+Enable extended thinking (reasoning) for supported models. Pass the thinking configuration hash directly as Anthropic expects:
+
+```ruby
+# Enable with budget tokens
+model_options thinking: {type: "enabled", budget_tokens: 10000}
+```
+
+## Example
+
+```ruby
+Riffer.configure do |config|
+  config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
+end
+
+class AssistantAgent < Riffer::Agent
+  model 'anthropic/claude-4-5-haiku-20251001'
+  instructions 'You are a helpful assistant.'
+  model_options temperature: 0.7, max_tokens: 4096
+end
+
+agent = AssistantAgent.new
+puts agent.generate("Explain quantum computing")
+```
+
+## Streaming
+
+```ruby
+agent.stream("Tell me about Claude models").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::TextDone
+    puts "\n[Complete]"
+  when Riffer::StreamEvents::ReasoningDelta
+    print "[Thinking] #{event.content}"
+  when Riffer::StreamEvents::ReasoningDone
+    puts "\n[Thinking Complete]"
+  when Riffer::StreamEvents::ToolCallDone
+    puts "[Tool: #{event.name}]"
+  end
+end
+```
+
+## Tool Calling
+
+Anthropic provider converts tools to the Anthropic tool format:
+
+```ruby
+class WeatherTool < Riffer::Tool
+  description "Gets the current weather for a location"
+
+  params do
+    required :city, String, description: "The city name"
+    optional :unit, String, description: "Temperature unit (celsius or fahrenheit)"
+  end
+
+  def call(context:, city:, unit: "celsius")
+    # Implementation
+    "It's 22 degrees #{unit} in #{city}"
+  end
+end
+
+class WeatherAgent < Riffer::Agent
+  model 'anthropic/claude-4-5-haiku-20251001'
+  uses_tools [WeatherTool]
+end
+```
+
+## Extended Thinking
+
+Extended thinking enables Claude to reason through complex problems before responding. This is available on Claude 3.7 models.
+
+```ruby
+class ReasoningAgent < Riffer::Agent
+  model 'anthropic/claude-4-5-haiku-20251001'
+  model_options thinking: {type: "enabled", budget_tokens: 10000}
+end
+```
+
+When streaming with extended thinking enabled, you'll receive `ReasoningDelta` events containing the model's thought process, followed by a `ReasoningDone` event when thinking completes:
+
+```ruby
+agent.stream("Solve this complex math problem").each do |event|
+  case event
+  when Riffer::StreamEvents::ReasoningDelta
+    # Model's internal reasoning
+    print "[Thinking] #{event.content}"
+  when Riffer::StreamEvents::ReasoningDone
+    puts "\n[Thinking complete]"
+  when Riffer::StreamEvents::TextDelta
+    # Final response
+    print event.content
+  end
+end
+```
+
+## Message Format
+
+The provider converts Riffer messages to Anthropic format:
+
+| Riffer Message | Anthropic Format                                                |
+| -------------- | --------------------------------------------------------------- |
+| `System`       | Added to `system` array as `{type: "text", text: ...}`          |
+| `User`         | `{role: "user", content: "..."}`                                |
+| `Assistant`    | `{role: "assistant", content: [...]}` with text/tool_use blocks |
+| `Tool`         | `{role: "user", content: [{type: "tool_result", ...}]}`         |
+
+## Direct Provider Usage
+
+```ruby
+provider = Riffer::Providers::Anthropic.new(
+  api_key: ENV['ANTHROPIC_API_KEY']
+)
+
+response = provider.generate_text(
+  prompt: "Hello!",
+  model: "claude-4-5-haiku-20251001",
+  temperature: 0.7
+)
+
+puts response.content
+```
+
+### With extended thinking:
+
+```ruby
+response = provider.generate_text(
+  prompt: "Explain step by step how to solve a Rubik's cube",
+  model: "claude-4-5-haiku-20251001",
+  thinking: { type: "enabled", budget_tokens: 10000 }
+)
+
+puts response.content
+```

data/docs_providers/04_OPENAI.md

@@ -0,0 +1,157 @@
+# OpenAI Provider
+
+The OpenAI provider connects to OpenAI's API for GPT models.
+
+## Installation
+
+Add the OpenAI gem to your Gemfile:
+
+```ruby
+gem 'openai'
+```
+
+## Configuration
+
+Set your API key globally:
+
+```ruby
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+```
+
+Or per-agent:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  provider_options api_key: ENV['CUSTOM_API_KEY']
+end
+```
+
+## Supported Models
+
+Use any OpenAI model in the `openai/model` format:
+
+```ruby
+model 'openai/gpt-4o'
+model 'openai/gpt-4o-mini'
+model 'openai/gpt-4-turbo'
+model 'openai/gpt-3.5-turbo'
+```
+
+## Model Options
+
+### temperature
+
+Controls randomness (0.0-2.0):
+
+```ruby
+model_options temperature: 0.7
+```
+
+### max_tokens
+
+Maximum tokens in response:
+
+```ruby
+model_options max_tokens: 4096
+```
+
+### reasoning
+
+Enables extended thinking (for supported models):
+
+```ruby
+model_options reasoning: 'medium'  # 'low', 'medium', or 'high'
+```
+
+When reasoning is enabled, you'll receive `ReasoningDelta` and `ReasoningDone` events during streaming.
+
+## Example
+
+```ruby
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+
+class CodeReviewAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a code reviewer. Provide constructive feedback.'
+  model_options temperature: 0.3, reasoning: 'medium'
+end
+
+agent = CodeReviewAgent.new
+puts agent.generate("Review this code: def add(a,b); a+b; end")
+```
+
+## Streaming
+
+```ruby
+agent.stream("Explain Ruby blocks").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::ReasoningDelta
+    # Extended thinking content
+    print "[thinking] #{event.content}"
+  when Riffer::StreamEvents::ReasoningDone
+    puts "\n[reasoning complete]"
+  end
+end
+```
+
+## Tool Calling
+
+OpenAI provider converts tools to function calling format with strict mode:
+
+```ruby
+class CalculatorTool < Riffer::Tool
+  description "Performs basic math operations"
+
+  params do
+    required :operation, String, enum: ["add", "subtract", "multiply", "divide"]
+    required :a, Float, description: "First number"
+    required :b, Float, description: "Second number"
+  end
+
+  def call(context:, operation:, a:, b:)
+    case operation
+    when "add" then a + b
+    when "subtract" then a - b
+    when "multiply" then a * b
+    when "divide" then a / b
+    end.to_s
+  end
+end
+
+class MathAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  uses_tools [CalculatorTool]
+end
+```
+
+## Message Format
+
+The provider converts Riffer messages to OpenAI format:
+
+| Riffer Message | OpenAI Role            |
+| -------------- | ---------------------- |
+| `System`       | `developer`            |
+| `User`         | `user`                 |
+| `Assistant`    | `assistant`            |
+| `Tool`         | `function_call_output` |
+
+## Direct Provider Usage
+
+```ruby
+provider = Riffer::Providers::OpenAI.new(api_key: ENV['OPENAI_API_KEY'])
+
+response = provider.generate_text(
+  prompt: "Hello!",
+  model: "gpt-4o",
+  temperature: 0.7
+)
+
+puts response.content
+```

data/docs_providers/05_TEST_PROVIDER.md

@@ -0,0 +1,163 @@
+# Test Provider
+
+The Test provider is a mock provider for testing agents without making real API calls.
+
+## Usage
+
+No additional gems required. Use the `test` provider identifier:
+
+```ruby
+class TestableAgent < Riffer::Agent
+  model 'test/any'  # The model name doesn't matter for test provider
+  instructions 'You are helpful.'
+  uses_tools [MyTool]
+end
+```
+
+## Stubbing Responses
+
+Use `stub_response` to queue responses:
+
+```ruby
+# Get the provider instance from the agent
+agent = TestableAgent.new
+provider = agent.send(:provider_instance)
+
+# Stub a simple text response
+provider.stub_response("Hello, I'm here to help!")
+
+# Now generate will return the stubbed response
+response = agent.generate("Hi")
+# => "Hello, I'm here to help!"
+```
+
+## Stubbing Tool Calls
+
+Stub responses that trigger tool execution:
+
+```ruby
+provider.stub_response("", tool_calls: [
+  {name: "my_tool", arguments: '{"query":"test"}'}
+])
+
+# Queue the response after tool execution
+provider.stub_response("Based on the tool result, here's my answer.")
+
+response = agent.generate("Use the tool")
+```
+
+## Queueing Multiple Responses
+
+Responses are consumed in order:
+
+```ruby
+provider.stub_response("First response")
+provider.stub_response("Second response")
+provider.stub_response("Third response")
+
+agent.generate("Message 1")  # => "First response"
+agent.generate("Message 2")  # => "Second response"
+agent.generate("Message 3")  # => "Third response"
+agent.generate("Message 4")  # => "Test response" (default)
+```
+
+## Inspecting Calls
+
+Access recorded calls for assertions:
+
+```ruby
+provider.calls
+# => [
+#   {messages: [...], model: "any", tools: [...], ...},
+#   {messages: [...], model: "any", tools: [...], ...}
+# ]
+
+# Check what was sent
+expect(provider.calls.last[:messages].last[:content]).to eq("Hi")
+```
+
+## Clearing State
+
+Reset stubbed responses:
+
+```ruby
+provider.clear_stubs
+```
+
+## Example Test
+
+```ruby
+require 'minitest/autorun'
+
+class MyAgentTest < Minitest::Test
+  def setup
+    @agent = TestableAgent.new
+    @provider = @agent.send(:provider_instance)
+  end
+
+  def test_generates_response
+    @provider.stub_response("Hello!")
+
+    response = @agent.generate("Hi")
+
+    assert_equal "Hello!", response
+  end
+
+  def test_executes_tool
+    @provider.stub_response("", tool_calls: [
+      {name: "weather_tool", arguments: '{"city":"Tokyo"}'}
+    ])
+    @provider.stub_response("The weather is sunny.")
+
+    response = @agent.generate("What's the weather?")
+
+    assert_equal "The weather is sunny.", response
+    assert_equal 2, @provider.calls.length
+  end
+
+  def test_passes_context_to_tools
+    @provider.stub_response("", tool_calls: [
+      {name: "user_tool", arguments: '{}'}
+    ])
+    @provider.stub_response("Done.")
+
+    @agent.generate("Do something", tool_context: {user_id: 123})
+
+    # Tool receives the context
+  end
+end
+```
+
+## Streaming
+
+The test provider also supports streaming:
+
+```ruby
+provider.stub_response("Hello world.")
+
+events = []
+agent.stream("Hi").each { |e| events << e }
+
+# Events include TextDelta and TextDone
+text_deltas = events.select { |e| e.is_a?(Riffer::StreamEvents::TextDelta) }
+text_done = events.find { |e| e.is_a?(Riffer::StreamEvents::TextDone) }
+```
+
+## Initial Responses
+
+Pass responses during initialization:
+
+```ruby
+provider = Riffer::Providers::Test.new(responses: [
+  {content: "First"},
+  {content: "Second"}
+])
+```
+
+## Default Response
+
+When no stubs are queued and initial responses are exhausted, the provider returns:
+
+```ruby
+{role: "assistant", content: "Test response"}
+```