riffer 0.31.0 → 0.32.1

data/lib/riffer/messages/base.rb

@@ -3,10 +3,49 @@
 
 require "securerandom"
 
-# Base class for all message types in the Riffer framework.
-#
-# Subclasses must implement the +role+ method.
+# Base class for all message types. Subclasses must implement +role+.
 class Riffer::Messages::Base
+  # Builds the matching message subclass from a hash, or returns +msg+ unchanged
+  # when it is already a message. Raises Riffer::ArgumentError on an invalid message.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::Base)) -> Riffer::Messages::Base
+  def self.from_hash(msg)
+    return msg if msg.is_a?(Riffer::Messages::Base)
+
+    unless msg.is_a?(Hash)
+      raise Riffer::ArgumentError, "Message must be a Hash or Message object, got #{msg.class}"
+    end
+
+    role = msg[:role]
+    content = msg[:content]
+
+    if role.nil? || role.empty?
+      raise Riffer::ArgumentError, "Message hash must include a 'role' key"
+    end
+
+    id = msg[:id]
+
+    case role.to_sym
+    when :user
+      files = (msg[:files] || []).map { |f| Riffer::Messages::FilePart.from_hash(f) }
+      Riffer::Messages::User.new(content, id: id, files: files)
+    when :assistant
+      tool_calls = (msg[:tool_calls] || []).map { |tc|
+        tc.is_a?(Riffer::Messages::Assistant::ToolCall) ? tc : Riffer::Messages::Assistant::ToolCall.new(**tc)
+      }
+      structured_output = msg[:structured_output]
+      Riffer::Messages::Assistant.new(content, id: id, tool_calls: tool_calls, structured_output: structured_output)
+    when :system
+      Riffer::Messages::System.new(content, id: id)
+    when :tool
+      tool_call_id = msg[:tool_call_id]
+      name = msg[:name]
+      Riffer::Messages::Tool.new(content, id: id, tool_call_id: tool_call_id, name: name)
+    else
+      raise Riffer::ArgumentError, "Unknown message role: #{role}"
+    end
+  end
+
   # The message content.
   attr_reader :content #: String
 
@@ -31,31 +70,22 @@ class Riffer::Messages::Base
   end
 
   # Returns the message role.
-  #
-  # Raises NotImplementedError if not implemented by subclass.
-  #
   #--
   #: () -> Symbol
   def role
     raise NotImplementedError, "Subclasses must implement #role"
   end
 
-  # Whether this message carries pending tool calls. Defaults to +false+;
-  # +Riffer::Messages::Assistant+ overrides this when its +tool_calls+
-  # array is non-empty.
-  #
+  # Whether this message carries pending tool calls (overridden by
+  # +Riffer::Messages::Assistant+).
   #--
   #: () -> bool
   def has_tool_calls?
     false
   end
 
-  # Merges another same-role message into this one.
-  #
-  # Raises NotImplementedError unless implemented by subclass. Mergeable
-  # message types (+User+, +Assistant+, +System+) override this; +Tool+
-  # messages are never merged.
-  #
+  # Merges another same-role message into this one. +Tool+ messages are never
+  # merged.
   #--
   #: (untyped) -> Riffer::Messages::Base
   def +(other)

data/lib/riffer/messages/file_part.rb

@@ -4,16 +4,8 @@
 require "base64"
 require "uri"
 
-# Represents a file attachment (image or document) in a conversation.
-#
-# Supports two input sources:
-# - URLs (stored and passed to providers that support them via +from_url+)
-# - Raw base64 data (via +new+)
-#
-#   file = Riffer::Messages::FilePart.from_url("https://example.com/doc.pdf", media_type: "application/pdf")
-#   file.url?        # => true
-#   file.document?   # => true
-#
+# Represents a file attachment (image or document) — from a URL (+from_url+) or
+# raw base64 data (+new+).
 class Riffer::Messages::FilePart
   # @rbs @url_string: String?
 
@@ -38,13 +30,8 @@ class Riffer::Messages::FilePart
   # The filename, if available.
   attr_reader :filename #: String?
 
-  # Creates a FilePart from raw base64 data or a URL.
-  #
-  # At least one of +data+ or +url+ must be provided.
-  #
-  # Raises Riffer::ArgumentError if neither data nor url is provided,
-  # or if media_type is not supported.
-  #
+  # Raises Riffer::ArgumentError unless +data+ or +url+ is given and
+  # +media_type+ is supported.
   #--
   #: (media_type: String, ?data: String?, ?filename: String?, ?url: String?) -> void
   def initialize(media_type:, data: nil, filename: nil, url: nil)
@@ -57,13 +44,8 @@ class Riffer::Messages::FilePart
     @url_string = url
   end
 
-  # Creates a FilePart from a URL.
-  #
-  # The URL is stored and passed directly to providers that support URL sources.
-  # If +media_type+ is not provided, it is detected from the URL path extension.
-  #
-  # Raises Riffer::ArgumentError if media_type cannot be detected.
-  #
+  # Creates a FilePart from a URL, detecting +media_type+ from the path
+  # extension when omitted. Raises Riffer::ArgumentError if it can't be detected.
   #--
   #: (String, ?media_type: String?) -> Riffer::Messages::FilePart
   def self.from_url(url, media_type: nil)
@@ -76,6 +58,32 @@ class Riffer::Messages::FilePart
     new(url: url, media_type: media_type)
   end
 
+  # Builds a FilePart from a +{url:, media_type:}+ or +{data:, media_type:}+ hash,
+  # or returns +file+ unchanged when it is already a FilePart. Raises
+  # Riffer::ArgumentError on an invalid hash.
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Messages::FilePart)) -> Riffer::Messages::FilePart
+  def self.from_hash(file)
+    return file if file.is_a?(Riffer::Messages::FilePart)
+
+    unless file.is_a?(Hash)
+      raise Riffer::ArgumentError, "File must be a Hash or FilePart object, got #{file.class}"
+    end
+
+    url = file[:url]
+    data = file[:data]
+    media_type = file[:media_type]
+    filename = file[:filename]
+
+    if url
+      from_url(url, media_type: media_type)
+    elsif data && media_type
+      new(data: data, media_type: media_type, filename: filename)
+    else
+      raise Riffer::ArgumentError, "File hash must include :url or :data with :media_type"
+    end
+  end
+
   # Returns the base64-encoded data, or nil for URL-only sources.
   attr_reader :data #: String?
 

data/lib/riffer/messages/system.rb

@@ -2,11 +2,6 @@
 # rbs_inline: enabled
 
 # Represents a system message (instructions) in a conversation.
-#
-#   msg = Riffer::Messages::System.new("You are a helpful assistant.")
-#   msg.role     # => :system
-#   msg.content  # => "You are a helpful assistant."
-#
 class Riffer::Messages::System < Riffer::Messages::Base
   #--
   #: () -> Symbol

data/lib/riffer/messages/tool.rb

@@ -2,16 +2,6 @@
 # rbs_inline: enabled
 
 # Represents a tool execution result in a conversation.
-#
-#   msg = Riffer::Messages::Tool.new(
-#     "The weather is sunny.",
-#     tool_call_id: "call_123",
-#     name: "weather_tool"
-#   )
-#   msg.role          # => :tool
-#   msg.tool_call_id  # => "call_123"
-#   msg.error?        # => false
-#
 class Riffer::Messages::Tool < Riffer::Messages::Base
   # The ID of the tool call this result responds to.
   attr_reader :tool_call_id #: String

data/lib/riffer/messages/user.rb

@@ -2,20 +2,10 @@
 # rbs_inline: enabled
 
 # Represents a user message in a conversation.
-#
-#   msg = Riffer::Messages::User.new("Hello!")
-#   msg.role     # => :user
-#   msg.content  # => "Hello!"
-#
-#   msg = Riffer::Messages::User.new("Describe this image", files: [file_part])
-#   msg.files    # => [#<Riffer::Messages::FilePart ...>]
-#
 class Riffer::Messages::User < Riffer::Messages::Base
   # File attachments for this message.
   attr_reader :files #: Array[Riffer::Messages::FilePart]
 
-  # Initializes a user message.
-  #
   #--
   #: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void
   def initialize(content, id: nil, files: [])

data/lib/riffer/messages.rb

@@ -1,12 +1,5 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Namespace for message types in the Riffer framework.
-#
-# Message objects represent the conversation between users and the assistant:
-# - Riffer::Messages::System - System instructions
-# - Riffer::Messages::User - User input
-# - Riffer::Messages::Assistant - LLM responses
-# - Riffer::Messages::Tool - Tool execution results
 module Riffer::Messages
 end

data/lib/riffer/params/boolean.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Params::Boolean is a sentinel type for declaring boolean parameters.
-#
-# Ruby has no +Boolean+ class (+true+ is +TrueClass+, +false+ is +FalseClass+).
-# Use this module wherever you need a single type that means "boolean":
+# Sentinel type for declaring boolean parameters — Ruby has no +Boolean+ class
+# (+true+/+false+ are +TrueClass+/+FalseClass+).
 #
 #   required :verbose, Riffer::Params::Boolean
 #

data/lib/riffer/params/param.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Params::Param represents a single parameter definition.
-#
-# Handles type validation and JSON Schema generation for individual parameters.
+# A single parameter definition, handling type validation and JSON Schema
+# generation.
 class Riffer::Params::Param
   # Maps Ruby types to JSON Schema type strings
   TYPE_MAPPINGS = {
@@ -20,9 +19,8 @@ class Riffer::Params::Param
   # Primitive types allowed for the <tt>of:</tt> keyword on Array params
   PRIMITIVE_TYPES = (TYPE_MAPPINGS.keys - [Array, Hash]).freeze #: Array[Module]
 
-  # Maps JSON Schema type strings back to Ruby types. The inverse of
-  # TYPE_MAPPINGS, collapsing the three boolean spellings onto
-  # Riffer::Params::Boolean. Used by +from_json_schema+.
+  # Maps JSON Schema type strings back to Ruby types (inverse of TYPE_MAPPINGS),
+  # collapsing the three boolean spellings onto Riffer::Params::Boolean.
   JSON_TYPE_MAPPINGS = {
     "string" => String,
     "integer" => Integer,
@@ -32,24 +30,32 @@ class Riffer::Params::Param
     "object" => Hash
   }.freeze #: Hash[String, Module]
 
+  # The parameter name.
   attr_reader :name #: Symbol
+
+  # The Ruby type.
   attr_reader :type #: Module
+
+  # Whether the parameter is required.
   attr_reader :required #: bool
+
+  # The parameter description, if any.
   attr_reader :description #: String?
+
+  # Allowed values, if constrained.
   attr_reader :enum #: Array[untyped]?
+
+  # The default value, if any.
   attr_reader :default #: untyped
+
+  # Element type for a typed array (+of:+).
   attr_reader :item_type #: Module?
+
+  # Nested Params for object / array-of-object types.
   attr_reader :nested_params #: Riffer::Params?
 
-  #--
-  # Reconstructs a Param from a single JSON Schema property.
-  #
-  # [name] the parameter name (Symbol).
-  # [schema] the property's JSON Schema (Symbol-keyed).
-  # [required] whether the property appeared in the parent's +required+ list.
-  #
-  # Raises Riffer::ArgumentError on a type outside the Params-expressible subset.
-  #
+  # Reconstructs a Param from a single JSON Schema property. Raises
+  # Riffer::ArgumentError on a type outside the Params-expressible subset.
   #--
   #: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
   def self.from_json_schema(name, schema, required:)
@@ -68,10 +74,6 @@ class Riffer::Params::Param
     )
   end
 
-  # Resolves the +[item_type, nested_params]+ pair for a reconstructed Param:
-  # a nested Params for object / array-of-object schemas, an +item_type+ for
-  # typed primitive arrays, and +nil+ for everything else.
-  #
   #--
   #: (Module, Hash[Symbol, untyped]) -> [Module?, Riffer::Params?]
   def self.resolve_nesting(ruby_type, schema)
@@ -86,12 +88,9 @@ class Riffer::Params::Param
   end
   private_class_method :resolve_nesting
 
-  # Resolves a JSON Schema +type+ (a String, or a <tt>[type, "null"]</tt>
-  # union) back to its Ruby type. Returns a Module because
-  # Riffer::Params::Boolean is a Module, not a Class — the same widening the
-  # +type+ attribute uses. Raises Riffer::ArgumentError on a type outside the
-  # Params-expressible subset (the block runs only for an unmapped type).
-  #
+  # Resolves a JSON Schema +type+ (or a <tt>[type, "null"]</tt> union) to its
+  # Ruby type. Returns a Module — Riffer::Params::Boolean is a Module, not a
+  # Class. Raises Riffer::ArgumentError on an unsupported type.
   #--
   #: (untyped) -> Module
   def self.json_type_to_ruby(type)
@@ -135,21 +134,11 @@ class Riffer::Params::Param
     TYPE_MAPPINGS[type] || type.to_s.downcase
   end
 
-  # Converts this parameter to JSON Schema format.
-  #
-  # When +strict+ is true, optional parameters are made nullable
-  # (<tt>["type", "null"]</tt>) so that strict mode providers can distinguish
-  # "absent" from "present" without rejecting the schema.
-  #
-  # Optional parameters with an +enum+ use +anyOf+ to separate the enum
-  # constraint from the null type, since providers like Anthropic reject
+  # Converts this parameter to JSON Schema format. When +strict+, optional
+  # params are made nullable (<tt>["type", "null"]</tt>) so strict providers
+  # distinguish absent from present; optional params with an +enum+ use +anyOf+
+  # instead, since providers like Anthropic reject
   # <tt>{"type": ["string", "null"], "enum": [...]}</tt>.
-  #
-  # In non-strict mode a +default+ is emitted when set (a standard JSON
-  # Schema keyword), making the schema a lossless source for
-  # +Riffer::Params.from_json_schema+. Strict mode omits it, since strict
-  # providers reject the keyword.
-  #
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)

data/lib/riffer/params.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Riffer::Params provides a DSL for defining parameters.
-#
-# Used within a Tool's +params+ block to define required and optional parameters,
-# and by StructuredOutput to define response schemas.
+# A DSL for defining tool parameters and structured-output schemas, used within
+# a Tool's +params+ block.
 #
 #   params do
 #     required :city, String, description: "The city name"
@@ -12,6 +10,7 @@
 #   end
 #
 class Riffer::Params
+  # The defined parameters.
   attr_reader :parameters #: Array[Riffer::Params::Param]
 
   #--
@@ -20,17 +19,9 @@ class Riffer::Params
     @parameters = []
   end
 
-  # Reconstructs a Params from a JSON Schema object (the inverse of
-  # +to_json_schema(strict: false)+).
-  #
-  # Accepts the Symbol-keyed object schema produced by +to_json_schema+
-  # (property-name keys may be String or Symbol — both are normalized).
-  # Reconstructs types, +required+, +description+, +enum+, +default+,
-  # typed-array +item_type+, and nested object/array Params recursively.
-  #
-  # Round-trips losslessly with +to_json_schema(strict: false)+ over the
-  # Params-expressible subset of JSON Schema. Raises Riffer::ArgumentError
-  # on a schema using features outside that subset.
+  # Reconstructs a Params from a JSON Schema object — the inverse of
+  # +to_json_schema(strict: false)+. Raises Riffer::ArgumentError on features
+  # outside the Params-expressible subset of JSON Schema.
   #
   #   schema = params.to_json_schema(strict: false)
   #   Riffer::Params.from_json_schema(schema) # => equivalent Riffer::Params
@@ -129,12 +120,9 @@ class Riffer::Params
     validated
   end
 
-  # Converts all parameters to JSON Schema format.
-  #
-  # When +strict+ is true, every property appears in +required+ and
-  # optional properties are made nullable instead. This satisfies
-  # providers that enforce strict structured output schemas.
-  #
+  # Converts all parameters to JSON Schema format. When +strict+ is true, every
+  # property is listed in +required+ and optional ones are made nullable
+  # instead, satisfying providers that enforce strict structured output schemas.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)

data/lib/riffer/providers/amazon_bedrock.rb

@@ -3,23 +3,15 @@
 
 require "base64"
 
-# Amazon Bedrock provider for Claude and other foundation models.
-#
-# Requires the +aws-sdk-bedrockruntime+ gem to be installed.
-#
-# See https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/BedrockRuntime/Client.html
+# Amazon Bedrock provider for Claude and other foundation models. Requires the
+# +aws-sdk-bedrockruntime+ gem.
 class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
-  # Matches Anthropic models on Bedrock: bare ids like
-  # +anthropic.claude-3-5-sonnet-20241022-v2:0+ and cross-region prefixed
-  # ids like +us.anthropic.claude-sonnet-4-6+.
+  # Matches Anthropic models on Bedrock — bare (+anthropic.claude-...+) and
+  # cross-region (+us.anthropic.claude-...+) ids.
   ANTHROPIC_MODEL_PATTERN = /(?:^|\.)anthropic\./ #: Regexp
 
-  # Returns the preferred skill adapter for the given Bedrock model.
-  #
-  # Bedrock hosts models from multiple vendors. Anthropic models prefer
-  # XML-rendered catalogs; everything else falls back to the default
-  # Markdown adapter.
-  #
+  # Returns the skill adapter for the Bedrock model — XML for Anthropic models
+  # (which Bedrock hosts alongside other vendors'), else Markdown.
   #--
   #: (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter(model = nil)
@@ -27,8 +19,6 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     Riffer::Skills::MarkdownAdapter
   end
 
-  # Initializes the Amazon Bedrock provider.
-  #
   #--
   #: (?api_token: String?, ?region: String?, **untyped) -> void
   def initialize(api_token: nil, region: nil, **options)
@@ -57,12 +47,13 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     partitioned_messages = partition_messages(messages)
     tools = options[:tools]
     structured_output = options[:structured_output]
+    cache_control = options[:cache_control]
 
     params = {
       model_id: model,
       system: partitioned_messages[:system],
       messages: partitioned_messages[:conversation],
-      **options.except(:tools, :structured_output)
+      **options.except(:tools, :structured_output, :cache_control)
     } #: Hash[Symbol, untyped]
 
     if tools && !tools.empty?
@@ -88,9 +79,37 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       }
     end
 
+    apply_cache_point(params, cache_control) if cache_control
+
     params
   end
 
+  # Converse chains +tools -> system -> messages+, so a single +cachePoint+ at
+  # the end of the system array (or the tools array, when there is no system
+  # prompt) also caches the preceding sections.
+  #--
+  #: (Hash[Symbol, untyped], untyped) -> void
+  def apply_cache_point(params, cache_control)
+    cache_point = {cache_point: build_cache_point(cache_control)}
+    system = params[:system]
+    tools = params.dig(:tool_config, :tools)
+
+    if system && !system.empty?
+      system << cache_point
+    elsif tools && !tools.empty?
+      tools << cache_point
+    end
+  end
+
+  #--
+  #: (untyped) -> Hash[Symbol, untyped]
+  def build_cache_point(cache_control)
+    point = {type: "default"} #: Hash[Symbol, untyped]
+    ttl = cache_control.is_a?(Hash) ? cache_control[:ttl] : nil
+    point[:ttl] = ttl if ttl
+    point
+  end
+
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
@@ -106,7 +125,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens,
-      cache_creation_tokens: usage.cache_write_input_tokens,
+      cache_write_tokens: usage.cache_write_input_tokens,
       cache_read_tokens: usage.cache_read_input_tokens
     )
   end
@@ -177,15 +196,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     end
   end
 
-  # Re-raises a Bedrock stream exception event as the matching
-  # +Aws::BedrockRuntime::Errors+ service error. ConverseStream delivers API
-  # errors on the same channel as content, so without this a mid-stream
-  # failure would silently end the enumerator with no tokens or content.
-  #
-  # Detection is by class-name suffix: every Bedrock stream-exception struct
-  # is named +*Exception+ and has a matching +Aws::BedrockRuntime::Errors+
-  # class of the same name (generated via +DynamicErrors+ if not explicit).
-  # Non-exception events (e.g. +MessageStartEvent+) pass through silently.
+  # Re-raises a Bedrock stream-exception event as the matching
+  # +Aws::BedrockRuntime::Errors+ class. ConverseStream delivers API errors on
+  # the same channel as content, so without this a mid-stream failure would
+  # silently end the stream with no content.
   #--
   #: (untyped) -> void
   def raise_if_stream_exception!(event)
@@ -261,7 +275,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       token_usage: Riffer::Providers::TokenUsage.new(
         input_tokens: typed_event.usage.input_tokens,
         output_tokens: typed_event.usage.output_tokens,
-        cache_creation_tokens: typed_event.usage.cache_write_input_tokens,
+        cache_write_tokens: typed_event.usage.cache_write_input_tokens,
         cache_read_tokens: typed_event.usage.cache_read_input_tokens
       )
     )

data/lib/riffer/providers/anthropic.rb

@@ -1,11 +1,8 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Anthropic provider for Claude models via the Anthropic API.
-#
-# Requires the +anthropic+ gem to be installed.
-#
-# See https://github.com/anthropics/anthropic-sdk-ruby
+# Anthropic provider for Claude models via the Anthropic API. Requires the
+# +anthropic+ gem.
 class Riffer::Providers::Anthropic < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE = "web_search_20250305" #: String
 
@@ -17,8 +14,6 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     Riffer::Skills::XmlAdapter
   end
 
-  # Initializes the Anthropic provider.
-  #
   #--
   #: (?api_key: String?, **untyped) -> void
   def initialize(api_key: nil, **options)
@@ -91,7 +86,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens,
-      cache_creation_tokens: usage.cache_creation_input_tokens,
+      cache_write_tokens: usage.cache_creation_input_tokens,
       cache_read_tokens: usage.cache_read_input_tokens
     )
   end
@@ -298,7 +293,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       token_usage: Riffer::Providers::TokenUsage.new(
         input_tokens: usage.input_tokens,
         output_tokens: usage.output_tokens,
-        cache_creation_tokens: usage.cache_creation_input_tokens,
+        cache_write_tokens: usage.cache_creation_input_tokens,
         cache_read_tokens: usage.cache_read_input_tokens
       )
     )

data/lib/riffer/providers/azure_open_ai.rb

@@ -1,26 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Azure OpenAI provider for GPT models hosted on Azure.
-#
-# Requires the +openai+ gem to be installed.
-#
-# Credentials are resolved in order:
-# 1. Keyword arguments (+api_key+, +base_url+)
-# 2. Config (<tt>Riffer.config.azure_openai.api_key</tt> / <tt>.endpoint</tt>)
-# 3. Environment variables (+AZURE_OPENAI_API_KEY+ / +AZURE_OPENAI_ENDPOINT+)
-#
-#   Riffer::Providers::AzureOpenAI.new(
-#     api_key: "key",
-#     base_url: "https://my-resource.openai.azure.com"
-#   )
-#
+# Azure OpenAI provider for GPT models hosted on Azure. Requires the +openai+
+# gem. Credentials resolve from kwargs, then config, then
+# +AZURE_OPENAI_API_KEY+ / +AZURE_OPENAI_ENDPOINT+.
 class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
-  # Initializes the Azure OpenAI provider.
-  #
-  # [api_key] Azure OpenAI API key. Falls back to config, then +AZURE_OPENAI_API_KEY+.
-  # [base_url] Azure OpenAI endpoint URL. Falls back to config, then +AZURE_OPENAI_ENDPOINT+.
-  #
   #--
   #: (**untyped) -> void
   def initialize(**options)