riffer 0.6.1 → 0.8.0

data/docs/02_GETTING_STARTED.md

@@ -0,0 +1,128 @@
+# Getting Started
+
+This guide walks you through installing Riffer and creating your first AI agent.
+
+## Installation
+
+Add Riffer to your Gemfile:
+
+```ruby
+gem 'riffer'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install riffer
+```
+
+## Provider Setup
+
+Riffer requires an LLM provider. Install the provider gem for your chosen service:
+
+### OpenAI
+
+```ruby
+gem 'openai'
+```
+
+Configure your API key:
+
+```ruby
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+```
+
+### Amazon Bedrock
+
+```ruby
+gem 'aws-sdk-bedrockruntime'
+```
+
+Configure your credentials:
+
+```ruby
+Riffer.configure do |config|
+  config.amazon_bedrock.region = 'us-east-1'
+  # Optional: Use bearer token auth instead of IAM
+  config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
+end
+```
+
+## Creating Your First Agent
+
+Define an agent by subclassing `Riffer::Agent`:
+
+```ruby
+require 'riffer'
+
+Riffer.configure do |config|
+  config.openai.api_key = ENV['OPENAI_API_KEY']
+end
+
+class GreetingAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a friendly assistant. Greet the user warmly.'
+end
+
+agent = GreetingAgent.new
+response = agent.generate('Hello!')
+puts response
+# => "Hello! It's wonderful to meet you..."
+```
+
+## Streaming Responses
+
+Use `stream` for real-time output:
+
+```ruby
+agent = GreetingAgent.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[Done]"
+  end
+end
+```
+
+## Adding Tools
+
+Tools let agents interact with external systems:
+
+```ruby
+class TimeTool < Riffer::Tool
+  description "Gets the current time"
+
+  def call(context:)
+    Time.now.strftime('%Y-%m-%d %H:%M:%S')
+  end
+end
+
+class TimeAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You can tell the user the current time.'
+  uses_tools [TimeTool]
+end
+
+agent = TimeAgent.new
+puts agent.generate("What time is it?")
+# => "The current time is 2024-01-15 14:30:00."
+```
+
+## Next Steps
+
+- [Agents](03_AGENTS.md) - Agent configuration options
+- [Tools](04_TOOLS.md) - Creating tools with parameters
+- [Messages](05_MESSAGES.md) - Message types and history
+- [Stream Events](06_STREAM_EVENTS.md) - Streaming event types
+- [Providers](providers/01_PROVIDERS.md) - Provider-specific guides

data/docs/03_AGENTS.md

@@ -0,0 +1,226 @@
+# Agents
+
+Agents are the central orchestrator in Riffer. They manage the conversation flow, call LLM providers, and handle tool execution.
+
+## Defining an Agent
+
+Create an agent by subclassing `Riffer::Agent`:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a helpful assistant.'
+end
+```
+
+## Configuration Methods
+
+### model
+
+Sets the provider and model in `provider/model` format:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'           # OpenAI
+  # or
+  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'  # Bedrock
+  # or
+  model 'test/any'                # Test provider
+end
+```
+
+### instructions
+
+Sets system instructions for the agent:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are an expert Ruby programmer. Provide concise answers.'
+end
+```
+
+### identifier
+
+Sets a custom identifier (defaults to snake_case class name):
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  identifier 'custom_agent_name'
+end
+
+MyAgent.identifier  # => "custom_agent_name"
+```
+
+### uses_tools
+
+Registers tools the agent can use:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  uses_tools [WeatherTool, TimeTool]
+end
+```
+
+Tools can also be resolved dynamically with a lambda:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+
+  uses_tools ->(context) {
+    tools = [PublicTool]
+    tools << AdminTool if context&.dig(:user)&.admin?
+    tools
+  }
+end
+```
+
+### provider_options
+
+Passes options to the provider client:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
+end
+```
+
+### model_options
+
+Passes options to each LLM request:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  model_options reasoning: 'medium', temperature: 0.7
+end
+```
+
+## Instance Methods
+
+### generate
+
+Generates a response synchronously:
+
+```ruby
+agent = MyAgent.new
+
+# With a string prompt
+response = agent.generate('Hello')
+
+# With message objects/hashes
+response = agent.generate([
+  {role: 'user', content: 'Hello'},
+  {role: 'assistant', content: 'Hi there!'},
+  {role: 'user', content: 'How are you?'}
+])
+
+# With tool context
+response = agent.generate('Look up my orders', tool_context: {user_id: 123})
+```
+
+### stream
+
+Streams a response as an Enumerator:
+
+```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"
+  when Riffer::StreamEvents::ToolCallDone
+    puts "[Tool: #{event.name}]"
+  end
+end
+```
+
+### messages
+
+Access the message history after a generate/stream call:
+
+```ruby
+agent = MyAgent.new
+agent.generate('Hello')
+
+agent.messages.each do |msg|
+  puts "#{msg.role}: #{msg.content}"
+end
+```
+
+### on_message
+
+Registers a callback to receive messages as they're added during generation:
+
+```ruby
+agent.on_message do |message|
+  case message.role
+  when :assistant
+    puts "[Assistant] #{message.content}"
+  when :tool
+    puts "[Tool:#{message.name}] #{message.content}"
+  end
+end
+```
+
+Multiple callbacks can be registered. Returns `self` for method chaining:
+
+```ruby
+agent
+  .on_message { |msg| persist_message(msg) }
+  .on_message { |msg| log_message(msg) }
+  .generate('Hello')
+```
+
+Works with both `generate` and `stream`. Only emits agent-generated messages (Assistant, Tool), not inputs (System, User).
+
+## Class Methods
+
+### find
+
+Find an agent class by identifier:
+
+```ruby
+agent_class = Riffer::Agent.find('my_agent')
+agent = agent_class.new
+```
+
+### all
+
+List all agent subclasses:
+
+```ruby
+Riffer::Agent.all.each do |agent_class|
+  puts agent_class.identifier
+end
+```
+
+## Tool Execution Flow
+
+When an agent receives a response with tool calls:
+
+1. Agent detects `tool_calls` in the assistant message
+2. For each tool call:
+   - Finds the matching tool class
+   - Validates arguments against the tool's parameter schema
+   - Calls the tool's `call` method with `context` and arguments
+   - Creates a Tool message with the result
+3. Sends the updated message history back to the LLM
+4. Repeats until no more tool calls
+
+## Error Handling
+
+Tool execution errors are captured and sent back to the LLM:
+
+- `unknown_tool` - Tool not found in registered tools
+- `validation_error` - Arguments failed validation
+- `execution_error` - Tool raised an exception
+
+The LLM can use this information to retry or respond appropriately.

data/docs/04_TOOLS.md

@@ -0,0 +1,251 @@
+# Tools
+
+Tools are callable functions that agents can invoke to interact with external systems, fetch data, or perform actions.
+
+## Defining a Tool
+
+Create a tool by subclassing `Riffer::Tool`:
+
+```ruby
+class WeatherTool < Riffer::Tool
+  description "Gets the current weather for a city"
+
+  params do
+    required :city, String, description: "The city name"
+    optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
+  end
+
+  def call(context:, city:, units: nil)
+    weather = WeatherAPI.fetch(city, units: units || "celsius")
+    "The weather in #{city} is #{weather.temperature} #{units}."
+  end
+end
+```
+
+## Configuration Methods
+
+### description
+
+Sets a description that helps the LLM understand when to use the tool:
+
+```ruby
+class SearchTool < Riffer::Tool
+  description "Searches the knowledge base for relevant information"
+end
+```
+
+### identifier / name
+
+Sets a custom identifier (defaults to snake_case class name):
+
+```ruby
+class SearchTool < Riffer::Tool
+  identifier 'kb_search'
+end
+
+SearchTool.identifier  # => "kb_search"
+SearchTool.name        # => "kb_search" (alias)
+```
+
+### params
+
+Defines the tool's parameters using a DSL:
+
+```ruby
+class CreateOrderTool < Riffer::Tool
+  params do
+    required :product_id, Integer, description: "The product ID"
+    required :quantity, Integer, description: "Number of items"
+    optional :notes, String, description: "Order notes"
+    optional :priority, String, default: "normal", enum: ["low", "normal", "high"]
+  end
+end
+```
+
+## Parameter DSL
+
+### required
+
+Defines a required parameter:
+
+```ruby
+params do
+  required :name, String, description: "The user's name"
+  required :age, Integer, description: "The user's age"
+end
+```
+
+Options:
+
+- `description` - Human-readable description for the LLM
+- `enum` - Array of allowed values
+
+### optional
+
+Defines an optional parameter:
+
+```ruby
+params do
+  optional :limit, Integer, default: 10, description: "Max results"
+  optional :format, String, enum: ["json", "xml"], description: "Output format"
+end
+```
+
+Options:
+
+- `description` - Human-readable description
+- `default` - Default value when not provided
+- `enum` - Array of allowed values
+
+### Supported Types
+
+| Ruby Type                  | JSON Schema Type |
+| -------------------------- | ---------------- |
+| `String`                   | `string`         |
+| `Integer`                  | `integer`        |
+| `Float`                    | `number`         |
+| `TrueClass` / `FalseClass` | `boolean`        |
+| `Array`                    | `array`          |
+| `Hash`                     | `object`         |
+
+## The call Method
+
+Every tool must implement the `call` method:
+
+```ruby
+def call(context:, **kwargs)
+  # context - The tool_context passed to agent.generate()
+  # kwargs  - Validated parameters
+end
+```
+
+### Accessing Context
+
+The `context` argument receives whatever was passed to `tool_context`:
+
+```ruby
+class UserOrdersTool < Riffer::Tool
+  description "Gets the current user's orders"
+
+  def call(context:)
+    user_id = context&.dig(:user_id)
+    return "No user ID provided" unless user_id
+
+    orders = Order.where(user_id: user_id)
+    orders.map(&:to_s).join("\n")
+  end
+end
+
+# Usage
+agent.generate("Show my orders", tool_context: {user_id: 123})
+```
+
+### Return Values
+
+Return a string that will be sent back to the LLM:
+
+```ruby
+def call(context:, query:)
+  results = Database.search(query)
+
+  if results.empty?
+    "No results found for '#{query}'"
+  else
+    results.map { |r| "- #{r.title}: #{r.summary}" }.join("\n")
+  end
+end
+```
+
+## Timeout Configuration
+
+Configure timeouts to prevent tools from running indefinitely. The default timeout is 10 seconds.
+
+```ruby
+class SlowExternalApiTool < Riffer::Tool
+  description "Calls a slow external API"
+  timeout 30  # 30 seconds
+
+  def call(context:, query:)
+    ExternalAPI.search(query)
+  end
+end
+```
+
+When a tool times out, the error is reported to the LLM with error type `:timeout_error`, allowing it to respond appropriately (e.g., suggest retrying or using a different approach).
+
+## Validation
+
+Arguments are automatically validated before `call` is invoked:
+
+- Required parameters must be present
+- Types must match the schema
+- Enum values must be in the allowed list
+
+Validation errors are captured and sent back to the LLM as tool results.
+
+## JSON Schema Generation
+
+Riffer automatically generates JSON Schema for each tool:
+
+```ruby
+WeatherTool.parameters_schema
+# => {
+#   type: "object",
+#   properties: {
+#     "city" => {type: "string", description: "The city name"},
+#     "units" => {type: "string", enum: ["celsius", "fahrenheit"]}
+#   },
+#   required: ["city"],
+#   additionalProperties: false
+# }
+```
+
+## Registering Tools with Agents
+
+### Static Registration
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  uses_tools [WeatherTool, SearchTool]
+end
+```
+
+### Dynamic Registration
+
+Use a lambda for context-aware tool resolution:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+
+  uses_tools ->(context) {
+    tools = [PublicSearchTool]
+
+    if context&.dig(:user)&.premium?
+      tools << PremiumAnalyticsTool
+    end
+
+    if context&.dig(:user)&.admin?
+      tools << AdminTool
+    end
+
+    tools
+  }
+end
+```
+
+## Error Handling
+
+Errors in tools are captured and reported back to the LLM:
+
+```ruby
+def call(context:, query:)
+  raise "API rate limit exceeded"
+rescue => e
+  # Error is caught by Riffer and sent as tool result:
+  # "Error executing tool: API rate limit exceeded"
+end
+```
+
+The LLM can then decide how to respond (retry, apologize, ask for different input, etc.).