riffer 0.7.0 → 0.8.0

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

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