riffer 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7a4f27800f9f5a266d408a1b8b8d6d96f6c59307b4761d34d3a1365b9b71bb8
-  data.tar.gz: 6719e5013f8d83c78f2647808dd0d27a024ec432085311af02b1dc7cfbdaacfb
+  metadata.gz: ae2818fb04f43e8b5bd3a4a2ecfc2302af15ac073985e08f3fd36c461bafdf8c
+  data.tar.gz: e5ec190ea0c927eb38604849798b44fc96a03ba80510376d1d0e2eb2f5138fd0
 SHA512:
-  metadata.gz: 24356e56e024eaf5223c91c97b72bf4e90a9dd74721d12dac6b5d0f294bea305914d6f074467e915dfd64adbf3eea5a07484147a394f51613f7fe16e828e4c36
-  data.tar.gz: 6c8b8d464d94b56f044196f81ec298b01824dea114aca266b82de020c82521ce975451c643c5307d532c23f6fb85e2d38f4931f931cf13dee5e54b53ba5e8211
+  metadata.gz: c841653977d2277537ae2930a874d32748f874a4995fa058fd2abdff798d70f99cecdc4e75058179194f7b78502e209c4c97d916b4f568cab5935b9f4d470e84
+  data.tar.gz: 383682e8b929bc8f164c9bce1ae0b6bbec9a6ea7a30a5282bde79becfe886b22e7177f45ac5421ec97aad7fdfd2adf0150d649d0791c14f931c59ab737b36940

data/.agents/architecture.md

@@ -4,7 +4,7 @@
 
 ### Agent (`lib/riffer/agent.rb`)
 
-Base class for AI agents. Subclass and use DSL methods `model` and `instructions` to configure. Orchestrates message flow, LLM calls, and tool execution via a generate/stream loop.
+Base class for AI agents. Subclass and use DSL methods `model`, `instructions`, and `structured_output` to configure. Orchestrates message flow, LLM calls, tool execution, and structured output parsing via a generate/stream loop.
 
 ```ruby
 class EchoAgent < Riffer::Agent
@@ -18,10 +18,13 @@ puts agent.generate('Hello world')
 
 ### Providers (`lib/riffer/providers/`)
 
-Adapters for LLM APIs. Each provider extends `Riffer::Providers::Base` and implements:
+Adapters for LLM APIs. The base class uses a template-method pattern — `generate_text` and `stream_text` orchestrate the flow, delegating to five hook methods each provider implements:
 
-- `perform_generate_text(messages, model:)` - returns `Riffer::Messages::Assistant`
-- `perform_stream_text(messages, model:)` - returns an `Enumerator` yielding stream events
+- `build_request_params(messages, model, options)` — convert messages, tools, and options into SDK params
+- `execute_generate(params)` — call the SDK and return the raw response
+- `execute_stream(params, yielder)` — call the streaming SDK, mapping events to the yielder
+- `extract_token_usage(response)` — pull token counts from the SDK response
+- `extract_assistant_message(response, token_usage)` — parse the SDK response into an `Assistant` message
 
 Providers are registered in `Riffer::Providers::Repository::REPO` with identifiers (e.g., `openai`, `amazon_bedrock`).
 
@@ -30,11 +33,13 @@ Providers are registered in `Riffer::Providers::Repository::REPO` with identifie
 Typed message objects that extend `Riffer::Messages::Base`:
 
 - `System` - system instructions
-- `User` - user input
+- `User` - user input (supports file attachments via `Riffer::FilePart`)
 - `Assistant` - AI responses
 - `Tool` - tool execution results
 
-The `Converter` module handles hash-to-object conversion.
+`Riffer::FilePart` represents file attachments (images and documents) that can be included with User messages. Supports file paths, URLs, and raw base64 data.
+
+The `Converter` module handles hash-to-object conversion, including file hash-to-`FilePart` conversion.
 
 ### StreamEvents (`lib/riffer/stream_events/`)
 
@@ -44,10 +49,27 @@ Structured events for streaming responses:
 - `TextDone` - completion signals
 - `ReasoningDelta` - reasoning process chunks
 - `ReasoningDone` - reasoning completion
+- `WebSearchStatus` - web search status updates
+- `WebSearchDone` - web search completion with query and sources
+- `Interrupt` - callback interrupted the agent loop
+
+### Stopping the Loop Early
+
+Two mechanisms can stop the agent loop before the LLM finishes naturally:
+
+**Guardrail tripwires** — declarative policy enforcement registered at class level. A `:before` guardrail can block the request before the LLM is called; an `:after` guardrail can block the response. Tripwires are not resumable — the caller must change the input and start over. `Response#blocked?` returns `true`.
+
+**Callback interrupts** — imperative flow control via `on_message` callbacks. Use `throw :riffer_interrupt` to pause the loop at any point. `Response#interrupted?` returns `true`. In streaming, yields an `Interrupt` event.
+
+### Resuming After an Interrupt
+
+`agent.resume` or `agent.resume_stream` continues an interrupted loop. Both accept `messages:` for cross-process resume from persisted data.
+
+On resume, `execute_pending_tool_calls` detects tool calls from the last assistant message that lack corresponding tool result messages and executes them before entering the LLM loop. This handles the case where an interrupt fired mid-way through tool execution.
 
 ## Key Patterns
 
-- Model strings use `provider/model` format (e.g., `openai/gpt-4`)
+- Model config accepts a `provider/model` string (e.g., `openai/gpt-4`) or a Proc/lambda that returns one
 - Configuration via `Riffer.configure { |c| c.openai.api_key = "..." }`
 - Providers use `depends_on` helper for runtime dependency checking
 - Zeitwerk for autoloading - file structure must match module/class names
@@ -55,6 +77,9 @@ Structured events for streaming responses:
 ## Project Structure
 
 ```
+examples/
+  evaluators/            # Reference evaluator implementations (copy-paste)
+  guardrails/            # Reference guardrail implementations (copy-paste)
 lib/
   riffer.rb              # Main entry point, uses Zeitwerk for autoloading
   riffer/
@@ -64,11 +89,17 @@ lib/
     agent.rb             # Agent class
     messages.rb          # Messages namespace/module
     providers.rb         # Providers namespace/module
+    param.rb             # Single parameter definition (shared by tools and structured output)
+    params.rb            # Parameter collection with DSL and validation
+    structured_output.rb # Structured output schema wrapper
     stream_events.rb     # Stream events namespace/module
+    structured_output/
+      result.rb          # Parse/validation result object
     helpers/
       class_name_converter.rb  # Class name conversion utilities
       dependencies.rb          # Dependency management
       validations.rb           # Validation helpers
+    file_part.rb         # File attachment (images and documents)
     messages/
       base.rb            # Base message class
       assistant.rb       # Assistant message
@@ -80,14 +111,18 @@ lib/
       base.rb            # Base provider class
       open_ai.rb         # OpenAI provider
       amazon_bedrock.rb  # Amazon Bedrock provider
+      anthropic.rb       # Anthropic provider
       repository.rb      # Provider registry
-      test.rb            # Test provider
+      mock.rb            # Mock provider
     stream_events/
       base.rb            # Base stream event
+      interrupt.rb       # Interrupt event
       text_delta.rb      # Text delta event
       text_done.rb       # Text done event
       reasoning_delta.rb # Reasoning delta event
       reasoning_done.rb  # Reasoning done event
+      web_search_status.rb # Web search status event
+      web_search_done.rb   # Web search done event
 test/
   test_helper.rb         # Minitest configuration with VCR
   riffer_test.rb         # Main module tests

data/.agents/providers.md

@@ -3,33 +3,185 @@
 ## Steps
 
 1. Create `lib/riffer/providers/your_provider.rb` extending `Riffer::Providers::Base`
-2. Implement required methods (see below)
+2. Implement the required hook methods (see below)
 3. Register in `Riffer::Providers::Repository::REPO`
 4. Add provider config to `Riffer::Config` if needed
 5. Create tests in `test/riffer/providers/your_provider_test.rb`
 
-## Required Methods
+## Architecture
+
+The base class uses the **template method** pattern. The public methods `generate_text` and `stream_text` orchestrate the flow, delegating to five hook methods that each provider implements:
+
+```
+generate_text
+  ├─ build_request_params
+  ├─ execute_generate
+  ├─ extract_token_usage
+  └─ extract_assistant_message
+
+stream_text
+  ├─ build_request_params
+  └─ execute_stream
+```
+
+## Required Hook Methods
 
 ```ruby
 # frozen_string_literal: true
+# rbs_inline: enabled
+
+class Riffer::Providers::YourProvider < Riffer::Providers::Base
+  def initialize(**options)
+    depends_on "your-sdk-gem"
+    @client = YourSDK::Client.new(**options)
+  end
+
+  private
+
+  # Convert messages, tools, and options into SDK-specific params.
+  # If supporting web search, extract `web_search` from options and convert
+  # it to a provider-native tool format (e.g., OpenAI's `web_search_preview`
+  # or Anthropic's `web_search_20250305` server tool).
+  #
+  #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def build_request_params(messages, model, options)
+    # Return a hash that can be passed to both execute_generate and execute_stream
+  end
 
-module Riffer
-  module Providers
-    class YourProvider < Base
-      # Returns Riffer::Messages::Assistant
-      def perform_generate_text(messages, model:)
-        # Implementation
-      end
-
-      # Returns Enumerator yielding stream events
-      def perform_stream_text(messages, model:)
-        # Implementation
-      end
+  # Call the SDK and return the raw response object.
+  #
+  #: (Hash[Symbol, untyped]) -> untyped
+  def execute_generate(params)
+    @client.create(**params)
+  end
+
+  # Call the streaming SDK, mapping provider events to Riffer stream events.
+  #
+  #: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
+  def execute_stream(params, yielder)
+    @client.stream(**params) do |event|
+      # Map SDK events to Riffer::StreamEvents::* and yield them
+      # yielder << Riffer::StreamEvents::TextDelta.new(event.text)
     end
   end
+
+  # Extract token usage from the SDK response.
+  #
+  #: (untyped) -> Riffer::TokenUsage?
+  def extract_token_usage(response)
+    usage = response.usage
+    return nil unless usage
+
+    Riffer::TokenUsage.new(
+      input_tokens: usage.input_tokens,
+      output_tokens: usage.output_tokens
+    )
+  end
+
+  # Parse the SDK response into an Assistant message.
+  #
+  #: (untyped, ?Riffer::TokenUsage?) -> Riffer::Messages::Assistant
+  def extract_assistant_message(response, token_usage = nil)
+    # Extract text and tool_calls from the response
+    Riffer::Messages::Assistant.new(text, tool_calls: tool_calls, token_usage: token_usage)
+  end
+end
+```
+
+## Structured Output
+
+When structured output is configured, the agent passes a `Riffer::StructuredOutput` instance via `options[:structured_output]`. Providers must extract it from options (and exclude it from the splat) and convert it to their SDK-specific format.
+
+### Extracting from options
+
+All providers follow the same pattern:
+
+```ruby
+def build_request_params(messages, model, options)
+  structured_output = options[:structured_output]
+
+  params = {
+    # ...
+    **options.except(:tools, :structured_output)
+  }
+
+  # Convert to provider-specific format (see below)
+end
+```
+
+### Provider-specific formats
+
+**OpenAI** — uses `params[:text][:format]`:
+
+```ruby
+if structured_output
+  params[:text] = {
+    format: {
+      type: "json_schema",
+      name: "response",
+      schema: structured_output.json_schema,
+      strict: true
+    }
+  }
 end
 ```
 
+**Anthropic** — uses `params[:output_config]`:
+
+```ruby
+if structured_output
+  params[:output_config] = {
+    format: {
+      type: "json_schema",
+      schema: structured_output.json_schema
+    }
+  }
+end
+```
+
+**Amazon Bedrock** — uses `params[:output_config][:text_format]` with stringified schema:
+
+```ruby
+if structured_output
+  params[:output_config] = {
+    text_format: {
+      type: "json_schema",
+      structure: {
+        json_schema: {
+          schema: structured_output.json_schema.to_json,
+          name: "response"
+        }
+      }
+    }
+  }
+end
+```
+
+### Key details
+
+- `structured_output.json_schema` returns a Hash with `type`, `properties`, `required`, and `additionalProperties` keys
+- Bedrock requires the schema as a JSON string (`.to_json`), others use the Hash directly
+- The agent handles parsing and validation of the response — providers only need to pass the schema to the SDK
+
+## File Handling
+
+User messages may include `Riffer::FilePart` objects in their `files` array. Each provider's `build_request_params` (or its message conversion helpers) must convert these to provider-specific content blocks:
+
+- **OpenAI**: `input_image` (URLs or data URIs) and `input_file` (data URIs)
+- **Anthropic**: `image` and `document` blocks with `url` or `base64` source
+- **Bedrock**: `image` and `document` blocks with `bytes` source (always base64, URLs are resolved)
+
+## Shared Utilities
+
+The base class provides `parse_tool_arguments` for converting tool call arguments from JSON strings to hashes:
+
+```ruby
+# Available in all providers via the base class
+parse_tool_arguments('{"key":"value"}')  # => {"key" => "value"}
+parse_tool_arguments({"key" => "value"}) # => {"key" => "value"}
+parse_tool_arguments(nil)                # => {}
+```
+
 ## Registration
 
 Add to `Riffer::Providers::Repository::REPO`:

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.13.0"
+  ".": "0.14.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0](https://github.com/janeapp/riffer/compare/riffer/v0.13.0...riffer/v0.14.0) (2026-02-24)
+
+
+### Features
+
+* add file attachment support for user messages ([#129](https://github.com/janeapp/riffer/issues/129)) ([0d08eb1](https://github.com/janeapp/riffer/commit/0d08eb140e4094a729b1da5e3fddb57b251bf6f3))
+* add max_steps option to Agent ([#121](https://github.com/janeapp/riffer/issues/121)) ([fbc0391](https://github.com/janeapp/riffer/commit/fbc0391d157db587c0293255587a70141a7b588f))
+* add structured output support for agents ([#128](https://github.com/janeapp/riffer/issues/128)) ([99be155](https://github.com/janeapp/riffer/commit/99be15567747427830fdb75b585715f013857f6f))
+* add web_search option for OpenAI and Anthropic providers ([#126](https://github.com/janeapp/riffer/issues/126)) ([7e7e793](https://github.com/janeapp/riffer/commit/7e7e793a4ff746d7238074a21b9cd62a846e7c99))
+* interruptible callbacks via throw/catch ([#119](https://github.com/janeapp/riffer/issues/119)) ([f5985e6](https://github.com/janeapp/riffer/commit/f5985e627737b28ebbf7ed7262e62496836acf1f))
+* replace eval prompt API with semantic fields ([#132](https://github.com/janeapp/riffer/issues/132)) ([5d99d5a](https://github.com/janeapp/riffer/commit/5d99d5af408e4e70ae66c975d1b40d60a209f5a6))
+* replace Profile/Metric eval system with EvaluatorRunner ([#138](https://github.com/janeapp/riffer/issues/138)) ([ebf2696](https://github.com/janeapp/riffer/commit/ebf2696dfce814be43278aa9857285c21b3894bf))
+* support dynamic model selection via lambda ([#127](https://github.com/janeapp/riffer/issues/127)) ([c59cf96](https://github.com/janeapp/riffer/commit/c59cf96efb5a4f5d0bc947441fa3aeeea3b4e5f3))
+
+
+### Bug Fixes
+
+* add --comment flag to claude code review prompt ([#122](https://github.com/janeapp/riffer/issues/122)) ([534bd59](https://github.com/janeapp/riffer/commit/534bd59c389233466824090b7bdfed976870d9f1))
+* add RBS annotations to web search constants and fix test provider docs ([#130](https://github.com/janeapp/riffer/issues/130)) ([7cebe05](https://github.com/janeapp/riffer/commit/7cebe0506eafaa35abe2de74997af479a3776a7d))
+* correct Amazon Bedrock model options to use Converse API structure ([#133](https://github.com/janeapp/riffer/issues/133)) ([3af4562](https://github.com/janeapp/riffer/commit/3af45620fc47d1b98961eb45d79a905a7d2cac82))
+* widen run_eval input type to accept String or messages array ([#124](https://github.com/janeapp/riffer/issues/124)) ([f96214c](https://github.com/janeapp/riffer/commit/f96214c5b602c3469edca2ac9d0b856d1e23c630))
+
 ## [0.13.0](https://github.com/janeapp/riffer/compare/riffer/v0.12.0...riffer/v0.13.0) (2026-02-12)
 
 

data/docs/01_OVERVIEW.md

@@ -37,13 +37,32 @@ end
 
 See [Tools](04_TOOLS.md) for details.
 
+### Structured Output
+
+Agents can return structured JSON responses that conform to a schema. The response is automatically parsed and validated:
+
+```ruby
+class SentimentAgent < Riffer::Agent
+  model 'openai/gpt-4o'
+  structured_output do
+    required :sentiment, String
+    required :score, Float
+  end
+end
+
+response = SentimentAgent.generate('Analyze: "I love this!"')
+response.structured_output  # => {sentiment: "positive", score: 0.95}
+```
+
+See the [structured output section in Agents](03_AGENTS.md#structured_output) for details.
+
 ### Provider
 
 Providers are adapters that connect to LLM services. Riffer supports:
 
 - **OpenAI** - GPT models via the OpenAI API
 - **Amazon Bedrock** - Claude and other models via AWS Bedrock
-- **Test** - Mock provider for testing
+- **Mock** - Mock provider for testing
 
 See [Providers](providers/01_PROVIDERS.md) for details.
 
@@ -66,6 +85,8 @@ When streaming responses, Riffer emits typed events:
 - `TextDone` - Complete text
 - `ToolCallDelta` - Incremental tool call arguments
 - `ToolCallDone` - Complete tool call
+- `WebSearchStatus` - Web search progress updates
+- `WebSearchDone` - Web search completion with sources
 
 See [Stream Events](06_STREAM_EVENTS.md) for details.