riffer 0.6.1 → 0.8.0

data/docs_providers/01_PROVIDERS.md

@@ -0,0 +1,168 @@
+# Providers Overview
+
+Providers are adapters that connect Riffer to LLM services. They implement a common interface for text generation and streaming.
+
+## Available Providers
+
+| Provider       | Identifier       | Gem Required             |
+| -------------- | ---------------- | ------------------------ |
+| OpenAI         | `openai`         | `openai`                 |
+| Amazon Bedrock | `amazon_bedrock` | `aws-sdk-bedrockruntime` |
+| Anthropic      | `anthropic`      | `anthropic`              |
+| Test           | `test`           | None                     |
+
+## Model String Format
+
+Agents specify providers using the `provider/model` format:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'              # OpenAI
+  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'  # Bedrock
+  model 'anthropic/claude-3-5-sonnet-20241022'  # Anthropic
+  model 'test/any'                   # Test provider
+end
+```
+
+## Provider Interface
+
+All providers inherit from `Riffer::Providers::Base` and implement:
+
+### generate_text
+
+Generates a response synchronously:
+
+```ruby
+provider = Riffer::Providers::OpenAI.new(api_key: "...")
+
+response = provider.generate_text(
+  prompt: "Hello!",
+  model: "gpt-4o"
+)
+# => Riffer::Messages::Assistant
+
+# Or with messages
+response = provider.generate_text(
+  messages: [Riffer::Messages::User.new("Hello!")],
+  model: "gpt-4o"
+)
+```
+
+### stream_text
+
+Streams a response as an Enumerator:
+
+```ruby
+provider.stream_text(prompt: "Tell me a story", model: "gpt-4o").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  end
+end
+```
+
+## Method Parameters
+
+| Parameter   | Description                                               |
+| ----------- | --------------------------------------------------------- |
+| `prompt`    | String prompt (required if `messages` not provided)       |
+| `system`    | Optional system message string                            |
+| `messages`  | Array of message objects/hashes (alternative to `prompt`) |
+| `model`     | Model name string                                         |
+| `tools`     | Array of Tool classes                                     |
+| `**options` | Provider-specific options                                 |
+
+You must provide either `prompt` or `messages`, but not both.
+
+## Using Providers Directly
+
+While agents abstract provider usage, you can use providers directly:
+
+```ruby
+require 'riffer'
+
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+
+provider = Riffer::Providers::OpenAI.new
+
+# Simple prompt
+response = provider.generate_text(
+  prompt: "What is Ruby?",
+  model: "gpt-4o"
+)
+puts response.content
+
+# With system message
+response = provider.generate_text(
+  prompt: "Explain recursion",
+  system: "You are a programming tutor. Use simple language.",
+  model: "gpt-4o"
+)
+
+# With message history
+messages = [
+  Riffer::Messages::System.new("You are helpful."),
+  Riffer::Messages::User.new("Hi!"),
+  Riffer::Messages::Assistant.new("Hello!"),
+  Riffer::Messages::User.new("How are you?")
+]
+
+response = provider.generate_text(
+  messages: messages,
+  model: "gpt-4o"
+)
+```
+
+## Tool Support
+
+Providers convert tools to their native format:
+
+```ruby
+class WeatherTool < Riffer::Tool
+  description "Gets weather"
+  params do
+    required :city, String
+  end
+  def call(context:, city:)
+    "Sunny in #{city}"
+  end
+end
+
+response = provider.generate_text(
+  prompt: "What's the weather in Tokyo?",
+  model: "gpt-4o",
+  tools: [WeatherTool]
+)
+
+if response.tool_calls.any?
+  # Handle tool calls
+end
+```
+
+## Provider Registry
+
+Riffer uses a registry to find providers by identifier:
+
+```ruby
+Riffer::Providers::Repository.find(:openai)
+# => Riffer::Providers::OpenAI
+
+Riffer::Providers::Repository.find(:amazon_bedrock)
+# => Riffer::Providers::AmazonBedrock
+
+Riffer::Providers::Repository.find(:anthropic)
+# => Riffer::Providers::Anthropic
+
+Riffer::Providers::Repository.find(:test)
+# => Riffer::Providers::Test
+```
+
+## Provider-Specific Guides
+
+- [Amazon Bedrock](02_AMAZON_BEDROCK.md) - Claude and other models via AWS
+- [Anthropic](03_ANTHROPIC.md) - Claude models via Anthropic API
+- [OpenAI](04_OPENAI.md) - GPT models
+- [Test](05_TEST_PROVIDER.md) - Mock provider for testing
+- [Custom Providers](06_CUSTOM_PROVIDERS.md) - Creating your own provider

data/docs_providers/02_AMAZON_BEDROCK.md

@@ -0,0 +1,196 @@
+# Amazon Bedrock Provider
+
+The Amazon Bedrock provider connects to AWS Bedrock for Claude and other foundation models.
+
+## Installation
+
+Add the AWS SDK gem to your Gemfile:
+
+```ruby
+gem 'aws-sdk-bedrockruntime'
+```
+
+## Configuration
+
+### IAM Authentication (Recommended)
+
+Configure your AWS credentials using standard AWS methods (environment variables, IAM roles, etc.):
+
+```ruby
+Riffer.configure do |config|
+  config.amazon_bedrock.region = 'us-east-1'
+end
+```
+
+### Bearer Token Authentication
+
+For API token authentication:
+
+```ruby
+Riffer.configure do |config|
+  config.amazon_bedrock.region = 'us-east-1'
+  config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
+end
+```
+
+Or per-agent:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'
+  provider_options region: 'us-west-2', api_token: ENV['BEDROCK_API_TOKEN']
+end
+```
+
+## Supported Models
+
+Use Bedrock model IDs in the `amazon_bedrock/model` format:
+
+```ruby
+# Claude models
+model 'amazon_bedrock/anthropic.claude-3-opus-20240229-v1:0'
+model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'
+model 'amazon_bedrock/anthropic.claude-3-haiku-20240307-v1:0'
+
+# Other foundation models available in Bedrock
+model 'amazon_bedrock/amazon.titan-text-express-v1'
+```
+
+## 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
+```
+
+## Example
+
+```ruby
+Riffer.configure do |config|
+  config.amazon_bedrock.region = 'us-east-1'
+end
+
+class AssistantAgent < Riffer::Agent
+  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'
+  instructions 'You are a helpful assistant.'
+  model_options temperature: 0.7, max_tokens: 4096
+end
+
+agent = AssistantAgent.new
+puts agent.generate("Explain cloud computing")
+```
+
+## Streaming
+
+```ruby
+agent.stream("Tell me about AWS services").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::TextDone
+    puts "\n[Complete]"
+  when Riffer::StreamEvents::ToolCallDone
+    puts "[Tool: #{event.name}]"
+  end
+end
+```
+
+## Tool Calling
+
+Bedrock provider converts tools to the Bedrock tool_config format:
+
+```ruby
+class S3ListTool < Riffer::Tool
+  description "Lists objects in an S3 bucket"
+
+  params do
+    required :bucket, String, description: "The S3 bucket name"
+    optional :prefix, String, description: "Object prefix filter"
+  end
+
+  def call(context:, bucket:, prefix: nil)
+    # Implementation
+    "Found 10 objects in #{bucket}"
+  end
+end
+
+class AWSAgent < Riffer::Agent
+  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'
+  uses_tools [S3ListTool]
+end
+```
+
+## Message Format
+
+The provider converts Riffer messages to Bedrock format:
+
+| Riffer Message | Bedrock Format                                  |
+| -------------- | ----------------------------------------------- |
+| `System`       | Added to `system` array as `{text: ...}`        |
+| `User`         | `{role: "user", content: [{text: ...}]}`        |
+| `Assistant`    | `{role: "assistant", content: [...]}`           |
+| `Tool`         | `{role: "user", content: [{tool_result: ...}]}` |
+
+## Direct Provider Usage
+
+```ruby
+provider = Riffer::Providers::AmazonBedrock.new(
+  region: 'us-east-1',
+  api_token: ENV['BEDROCK_API_TOKEN']  # Optional
+)
+
+response = provider.generate_text(
+  prompt: "Hello!",
+  model: "anthropic.claude-3-sonnet-20240229-v1:0",
+  temperature: 0.7
+)
+
+puts response.content
+```
+
+## AWS IAM Permissions
+
+Ensure your IAM role/user has the following permissions:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "bedrock:InvokeModel",
+        "bedrock:InvokeModelWithResponseStream"
+      ],
+      "Resource": "arn:aws:bedrock:*::foundation-model/*"
+    }
+  ]
+}
+```

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