riffer 0.6.1 → 0.8.0

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"}
+```

data/docs_providers/06_CUSTOM_PROVIDERS.md

@@ -0,0 +1,304 @@
+# Creating Custom Providers
+
+You can create custom providers to connect Riffer to other LLM services.
+
+## Basic Structure
+
+Extend `Riffer::Providers::Base` and implement the required methods:
+
+```ruby
+class Riffer::Providers::MyProvider < Riffer::Providers::Base
+  def initialize(**options)
+    # Initialize your client
+    @api_key = options[:api_key] || ENV['MY_PROVIDER_API_KEY']
+    @client = MyProviderClient.new(api_key: @api_key)
+  end
+
+  private
+
+  def perform_generate_text(messages, model:, **options)
+    # Convert messages to provider format
+    formatted = convert_messages(messages)
+
+    # Call your provider's API
+    response = @client.generate(
+      model: model,
+      messages: formatted,
+      **options
+    )
+
+    # Return a Riffer::Messages::Assistant
+    Riffer::Messages::Assistant.new(
+      response.text,
+      tool_calls: extract_tool_calls(response)
+    )
+  end
+
+  def perform_stream_text(messages, model:, **options)
+    Enumerator.new do |yielder|
+      formatted = convert_messages(messages)
+
+      @client.stream(model: model, messages: formatted, **options) do |chunk|
+        # Yield appropriate stream events
+        case chunk.type
+        when :text
+          yielder << Riffer::StreamEvents::TextDelta.new(chunk.content)
+        when :text_done
+          yielder << Riffer::StreamEvents::TextDone.new(chunk.content)
+        when :tool_call
+          yielder << Riffer::StreamEvents::ToolCallDone.new(
+            item_id: chunk.id,
+            call_id: chunk.id,
+            name: chunk.name,
+            arguments: chunk.arguments
+          )
+        end
+      end
+    end
+  end
+
+  def convert_messages(messages)
+    messages.map do |msg|
+      case msg
+      when Riffer::Messages::System
+        {role: "system", content: msg.content}
+      when Riffer::Messages::User
+        {role: "user", content: msg.content}
+      when Riffer::Messages::Assistant
+        convert_assistant(msg)
+      when Riffer::Messages::Tool
+        {role: "tool", tool_call_id: msg.tool_call_id, content: msg.content}
+      end
+    end
+  end
+
+  def convert_assistant(msg)
+    # Handle tool calls if present
+    {role: "assistant", content: msg.content, tool_calls: msg.tool_calls}
+  end
+
+  def extract_tool_calls(response)
+    return [] unless response.tool_calls
+
+    response.tool_calls.map do |tc|
+      {
+        id: tc.id,
+        call_id: tc.id,
+        name: tc.name,
+        arguments: tc.arguments
+      }
+    end
+  end
+end
+```
+
+## Using depends_on
+
+For lazy loading of external gems:
+
+```ruby
+class Riffer::Providers::MyProvider < Riffer::Providers::Base
+  def initialize(**options)
+    depends_on "my_provider_gem"  # Only loaded when provider is used
+
+    @client = ::MyProviderGem::Client.new(**options)
+  end
+end
+```
+
+## Registering Your Provider
+
+Add your provider to the repository:
+
+```ruby
+# In lib/riffer/providers/repository.rb or your own code
+
+Riffer::Providers::Repository::REPO[:my_provider] = -> { Riffer::Providers::MyProvider }
+```
+
+Or create a custom repository:
+
+```ruby
+module MyApp
+  module Providers
+    def self.find(identifier)
+      case identifier.to_sym
+      when :my_provider
+        Riffer::Providers::MyProvider
+      else
+        Riffer::Providers::Repository.find(identifier)
+      end
+    end
+  end
+end
+```
+
+## Using Your Provider
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'my_provider/model-name'
+end
+```
+
+## Tool Support
+
+Convert tools to your provider's format:
+
+```ruby
+def perform_generate_text(messages, model:, tools: nil, **options)
+  params = {
+    model: model,
+    messages: convert_messages(messages)
+  }
+
+  if tools && !tools.empty?
+    params[:tools] = tools.map { |t| convert_tool(t) }
+  end
+
+  response = @client.generate(**params)
+  # ...
+end
+
+def convert_tool(tool)
+  {
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters_schema
+  }
+end
+```
+
+## Stream Events
+
+Use the appropriate stream event classes:
+
+```ruby
+# Text streaming
+Riffer::StreamEvents::TextDelta.new("chunk of text")
+Riffer::StreamEvents::TextDone.new("complete text")
+
+# Tool calls
+Riffer::StreamEvents::ToolCallDelta.new(
+  item_id: "id",
+  name: "tool_name",
+  arguments_delta: '{"partial":'
+)
+Riffer::StreamEvents::ToolCallDone.new(
+  item_id: "id",
+  call_id: "call_id",
+  name: "tool_name",
+  arguments: '{"complete":"args"}'
+)
+
+# Reasoning (if supported)
+Riffer::StreamEvents::ReasoningDelta.new("thinking...")
+Riffer::StreamEvents::ReasoningDone.new("complete reasoning")
+```
+
+## Error Handling
+
+Raise appropriate Riffer errors:
+
+```ruby
+def perform_generate_text(messages, model:, **options)
+  response = @client.generate(...)
+
+  if response.error?
+    raise Riffer::Error, "Provider error: #{response.error_message}"
+  end
+
+  # ...
+rescue MyProviderGem::AuthError => e
+  raise Riffer::ArgumentError, "Authentication failed: #{e.message}"
+end
+```
+
+## Complete Example
+
+```ruby
+# lib/riffer/providers/anthropic.rb
+
+class Riffer::Providers::Anthropic < Riffer::Providers::Base
+  def initialize(**options)
+    depends_on "anthropic"
+
+    api_key = options[:api_key] || ENV['ANTHROPIC_API_KEY']
+    @client = ::Anthropic::Client.new(api_key: api_key)
+  end
+
+  private
+
+  def perform_generate_text(messages, model:, tools: nil, **options)
+    system_message = extract_system(messages)
+    conversation = messages.reject { |m| m.is_a?(Riffer::Messages::System) }
+
+    params = {
+      model: model,
+      messages: convert_messages(conversation),
+      system: system_message,
+      max_tokens: options[:max_tokens] || 4096
+    }
+
+    if tools && !tools.empty?
+      params[:tools] = tools.map { |t| convert_tool(t) }
+    end
+
+    response = @client.messages.create(**params)
+    extract_assistant_message(response)
+  end
+
+  def perform_stream_text(messages, model:, tools: nil, **options)
+    Enumerator.new do |yielder|
+      # Similar implementation with streaming
+    end
+  end
+
+  def extract_system(messages)
+    system_msg = messages.find { |m| m.is_a?(Riffer::Messages::System) }
+    system_msg&.content
+  end
+
+  def convert_messages(messages)
+    messages.map do |msg|
+      case msg
+      when Riffer::Messages::User
+        {role: "user", content: msg.content}
+      when Riffer::Messages::Assistant
+        {role: "assistant", content: msg.content}
+      when Riffer::Messages::Tool
+        {role: "user", content: [{type: "tool_result", tool_use_id: msg.tool_call_id, content: msg.content}]}
+      end
+    end
+  end
+
+  def convert_tool(tool)
+    {
+      name: tool.name,
+      description: tool.description,
+      input_schema: tool.parameters_schema
+    }
+  end
+
+  def extract_assistant_message(response)
+    text = ""
+    tool_calls = []
+
+    response.content.each do |block|
+      case block.type
+      when "text"
+        text = block.text
+      when "tool_use"
+        tool_calls << {
+          id: block.id,
+          call_id: block.id,
+          name: block.name,
+          arguments: block.input.to_json
+        }
+      end
+    end
+
+    Riffer::Messages::Assistant.new(text, tool_calls: tool_calls)
+  end
+end
+```