riffer 0.7.0 → 0.9.0

data/docs/04_TOOLS.md

@@ -0,0 +1,342 @@
+# 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")
+    text("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 and return a `Riffer::Tools::Response`:
+
+```ruby
+def call(context:, **kwargs)
+  # context - The tool_context passed to agent.generate()
+  # kwargs  - Validated parameters
+  #
+  # Must return a Riffer::Tools::Response
+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)
+    unless user_id
+      return error("No user ID provided")
+    end
+
+    orders = Order.where(user_id: user_id)
+    text(orders.map(&:to_s).join("\n"))
+  end
+end
+
+# Usage
+agent.generate("Show my orders", tool_context: {user_id: 123})
+```
+
+## Response Objects
+
+All tools must return a `Riffer::Tools::Response` object from their `call` method. Riffer::Tool provides shorthand methods for creating responses.
+
+### Success Responses
+
+Use `text` for string responses and `json` for structured data:
+
+```ruby
+def call(context:, query:)
+  results = Database.search(query)
+
+  if results.empty?
+    text("No results found for '#{query}'")
+  else
+    text(results.map { |r| "- #{r.title}: #{r.summary}" }.join("\n"))
+  end
+end
+```
+
+#### text
+
+Converts the result to a string via `to_s`:
+
+```ruby
+text("Hello, world!")
+# => content: "Hello, world!"
+
+text(42)
+# => content: "42"
+```
+
+#### json
+
+Converts the result to JSON via `to_json`:
+
+```ruby
+json({name: "Alice", age: 30})
+# => content: '{"name":"Alice","age":30}'
+
+json([1, 2, 3])
+# => content: '[1,2,3]'
+```
+
+### Error Responses
+
+Use `error(message, type:)` for errors:
+
+```ruby
+def call(context:, user_id:)
+  user = User.find_by(id: user_id)
+
+  unless user
+    return error("User not found", type: :not_found)
+  end
+
+  text("User: #{user.name}")
+end
+```
+
+The error type is any symbol that describes the error category:
+
+```ruby
+error("Invalid input", type: :validation_error)
+error("Service unavailable", type: :service_error)
+error("Rate limit exceeded", type: :rate_limit)
+```
+
+If no type is specified, it defaults to `:execution_error`.
+
+### Using Riffer::Tools::Response Directly
+
+The shorthand methods delegate to `Riffer::Tools::Response`. You can also use the class directly if preferred:
+
+```ruby
+Riffer::Tools::Response.text("Hello")
+Riffer::Tools::Response.json({data: [1, 2, 3]})
+Riffer::Tools::Response.error("Failed", type: :custom_error)
+```
+
+### Response Methods
+
+```ruby
+response = text("result")
+response.content        # => "result"
+response.success?       # => true
+response.error?         # => false
+response.error_message  # => nil
+response.error_type     # => nil
+
+error_response = error("failed", type: :not_found)
+error_response.content        # => "failed"
+error_response.success?       # => false
+error_response.error?         # => true
+error_response.error_message  # => "failed"
+error_response.error_type     # => :not_found
+```
+
+## 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:)
+    result = ExternalAPI.search(query)
+    text(result)
+  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 with error type `:validation_error`.
+
+## 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 can be returned explicitly using `error`:
+
+```ruby
+def call(context:, query:)
+  results = ExternalAPI.search(query)
+  json(results)
+rescue RateLimitError => e
+  error("API rate limit exceeded, please try again later", type: :rate_limit)
+rescue => e
+  error("Search failed: #{e.message}")
+end
+```
+
+Unhandled exceptions are caught by Riffer and converted to error responses with type `:execution_error`. However, it's recommended to handle expected errors explicitly for better error messages.
+
+The LLM receives the error message and can decide how to respond (retry, apologize, ask for different input, etc.).

data/docs/05_MESSAGES.md

@@ -0,0 +1,173 @@
+# Messages
+
+Messages represent the conversation between users and the assistant. Riffer uses strongly-typed message objects to ensure consistency and type safety.
+
+## Message Types
+
+### System
+
+System messages provide instructions to the LLM:
+
+```ruby
+msg = Riffer::Messages::System.new("You are a helpful assistant.")
+msg.role     # => :system
+msg.content  # => "You are a helpful assistant."
+msg.to_h     # => {role: :system, content: "You are a helpful assistant."}
+```
+
+System messages are typically set via agent `instructions` and automatically prepended to conversations.
+
+### User
+
+User messages represent input from the user:
+
+```ruby
+msg = Riffer::Messages::User.new("Hello, how are you?")
+msg.role     # => :user
+msg.content  # => "Hello, how are you?"
+msg.to_h     # => {role: :user, content: "Hello, how are you?"}
+```
+
+### Assistant
+
+Assistant messages represent LLM responses, potentially including tool calls:
+
+```ruby
+# Text-only response
+msg = Riffer::Messages::Assistant.new("I'm doing well, thank you!")
+msg.role        # => :assistant
+msg.content     # => "I'm doing well, thank you!"
+msg.tool_calls  # => []
+
+# Response with tool calls
+msg = Riffer::Messages::Assistant.new("", tool_calls: [
+  {id: "call_123", call_id: "call_123", name: "weather_tool", arguments: '{"city":"Tokyo"}'}
+])
+msg.tool_calls  # => [{id: "call_123", ...}]
+msg.to_h        # => {role: "assistant", content: "", tool_calls: [...]}
+```
+
+### Tool
+
+Tool messages contain the results of tool executions:
+
+```ruby
+msg = Riffer::Messages::Tool.new(
+  "The weather in Tokyo is 22C and sunny.",
+  tool_call_id: "call_123",
+  name: "weather_tool"
+)
+msg.role          # => :tool
+msg.content       # => "The weather in Tokyo is 22C and sunny."
+msg.tool_call_id  # => "call_123"
+msg.name          # => "weather_tool"
+msg.error?        # => false
+
+# Error result
+msg = Riffer::Messages::Tool.new(
+  "API rate limit exceeded",
+  tool_call_id: "call_123",
+  name: "weather_tool",
+  error: "API rate limit exceeded",
+  error_type: :execution_error
+)
+msg.error?      # => true
+msg.error       # => "API rate limit exceeded"
+msg.error_type  # => :execution_error
+```
+
+## Using Messages with Agents
+
+### String Prompts
+
+The simplest way to interact with an agent:
+
+```ruby
+agent = MyAgent.new
+response = agent.generate("Hello!")
+```
+
+This creates a `User` message internally.
+
+### Message Arrays
+
+For multi-turn conversations, pass an array of messages:
+
+```ruby
+messages = [
+  {role: :user, content: "What's the weather?"},
+  {role: :assistant, content: "I'll check that for you."},
+  {role: :user, content: "Thanks, I meant in Tokyo specifically."}
+]
+
+response = agent.generate(messages)
+```
+
+Messages can be hashes or `Riffer::Messages::Base` objects:
+
+```ruby
+messages = [
+  Riffer::Messages::User.new("Hello"),
+  Riffer::Messages::Assistant.new("Hi there!"),
+  Riffer::Messages::User.new("How are you?")
+]
+
+response = agent.generate(messages)
+```
+
+### Accessing Message History
+
+After calling `generate` or `stream`, access the full conversation:
+
+```ruby
+agent = MyAgent.new
+agent.generate("Hello!")
+
+agent.messages.each do |msg|
+  puts "[#{msg.role}] #{msg.content}"
+end
+# [system] You are a helpful assistant.
+# [user] Hello!
+# [assistant] Hi there! How can I help you today?
+```
+
+## Tool Call Structure
+
+Tool calls in assistant messages have this structure:
+
+```ruby
+{
+  id: "item_123",       # Item identifier
+  call_id: "call_456",  # Call identifier for response matching
+  name: "weather_tool", # Tool name
+  arguments: '{"city":"Tokyo"}'  # JSON string of arguments
+}
+```
+
+When creating tool result messages, use the `id` as `tool_call_id`.
+
+## Message Emission
+
+Agents can emit messages as they're added during generation via the `on_message` callback. This is useful for persistence or real-time logging. Only agent-generated messages (Assistant, Tool) are emitted—not inputs (System, User).
+
+See [Agents - on_message](03_AGENTS.md#on_message) for details.
+
+## Base Class
+
+All messages inherit from `Riffer::Messages::Base`:
+
+```ruby
+class Riffer::Messages::Base
+  attr_reader :content
+
+  def role
+    raise NotImplementedError
+  end
+
+  def to_h
+    {role: role, content: content}
+  end
+end
+```
+
+Subclasses implement `role` and optionally extend `to_h` with additional fields.

data/docs/06_STREAM_EVENTS.md

@@ -0,0 +1,191 @@
+# Stream Events
+
+When streaming responses, Riffer emits typed events that represent incremental updates from the LLM.
+
+## Using Streaming
+
+Use `stream` instead of `generate` to receive events as they arrive:
+
+```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[Complete]"
+  when Riffer::StreamEvents::ToolCallDelta
+    # Tool call being built
+  when Riffer::StreamEvents::ToolCallDone
+    puts "[Tool: #{event.name}]"
+  end
+end
+```
+
+## Event Types
+
+### TextDelta
+
+Emitted when incremental text content is received:
+
+```ruby
+event = Riffer::StreamEvents::TextDelta.new("Hello ")
+event.role     # => "assistant"
+event.content  # => "Hello "
+event.to_h     # => {role: "assistant", content: "Hello "}
+```
+
+Use this to display text in real-time as it streams.
+
+### TextDone
+
+Emitted when text generation is complete:
+
+```ruby
+event = Riffer::StreamEvents::TextDone.new("Hello, how can I help you?")
+event.role     # => "assistant"
+event.content  # => "Hello, how can I help you?"
+event.to_h     # => {role: "assistant", content: "Hello, how can I help you?"}
+```
+
+Contains the complete final text.
+
+### ToolCallDelta
+
+Emitted when tool call arguments are being streamed:
+
+```ruby
+event = Riffer::StreamEvents::ToolCallDelta.new(
+  item_id: "item_123",
+  name: "weather_tool",
+  arguments_delta: '{"city":'
+)
+event.role             # => "assistant"
+event.item_id          # => "item_123"
+event.name             # => "weather_tool"
+event.arguments_delta  # => '{"city":'
+```
+
+The `name` may only be present in the first delta. Accumulate `arguments_delta` to build the complete arguments.
+
+### ToolCallDone
+
+Emitted when a tool call is complete:
+
+```ruby
+event = Riffer::StreamEvents::ToolCallDone.new(
+  item_id: "item_123",
+  call_id: "call_456",
+  name: "weather_tool",
+  arguments: '{"city":"Tokyo"}'
+)
+event.role       # => "assistant"
+event.item_id    # => "item_123"
+event.call_id    # => "call_456"
+event.name       # => "weather_tool"
+event.arguments  # => '{"city":"Tokyo"}'
+```
+
+Contains the complete tool call information.
+
+### ReasoningDelta
+
+Emitted when reasoning/thinking content is streamed (OpenAI with reasoning enabled):
+
+```ruby
+event = Riffer::StreamEvents::ReasoningDelta.new("Let me think about ")
+event.role     # => "assistant"
+event.content  # => "Let me think about "
+```
+
+### ReasoningDone
+
+Emitted when reasoning is complete:
+
+```ruby
+event = Riffer::StreamEvents::ReasoningDone.new("Let me think about this step by step...")
+event.role     # => "assistant"
+event.content  # => "Let me think about this step by step..."
+```
+
+## Streaming with Tools
+
+When an agent uses tools during streaming, the flow is:
+
+1. Text events stream in (`TextDelta`, `TextDone`)
+2. If tool calls are present: `ToolCallDelta` events, then `ToolCallDone`
+3. Agent executes tools internally
+4. Agent sends results back to LLM
+5. More text events stream in
+6. Repeat until no more tool calls
+
+```ruby
+agent.stream("What's the weather in Tokyo?").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+  when Riffer::StreamEvents::ToolCallDone
+    puts "\n[Calling #{event.name}...]"
+  when Riffer::StreamEvents::TextDone
+    puts "\n"
+  end
+end
+```
+
+## Complete Example
+
+```ruby
+class WeatherAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  instructions 'You are a weather assistant.'
+  uses_tools [WeatherTool]
+end
+
+agent = WeatherAgent.new
+text_buffer = ""
+
+agent.stream("What's the weather in Tokyo and New York?").each do |event|
+  case event
+  when Riffer::StreamEvents::TextDelta
+    print event.content
+    text_buffer += event.content
+
+  when Riffer::StreamEvents::TextDone
+    # Final text available
+    puts "\n---"
+    puts "Complete response: #{event.content}"
+
+  when Riffer::StreamEvents::ToolCallDelta
+    # Could show "typing..." indicator
+
+  when Riffer::StreamEvents::ToolCallDone
+    puts "\n[Tool: #{event.name}(#{event.arguments})]"
+
+  when Riffer::StreamEvents::ReasoningDelta
+    # Show thinking process if desired
+    print "[thinking] #{event.content}"
+
+  when Riffer::StreamEvents::ReasoningDone
+    puts "\n[reasoning complete]"
+  end
+end
+```
+
+## Base Class
+
+All events inherit from `Riffer::StreamEvents::Base`:
+
+```ruby
+class Riffer::StreamEvents::Base
+  attr_reader :role
+
+  def initialize(role: "assistant")
+    @role = role
+  end
+
+  def to_h
+    raise NotImplementedError
+  end
+end
+```