riffer 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09506e8a2dfa346e49231fa598f1e899066a5597ddd5b6738758ca49594ca7c2'
-  data.tar.gz: 684dc3caf2f6a59d052adb51a5c33bdf0a5542a2a375f188a1bc0a600a7df5ef
+  metadata.gz: 8975a79d79a073d1bca29cd43216049766975f010b74dbc6ba1dbaaf22f69982
+  data.tar.gz: 5473e7c42541581bf7ad3c2efd046a3f3e76201e8b0c1a9a5ef324cc8175ae47
 SHA512:
-  metadata.gz: 2b1c4119f8afac1367aac6a7d9caddd656a598dab1ad44c921802864e73815d19c3a4f96e554483d9062c9e87864bd870e8af260b9d7f5922331bdcc714ccb52
-  data.tar.gz: 5f8387e02a6b2638550e59265980c8de6ce9422b77f905dcc019360e039d59ffb5b8d76310ba90819f7f7b51a5af34588b0de40782255c57215d4bf32ca862c8
+  metadata.gz: a331b45d49617ffaa73b65df988d2b018fcc214c25480880bb9b420ac3415a5abf5a4703e2e1568d3982c7bebad77a3710b8d1f04a83b0f063117e35298bc485
+  data.tar.gz: 3ed3b7446ce0385cf0a70a795ac7c00c27dc786a815b66bf77fe3927e4cb9bbae806342835eeb0759a5b7dcf8eb3b04df8fad249a69040e8b7a48a88da7435fe

data/.agents/providers.md

@@ -3,7 +3,7 @@
 ## Steps
 
 1. Create `lib/riffer/providers/your_provider.rb` extending `Riffer::Providers::Base`
-2. Implement the required hook methods (see below)
+2. Implement the required hook methods (see [Custom Providers](../docs/providers/07_CUSTOM_PROVIDERS.md) for the full API)
 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`
@@ -25,181 +25,6 @@ stream_text
   └─ 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
-
-  # 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
-
-  # Extract text content from the SDK response.
-  #
-  #: (untyped) -> String
-  def extract_content(response)
-    # Return the text content from the response
-  end
-
-  # Extract tool calls from the SDK response.
-  #
-  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
-  def extract_tool_calls(response)
-    # Return an array of ToolCall structs
-  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
-```
-
-### Strict schema
-
-All providers apply `strict_schema` (defined in `Providers::Base`) to schemas sent to LLMs — both structured output and tool parameters. This transformation:
-
-- Moves all properties into `required`
-- Makes originally-optional properties nullable (`[type, "null"]`)
-- Recurses into nested objects and array items
-
-This ensures all providers return proper `null` for optional fields instead of empty strings or garbage.
-
-### Provider-specific formats
-
-**OpenAI** — uses `params[:text][:format]` with `strict: true`:
-
-```ruby
-if structured_output
-  params[:text] = {
-    format: {
-      type: "json_schema",
-      name: "response",
-      schema: strict_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: strict_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: strict_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
-- All providers wrap schemas with `strict_schema` to ensure proper null handling
-- 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`:
@@ -214,3 +39,7 @@ REPO = {
 ## Dependencies
 
 Use `depends_on` helper for runtime dependency checking if your provider requires external gems.
+
+## Reference
+
+For hook method signatures, structured output handling, file handling, and complete examples, see [Custom Providers](../docs/providers/07_CUSTOM_PROVIDERS.md).

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.20.0"
+  ".": "0.21.0"
 }

data/AGENTS.md

@@ -4,7 +4,7 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 
 ## Quick Reference
 
-- **Ruby**: 3.2.0+
+- **Ruby**: 3.3.0+
 - **Lint + Test**: `bundle exec rake`
 - **Autoloading**: Zeitwerk (file paths must match module/class names)
 - **Model format**: `provider/model` (e.g., `openai/gpt-4`)

data/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.21.0](https://github.com/janeapp/riffer/compare/riffer/v0.20.0...riffer/v0.21.0) (2026-04-09)
+
+
+### Features
+
+* **amazon_bedrock:** support S3 URI file sources ([#190](https://github.com/janeapp/riffer/issues/190)) ([243e5b1](https://github.com/janeapp/riffer/commit/243e5b12407cac800b6cf0968a24989924932c26))
+* normalize consecutive same-role messages before provider serialization ([#201](https://github.com/janeapp/riffer/issues/201)) ([1ac986d](https://github.com/janeapp/riffer/commit/1ac986dd54a3fb9859ae05d57c49176e37704195))
+
 ## [0.20.0](https://github.com/janeapp/riffer/compare/riffer/v0.19.0...riffer/v0.20.0) (2026-03-26)
 
 

data/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
+[https://github.com/janeapp/riffer/issues](https://github.com/janeapp/riffer/issues) using the `conduct` label.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

data/README.md

@@ -6,7 +6,7 @@ The all-in-one Ruby framework for building AI-powered applications and agents.
 
 ## Requirements
 
-- Ruby 3.2 or later
+- Ruby 3.3 or later
 
 ## Installation
 
@@ -49,12 +49,18 @@ For comprehensive documentation, see the [docs](docs/) directory:
 
 - [Overview](docs/01_OVERVIEW.md) - Core concepts and architecture
 - [Getting Started](docs/02_GETTING_STARTED.md) - Installation and first steps
-- [Agents](docs/03_AGENTS.md) - Building AI agents
-- [Tools](docs/04_TOOLS.md) - Creating tools for agents
-- [Messages](docs/05_MESSAGES.md) - Message types and formats
-- [Stream Events](docs/06_STREAM_EVENTS.md) - Streaming responses
-- [Configuration](docs/07_CONFIGURATION.md) - Framework configuration
-- [Providers](docs_providers/01_PROVIDERS.md) - LLM provider adapters
+- [Agents](docs/03_AGENTS.md) - Defining and configuring agents
+- [Agent Lifecycle](docs/04_AGENT_LIFECYCLE.md) - Generate, stream, and responses
+- [Agent Loop](docs/05_AGENT_LOOP.md) - Tool execution flow and stopping
+- [Tools](docs/06_TOOLS.md) - Creating tools for agents
+- [Advanced Tools](docs/07_TOOL_ADVANCED.md) - Timeouts, runtime, and registration
+- [Messages](docs/08_MESSAGES.md) - Message types and formats
+- [Stream Events](docs/09_STREAM_EVENTS.md) - Streaming responses
+- [Configuration](docs/10_CONFIGURATION.md) - Framework configuration
+- [Evals](docs/11_EVALS.md) - Evaluating agent quality
+- [Guardrails](docs/12_GUARDRAILS.md) - Input/output validation
+- [Skills](docs/13_SKILLS.md) - Packaged agent capabilities
+- [Providers](docs/providers/01_PROVIDERS.md) - LLM provider adapters
 
 ### API Reference
 

data/Rakefile

@@ -12,12 +12,10 @@ RDoc::Task.new do |rdoc|
   rdoc.rdoc_dir = "doc"
   rdoc.title = "Riffer Documentation"
   rdoc.main = "README.md"
-
-  # Explicitly include top-level docs and the library
-  rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt", "docs/**/*.md", "docs_providers/**/*.md")
+  rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt")
   rdoc.rdoc_files.include("lib/**/*.rb")
-
   rdoc.options << "--charset" << "utf-8"
+  rdoc.options << "--page-dir" << "docs"
 end
 
 task docs: :rdoc

data/docs/01_OVERVIEW.md

@@ -30,12 +30,12 @@ class WeatherTool < Riffer::Tool
   end
 
   def call(context:, city:)
-    WeatherAPI.fetch(city)
+    text(WeatherAPI.fetch(city))
   end
 end
 ```
 
-See [Tools](04_TOOLS.md) for details.
+See [Tools](06_TOOLS.md) for details.
 
 ### Structured Output
 
@@ -65,7 +65,9 @@ See the [structured output section in Agents](03_AGENTS.md#structured_output) fo
 Providers are adapters that connect to LLM services. Riffer supports:
 
 - **OpenAI** - GPT models via the OpenAI API
+- **Azure OpenAI** - GPT models via Azure
 - **Amazon Bedrock** - Claude and other models via AWS Bedrock
+- **Anthropic** - Claude models via the Anthropic API
 - **Mock** - Mock provider for testing
 
 See [Providers](providers/01_PROVIDERS.md) for details.
@@ -79,7 +81,7 @@ Messages represent the conversation between user and assistant. Riffer uses stro
 - `Riffer::Messages::Assistant` - LLM responses
 - `Riffer::Messages::Tool` - Tool execution results
 
-See [Messages](05_MESSAGES.md) for details.
+See [Messages](08_MESSAGES.md) for details.
 
 ### Stream Events
 
@@ -92,7 +94,7 @@ When streaming responses, Riffer emits typed events:
 - `WebSearchStatus` - Web search progress updates
 - `WebSearchDone` - Web search completion with sources
 
-See [Stream Events](06_STREAM_EVENTS.md) for details.
+See [Stream Events](09_STREAM_EVENTS.md) for details.
 
 ## Architecture
 
@@ -127,5 +129,8 @@ Response
 
 - [Getting Started](02_GETTING_STARTED.md) - Quick start guide
 - [Agents](03_AGENTS.md) - Agent configuration and usage
-- [Tools](04_TOOLS.md) - Creating tools
-- [Configuration](07_CONFIGURATION.md) - Global configuration
+- [Tools](06_TOOLS.md) - Creating tools
+- [Configuration](10_CONFIGURATION.md) - Global configuration
+- [Evals](11_EVALS.md) - Evaluating agent quality
+- [Guardrails](12_GUARDRAILS.md) - Input/output validation
+- [Skills](13_SKILLS.md) - Packaged agent capabilities

data/docs/02_GETTING_STARTED.md

@@ -24,37 +24,7 @@ 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
-```
+Riffer requires an LLM provider. See [Providers](providers/01_PROVIDERS.md) for setup instructions for each supported provider.
 
 ## Creating Your First Agent
 
@@ -104,7 +74,7 @@ class TimeTool < Riffer::Tool
   description "Gets the current time"
 
   def call(context:)
-    Time.now.strftime('%Y-%m-%d %H:%M:%S')
+    text(Time.now.strftime('%Y-%m-%d %H:%M:%S'))
   end
 end
 
@@ -122,7 +92,7 @@ puts agent.generate("What time is it?")
 ## 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
+- [Tools](06_TOOLS.md) - Creating tools with parameters
+- [Messages](08_MESSAGES.md) - Message types and history
+- [Stream Events](09_STREAM_EVENTS.md) - Streaming event types
 - [Providers](providers/01_PROVIDERS.md) - Provider-specific guides