riffer 0.18.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12ca19d6aeb04239a6938aa523a9e7254a1a5599a9629e6a333fc385a0d94de3
-  data.tar.gz: dec4506d7e4800b9cf12aa817e5df14c65b8822930d50ad75b0c912a6d5099bf
+  metadata.gz: '09506e8a2dfa346e49231fa598f1e899066a5597ddd5b6738758ca49594ca7c2'
+  data.tar.gz: 684dc3caf2f6a59d052adb51a5c33bdf0a5542a2a375f188a1bc0a600a7df5ef
 SHA512:
-  metadata.gz: 84b914f6160009c13ba5ac1ed6b659fe45ba13dea14ccb1dd94d529b9de4526c0c7afff84e6bbeac565b81d529e42689c07874da89f6509e4510d59756cad073
-  data.tar.gz: df04dc8a8ee28e70b95073b790d268c7488f0a9cd16131e1acafbfa651a9254d8868d9042607a73a5f4572e5e0a5eaee84b27965034894e4022294344d89be1f
+  metadata.gz: 2b1c4119f8afac1367aac6a7d9caddd656a598dab1ad44c921802864e73815d19c3a4f96e554483d9062c9e87864bd870e8af260b9d7f5922331bdcc714ccb52
+  data.tar.gz: 5f8387e02a6b2638550e59265980c8de6ce9422b77f905dcc019360e039d59ffb5b8d76310ba90819f7f7b51a5af34588b0de40782255c57215d4bf32ca862c8

data/.agents/architecture.md

@@ -107,6 +107,29 @@ MyAgent.new.stream(persisted_messages)  # cross-process resume
 
 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.
 
+### Runner (`lib/riffer/runner.rb`)
+
+Concurrency primitive for batch execution. Subclasses implement `#map(items, context: nil, &block)` to control how items are processed. The `context` keyword carries the agent's context hash, enabling runners that need it for job serialization or routing.
+
+Built-in runners:
+- `Sequential` — processes items in the current thread via `Array#map`
+- `Threaded` — processes items concurrently using a thread pool with configurable `max_concurrency`
+
+```ruby
+runner = Riffer::Runner::Threaded.new(max_concurrency: 3)
+runner.map(items, context: ctx) { |item| process(item) }
+```
+
+### ToolRuntime (`lib/riffer/tool_runtime.rb`)
+
+Composes with a Runner to execute tool calls. Provides `#execute` as the public entry point and `#around_tool_call` as a hook for instrumentation. Passes the agent context through to the runner.
+
+Built-in runtimes:
+- `Inline` — uses `Runner::Sequential` (default)
+- `Threaded` — uses `Runner::Threaded`
+
+Context flow: `Agent#execute_tool_calls` → `ToolRuntime#execute(tool_calls, tools:, context:)` → `Runner#map(tool_calls, context:) { dispatch }` → `Tool#call(context:, **args)`
+
 ## Key Patterns
 
 - Model config accepts a `provider/model` string (e.g., `openai/gpt-4`) or a Proc/lambda that returns one

data/.agents/rdoc.md

@@ -4,18 +4,30 @@ Use RDoc prose comments for public API descriptions and RBS inline annotations f
 
 ## Parameters and Return Types
 
-Describe parameters in the RDoc prose comment. Use a single `#:` line for the RBS method signature (see [rbs-inline.md](rbs-inline.md) for the full type annotation syntax):
+Describe parameters using RDoc labeled list syntax. Use a single `#:` line for the RBS method signature (see [rbs-inline.md](rbs-inline.md) for the full type annotation syntax):
 
 ```ruby
 # Creates a new agent.
 #
-# +name+ - the agent name.
-# +options+ - optional configuration.
+# [name] the agent name.
+# [options] optional configuration.
 #
+#--
 #: (String, ?options: Hash[Symbol, untyped]) -> void
 def initialize(name, options: {})
 ```
 
+Always add `#--` (RDoc stop directive) on the line before a standalone `#:` type annotation. Without it, RDoc treats `#:` as a label-list marker and corrupts the preceding comment into a `<pre>` block. Inline `#:` on the same line as code (e.g., `attr_reader :name #: String`) does not need this.
+
+## Inline Code
+
+Use `+word+` for single-word inline code. For multi-word expressions (containing spaces, colons, or brackets), use `<tt>multi word expression</tt>`:
+
+```ruby
+# Returns +nil+ when no instructions are configured.
+# Equivalent to <tt>throw :riffer_interrupt, reason</tt>.
+```
+
 ## Attributes and Constants
 
 Use `#:` inline syntax (on the same line) for attribute and constant types:
@@ -37,7 +49,7 @@ Document with prose:
 
 ## Examples
 
-Include usage examples as indented code blocks:
+Include usage examples as indented code blocks (2 extra spaces of indent):
 
 ```ruby
 # Creates a new agent.

data/.release-please-manifest.json

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

data/.ruby-version

@@ -1 +1 @@
-3.4.8
+3.4.8

data/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.20.0](https://github.com/janeapp/riffer/compare/riffer/v0.19.0...riffer/v0.20.0) (2026-03-26)
+
+
+### Features
+
+* add fibers tool runtime using async gem ([#178](https://github.com/janeapp/riffer/issues/178)) ([67fd344](https://github.com/janeapp/riffer/commit/67fd34493126559b99a00cc3402a6adabefc14ea))
+
+
+### Bug Fixes
+
+* correct RDoc formatting for docs.riffer.ai ([#182](https://github.com/janeapp/riffer/issues/182)) ([2f2fbc9](https://github.com/janeapp/riffer/commit/2f2fbc997281ef4a546a58e44233e325a25c41d5))
+
+## [0.19.0](https://github.com/janeapp/riffer/compare/riffer/v0.18.0...riffer/v0.19.0) (2026-03-25)
+
+
+### Features
+
+* Add Azure OpenAI provider ([#167](https://github.com/janeapp/riffer/issues/167)) ([5d34fcd](https://github.com/janeapp/riffer/commit/5d34fcd4a98a6bcfa768c50fea7c25959eca5f1d))
+* expose message history in eval results ([#171](https://github.com/janeapp/riffer/issues/171)) ([c8b1aec](https://github.com/janeapp/riffer/commit/c8b1aeceb40a173c70d4be445fb82bba10113b87))
+* provide agent context to runners ([#181](https://github.com/janeapp/riffer/issues/181)) ([23c9282](https://github.com/janeapp/riffer/commit/23c9282d4f2076d1ff6185f99bcf855f158ccb0d))
+
 ## [0.18.0](https://github.com/janeapp/riffer/compare/riffer/v0.17.0...riffer/v0.18.0) (2026-03-13)
 
 

data/README.md

@@ -34,7 +34,7 @@ end
 
 # Define an agent
 class EchoAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are an assistant that repeats what the user says.'
 end
 

data/Rakefile

@@ -17,8 +17,7 @@ RDoc::Task.new do |rdoc|
   rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt", "docs/**/*.md", "docs_providers/**/*.md")
   rdoc.rdoc_files.include("lib/**/*.rb")
 
-  # Use Markdown where available and ensure UTF-8
-  rdoc.options << "--charset" << "utf-8" << "--markup" << "markdown"
+  rdoc.options << "--charset" << "utf-8"
 end
 
 task docs: :rdoc

data/docs/01_OVERVIEW.md

@@ -10,7 +10,7 @@ The Agent is the central orchestrator for AI interactions. It manages messages,
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are a helpful assistant.'
 end
 ```
@@ -43,7 +43,7 @@ Agents can return structured JSON responses that conform to a schema. The respon
 
 ```ruby
 class SentimentAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   structured_output do
     required :sentiment, String
     required :score, Float

data/docs/02_GETTING_STARTED.md

@@ -68,7 +68,7 @@ Riffer.configure do |config|
 end
 
 class GreetingAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are a friendly assistant. Greet the user warmly.'
 end
 
@@ -109,7 +109,7 @@ class TimeTool < Riffer::Tool
 end
 
 class TimeAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You can tell the user the current time.'
   uses_tools [TimeTool]
 end

data/docs/03_AGENTS.md

@@ -8,7 +8,7 @@ Create an agent by subclassing `Riffer::Agent`:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are a helpful assistant.'
 end
 ```
@@ -21,9 +21,9 @@ Sets the provider and model in `provider/model` format:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'           # OpenAI
+  model 'openai/gpt-5-mini'           # OpenAI
   # or
-  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'  # Bedrock
+  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'  # Bedrock
   # or
   model 'mock/any'                # Mock provider
 end
@@ -33,7 +33,7 @@ Models can also be resolved dynamically with a lambda:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model -> { "anthropic/claude-sonnet-4-20250514" }
+  model -> { "anthropic/claude-haiku-4-5-20251001" }
 end
 ```
 
@@ -42,7 +42,7 @@ When the lambda accepts a parameter, it receives the `context`:
 ```ruby
 class MyAgent < Riffer::Agent
   model ->(context) {
-    context&.dig(:premium) ? "anthropic/claude-sonnet-4-20250514" : "anthropic/claude-haiku-4-5-20251001"
+    context&.dig(:premium) ? "anthropic/claude-sonnet-4-5-20250929" : "anthropic/claude-haiku-4-5-20251001"
   }
 end
 ```
@@ -55,7 +55,7 @@ Sets system instructions for the agent:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are an expert Ruby programmer. Provide concise answers.'
 end
 ```
@@ -64,7 +64,7 @@ Instructions can also be resolved dynamically with a lambda:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions -> { "Today is #{Date.today}. You are a helpful assistant." }
 end
 ```
@@ -73,7 +73,7 @@ When the lambda accepts a parameter, it receives the `context`:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions ->(ctx) { "You are assisting #{ctx[:name]}" }
 end
 
@@ -88,7 +88,7 @@ Sets a custom identifier (defaults to snake_case class name):
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   identifier 'custom_agent_name'
 end
 
@@ -101,7 +101,7 @@ Registers tools the agent can use:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, TimeTool]
 end
 ```
@@ -110,7 +110,7 @@ Tools can also be resolved dynamically with a lambda:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
 
   uses_tools ->(context) {
     tools = [PublicTool]
@@ -126,7 +126,7 @@ Passes options to the provider client:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
 end
 ```
@@ -137,7 +137,7 @@ Passes options to each LLM request:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   model_options reasoning: 'medium', temperature: 0.7, web_search: true
 end
 ```
@@ -148,7 +148,7 @@ Sets the maximum number of LLM call steps in the tool-use loop. When the limit i
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   max_steps 8
 end
 ```
@@ -159,7 +159,7 @@ Configures the agent to return structured JSON responses conforming to a schema.
 
 ```ruby
 class SentimentAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'Analyze the sentiment of the given text.'
   structured_output do
     required :sentiment, String, description: "positive, negative, or neutral"
@@ -249,7 +249,7 @@ Configures how tool calls are executed. Defaults to sequential (inline) executio
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
   tool_runtime Riffer::ToolRuntime::Threaded
 end
@@ -263,7 +263,7 @@ Registers guardrails for pre/post processing of messages. Pass the guardrail cla
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
 
   # Input-only guardrail
   guardrail :before, with: InputValidator
@@ -544,6 +544,7 @@ Returns `nil` if the provider doesn't report usage, or a `Riffer::TokenUsage` ob
 | `modifications`     | `Array`                     | List of guardrail modifications applied            |
 | `interrupted?`      | `Boolean`                   | `true` if the loop was interrupted                 |
 | `interrupt_reason`  | `String` / `Symbol` / `nil` | The reason passed to `throw :riffer_interrupt`     |
+| `messages`          | `Array`                     | Full message history from the conversation         |
 
 ### response.structured_output
 
@@ -629,7 +630,7 @@ Guardrails are registered at class definition time and run automatically on ever
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   guardrail :before, with: ContentPolicy
 end
 
@@ -670,7 +671,7 @@ The `max_steps` class method caps the number of LLM call steps in the tool-use l
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   max_steps 8
 end
 

data/docs/04_TOOLS.md

@@ -324,7 +324,7 @@ WeatherTool.parameters_schema
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
 end
 ```
@@ -335,7 +335,7 @@ Use a lambda for context-aware tool resolution:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
 
   uses_tools ->(context) {
     tools = [PublicSearchTool]
@@ -384,6 +384,7 @@ By default, tool calls are executed sequentially in the current thread using `Ri
 | ------------------------------- | ---------------------------------------------- |
 | `Riffer::ToolRuntime::Inline`   | Executes tool calls sequentially (default)     |
 | `Riffer::ToolRuntime::Threaded` | Executes tool calls concurrently using threads |
+| `Riffer::ToolRuntime::Fibers`   | Executes tool calls concurrently using fibers  |
 
 ### Per-Agent Configuration
 
@@ -391,7 +392,7 @@ Use the `tool_runtime` class method on your agent:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
   tool_runtime Riffer::ToolRuntime::Threaded
 end
@@ -409,7 +410,7 @@ Use a lambda for context-aware runtime selection:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
 
   tool_runtime ->(context) {
@@ -444,12 +445,41 @@ The threaded runtime accepts a `max_concurrency` option (default: 5):
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   uses_tools [WeatherTool, SearchTool]
   tool_runtime Riffer::ToolRuntime::Threaded.new(max_concurrency: 3)
 end
 ```
 
+### Fibers Runtime
+
+The fibers runtime uses the [async](https://github.com/socketry/async) gem for lightweight, cooperative concurrency. It requires the `async` gem to be installed:
+
+```ruby
+# Gemfile
+gem "async"
+```
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-5-mini'
+  uses_tools [WeatherTool, SearchTool]
+  tool_runtime Riffer::ToolRuntime::Fibers
+end
+```
+
+By default, all tool calls run as fibers without a concurrency limit. You can optionally set a limit:
+
+```ruby
+class MyAgent < Riffer::Agent
+  model 'openai/gpt-5-mini'
+  uses_tools [WeatherTool, SearchTool]
+  tool_runtime Riffer::ToolRuntime::Fibers.new(max_concurrency: 10)
+end
+```
+
+Fibers use cooperative scheduling — they yield control at I/O boundaries (network calls, file reads, sleep). CPU-bound tools will not benefit from the fibers runtime. Be mindful of fiber-local state (`Fiber.[]`) and note that `Thread.current[]` values are shared across all fibers in the same thread.
+
 ### Custom Runtimes
 
 Create a custom runtime by subclassing `Riffer::ToolRuntime` and overriding the private `dispatch_tool_call` method:

data/docs/06_STREAM_EVENTS.md

@@ -266,7 +266,7 @@ end
 
 ```ruby
 class WeatherAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are a weather assistant.'
   uses_tools [WeatherTool]
 end

data/docs/07_CONFIGURATION.md

@@ -102,7 +102,7 @@ Pass options directly to the provider client:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
 
   # Override API key for this agent only
   provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
@@ -115,7 +115,7 @@ Pass options to each LLM request:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
 
   # These options are sent with every generate/stream call
   model_options temperature: 0.7, reasoning: 'medium'
@@ -136,7 +136,7 @@ end
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   model_options temperature: 0.7, reasoning: 'medium'
 end
 ```
@@ -152,7 +152,7 @@ Options are passed through to the [Bedrock Converse API](https://docs.aws.amazon
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'amazon_bedrock/anthropic.claude-3-sonnet-20240229-v1:0'
+  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'
   model_options inference_config: {temperature: 0.7, max_tokens: 4096}
 end
 ```
@@ -170,13 +170,13 @@ end
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'anthropic/claude-3-5-sonnet-20241022'
+  model 'anthropic/claude-haiku-4-5-20251001'
   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 'anthropic/claude-haiku-4-5-20251001'
   model_options thinking: {type: "enabled", budget_tokens: 10000}
 end
 ```
@@ -205,12 +205,12 @@ For different environments or use cases, use agent-level overrides:
 
 ```ruby
 class ProductionAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   provider_options api_key: ENV['PRODUCTION_OPENAI_KEY']
 end
 
 class DevelopmentAgent < Riffer::Agent
-  model 'openai/gpt-4o-mini'
+  model 'openai/gpt-5-mini'
   provider_options api_key: ENV['DEV_OPENAI_KEY']
   model_options temperature: 0.0  # Deterministic for testing
 end

data/docs/08_EVALS.md

@@ -120,6 +120,7 @@ scenario.output       # => "The capital of France is Paris."
 scenario.ground_truth # => "Paris"
 scenario.scores       # => { EvaluatorClass => score } for this scenario
 scenario.results      # => Array of Result objects
+scenario.messages     # => Array of Message objects (system, user, assistant, tool)
 scenario.to_h         # => Hash representation
 ```
 
@@ -183,7 +184,7 @@ Class methods:
 
 Instance methods:
 
-- `evaluate(input:, output:, ground_truth:)` - Override for custom logic; default calls judge with `instructions`
+- `evaluate(input:, output:, ground_truth:, messages:)` - Override for custom logic; default calls judge with `instructions`
 - `judge` - Returns a Judge instance for LLM-as-judge calls
 - `result(score:, reason:, metadata:)` - Helper to build Result objects
 
@@ -196,7 +197,7 @@ class CustomEvaluator < Riffer::Evals::Evaluator
   higher_is_better true
   judge_model "anthropic/claude-opus-4-5-20251101"
 
-  def evaluate(input:, output:, ground_truth: nil)
+  def evaluate(input:, output:, ground_truth: nil, messages: [])
     evaluation = judge.evaluate(
       instructions: "Custom evaluation criteria...",
       input: input,
@@ -217,7 +218,7 @@ Evaluators don't have to use LLM-as-judge:
 class LengthEvaluator < Riffer::Evals::Evaluator
   higher_is_better true
 
-  def evaluate(input:, output:, ground_truth: nil)
+  def evaluate(input:, output:, ground_truth: nil, messages: [])
     min_length = 50
     max_length = 500
 

data/docs/10_SKILLS.md

@@ -44,7 +44,7 @@ Use the `skills` block DSL to configure skills:
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model "openai/gpt-4o"
+  model "openai/gpt-5-mini"
   instructions "You are a helpful assistant."
   skills do
     backend Riffer::Skills::FilesystemBackend.new(".skills")

data/docs_providers/01_PROVIDERS.md

@@ -7,6 +7,7 @@ Providers are adapters that connect Riffer to LLM services. They implement a com
 | Provider       | Identifier       | Gem Required             |
 | -------------- | ---------------- | ------------------------ |
 | OpenAI         | `openai`         | `openai`                 |
+| Azure OpenAI   | `azure_openai`   | `openai`                 |
 | Amazon Bedrock | `amazon_bedrock` | `aws-sdk-bedrockruntime` |
 | Anthropic      | `anthropic`      | `anthropic`              |
 | Mock           | `mock`           | None                     |
@@ -17,10 +18,11 @@ 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 'mock/any'                   # Mock provider
+  model 'openai/gpt-5-mini'                                           # OpenAI
+  model 'azure_openai/gpt-5-mini'                                     # Azure OpenAI
+  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'  # Bedrock
+  model 'anthropic/claude-haiku-4-5-20251001'                         # Anthropic
+  model 'mock/any'                                                    # Mock provider
 end
 ```
 
@@ -37,14 +39,14 @@ provider = Riffer::Providers::OpenAI.new(api_key: "...")
 
 response = provider.generate_text(
   prompt: "Hello!",
-  model: "gpt-4o"
+  model: "gpt-5-mini"
 )
 # => Riffer::Messages::Assistant
 
 # Or with messages
 response = provider.generate_text(
   messages: [Riffer::Messages::User.new("Hello!")],
-  model: "gpt-4o"
+  model: "gpt-5-mini"
 )
 ```
 
@@ -53,7 +55,7 @@ response = provider.generate_text(
 Streams a response as an Enumerator:
 
 ```ruby
-provider.stream_text(prompt: "Tell me a story", model: "gpt-4o").each do |event|
+provider.stream_text(prompt: "Tell me a story", model: "gpt-5-mini").each do |event|
   case event
   when Riffer::StreamEvents::TextDelta
     print event.content
@@ -90,7 +92,7 @@ provider = Riffer::Providers::OpenAI.new
 # Simple prompt
 response = provider.generate_text(
   prompt: "What is Ruby?",
-  model: "gpt-4o"
+  model: "gpt-5-mini"
 )
 puts response.content
 
@@ -98,7 +100,7 @@ puts response.content
 response = provider.generate_text(
   prompt: "Explain recursion",
   system: "You are a programming tutor. Use simple language.",
-  model: "gpt-4o"
+  model: "gpt-5-mini"
 )
 
 # With message history
@@ -111,7 +113,7 @@ messages = [
 
 response = provider.generate_text(
   messages: messages,
-  model: "gpt-4o"
+  model: "gpt-5-mini"
 )
 ```
 
@@ -132,7 +134,7 @@ end
 
 response = provider.generate_text(
   prompt: "What's the weather in Tokyo?",
-  model: "gpt-4o",
+  model: "gpt-5-mini",
   tools: [WeatherTool]
 )
 
@@ -149,6 +151,9 @@ Riffer uses a registry to find providers by identifier:
 Riffer::Providers::Repository.find(:openai)
 # => Riffer::Providers::OpenAI
 
+Riffer::Providers::Repository.find(:azure_openai)
+# => Riffer::Providers::AzureOpenAI
+
 Riffer::Providers::Repository.find(:amazon_bedrock)
 # => Riffer::Providers::AmazonBedrock
 
@@ -164,5 +169,6 @@ Riffer::Providers::Repository.find(:mock)
 - [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
-- [Mock](05_MOCK_PROVIDER.md) - Mock provider for testing
-- [Custom Providers](06_CUSTOM_PROVIDERS.md) - Creating your own provider
+- [Azure OpenAI](05_AZURE_OPENAI.md) - GPT models via Azure
+- [Mock](06_MOCK_PROVIDER.md) - Mock provider for testing
+- [Custom Providers](07_CUSTOM_PROVIDERS.md) - Creating your own provider