riffer 0.31.0 → 0.32.0

data/sig/generated/riffer/mcp/registration.rbs

@@ -1,9 +1,7 @@
 # Generated from lib/riffer/mcp/registration.rb with RBS::Inline
 
-# Per-server state managed by Riffer::Mcp::Registry.
-#
-# Created when a server is registered. Discovers tools via the MCP
-# +tools/list+ call, then generates tool classes.
+# Per-server state managed by Riffer::Mcp::Registry — discovers tools via
+# +tools/list+ and generates tool classes when a server is registered.
 class Riffer::Mcp::Registration
   @cancelled: bool
 
@@ -39,12 +37,6 @@ class Riffer::Mcp::Registration
 
   private
 
-  # Runs tool discovery using the configured Runner.
-  #
-  # With +Runner::Sequential+ (default) discovery blocks inline. With
-  # +Runner::Threaded+ discovery runs on a pool thread but +map+ still
-  # blocks the caller — useful for Rails connection-pool isolation.
-  #
   # --
   # : () -> void
   def run_discovery: () -> void

data/sig/generated/riffer/mcp/registry.rbs

@@ -1,39 +1,32 @@
 # Generated from lib/riffer/mcp/registry.rb with RBS::Inline
 
-# Thread-safe global store for MCP server registrations.
-#
-# Keyed by manifest name. All public methods are mutex-guarded.
+# Thread-safe global store for MCP server registrations, keyed by manifest name.
 module Riffer::Mcp::Registry
-  self.@mutex: Thread::Mutex
+  @mutex: Thread::Mutex
 
-  self.@store: Hash[String, Riffer::Mcp::Registration]
+  @store: Hash[String, Riffer::Mcp::Registration]
 
-  # Registers an MCP server and starts async tool discovery.
-  #
-  # Accepts a Manifest instance or a hash of manifest keyword arguments.
-  # Replaces any existing registration with the same name.
-  #
+  # Registers an MCP server and starts async tool discovery, replacing any
+  # existing registration with the same name.
   # --
   # : ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
-  def self.register: (Hash[Symbol, untyped] | Riffer::Mcp::Manifest) -> Riffer::Mcp::Registration
+  def register: (Hash[Symbol, untyped] | Riffer::Mcp::Manifest) -> Riffer::Mcp::Registration
 
   # Removes a registration by name.
   #
   # --
   # : ((String | Symbol)) -> void
-  def self.unregister: (String | Symbol) -> void
+  def unregister: (String | Symbol) -> void
 
   # Returns a frozen snapshot of all current registrations.
   #
   # --
   # : () -> Hash[String, Riffer::Mcp::Registration]
-  def self.registrations: () -> Hash[String, Riffer::Mcp::Registration]
+  def registrations: () -> Hash[String, Riffer::Mcp::Registration]
 
-  # Returns all registrations whose manifest tags intersect with the given tags.
-  #
-  # Tags are normalized to symbols before matching.
-  #
+  # Returns all registrations whose manifest tags intersect the given tags
+  # (normalized to symbols).
   # --
   # : (Array[Symbol]) -> Array[Riffer::Mcp::Registration]
-  def self.find_by_tags: (Array[Symbol]) -> Array[Riffer::Mcp::Registration]
+  def find_by_tags: (Array[Symbol]) -> Array[Riffer::Mcp::Registration]
 end

data/sig/generated/riffer/mcp/search_tool.rbs

@@ -0,0 +1,26 @@
+# Generated from lib/riffer/mcp/search_tool.rb with RBS::Inline
+
+# Searches available MCP tools by name or description.
+class Riffer::Mcp::SearchTool < Riffer::Tool
+  IDENTIFIER: ::String
+
+  # Successful search response carrying the matched tool classes.
+  class Result < Riffer::Tools::Response
+    # Tool classes that matched the search query.
+    attr_reader discovered_tools: Array[singleton(Riffer::Tool)]
+
+    # --
+    # : (String, Array[singleton(Riffer::Tool)]) -> void
+    def initialize: (String, Array[singleton(Riffer::Tool)]) -> void
+  end
+
+  # Searches progressive MCP tools and returns a +Result+ with +discovered_tools+.
+  # --
+  # : (context: Riffer::Agent::Context?, query: String) -> Riffer::Tools::Response
+  def call: (context: Riffer::Agent::Context?, query: String) -> Riffer::Tools::Response
+
+  private
+
+  # : (Array[singleton(Riffer::Tool)], String) -> Array[singleton(Riffer::Tool)]
+  def filter: (Array[singleton(Riffer::Tool)], String) -> Array[singleton(Riffer::Tool)]
+end

data/sig/generated/riffer/mcp/tool_factory.rbs

@@ -1,25 +1,20 @@
 # Generated from lib/riffer/mcp/tool_factory.rb with RBS::Inline
 
 # Generates anonymous Riffer::Tool subclasses from MCP tool definitions.
-#
-# Each generated class:
-# - Has +.name+, +.description+, and +.parameters_schema+ derived from the MCP tool definition.
-# - Delegates +#call+ to the MCP client's +tools_call+ method.
-# - Skips Riffer's param validation — the MCP server validates inputs.
+# Generated tools delegate +#call+ to the MCP client and skip Riffer's param
+# validation — the MCP server validates inputs.
 module Riffer::Mcp::ToolFactory
-  # Builds one Riffer::Tool subclass per tool definition.
-  #
-  # Tool names are prefixed with the manifest name to avoid collisions
-  # across MCP servers (e.g. +"jira__search"+). The original server-side
-  # name is available via +.mcp_server_tool_name+.
-  #
+  # Builds one Riffer::Tool subclass per tool definition, prefixing names with
+  # the manifest name to avoid cross-server collisions (e.g. +jira__search+);
+  # the server-side name stays on +.mcp_server_tool_name+.
   # --
   # : (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Tool)]
-  def self.build: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Tool)]
+  def build: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Tool)]
+
+  private
 
-  # Replaces characters that are unsafe in LLM tool names.
   # : (String) -> String
-  def self.sanitize_name_component: (String) -> String
+  def sanitize_name_component: (String) -> String
 
-  def self.build_tool_class: (untyped manifest_name, untyped client, untyped td) -> untyped
+  def build_tool_class: (untyped manifest_name, untyped client, untyped td) -> untyped
 end

data/sig/generated/riffer/mcp.rbs

@@ -1,9 +1,8 @@
 # Generated from lib/riffer/mcp.rb with RBS::Inline
 
-# Riffer::Mcp provides integration with Model Context Protocol (MCP) servers.
-#
-# Register MCP servers globally; agents opt-in by tag via the +use_mcp+ DSL.
-# Tags are application-defined; see +docs/14_MCP.md+ (Tags section).
+# Integration with Model Context Protocol (MCP) servers. Register servers
+# globally; agents opt-in by tag via the +use_mcp+ DSL. Tags are
+# application-defined; see +docs/14_MCP.md+.
 #
 #   Riffer::Mcp.register(
 #     name: "github",
@@ -26,26 +25,20 @@ module Riffer::Mcp
   class CredentialsDeniedError < Error
   end
 
-  # Registers an MCP server, blocking until tool discovery completes.
-  #
-  # Raises on discovery failure. Pass a +Manifest+ instance or a hash with
-  # the same keys.
-  #
+  # Registers an MCP server, blocking until tool discovery completes. Raises
+  # on discovery failure.
   # --
   # : ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
-  def self.register: (Hash[Symbol, untyped] | Riffer::Mcp::Manifest) -> Riffer::Mcp::Registration
+  def register: (Hash[Symbol, untyped] | Riffer::Mcp::Manifest) -> Riffer::Mcp::Registration
 
-  # Removes a registration by name.
-  #
-  # Subsequent agent runs will not see tools from this server.
-  #
+  # Removes a registration by name; subsequent agent runs won't see its tools.
   # --
   # : (String) -> void
-  def self.unregister: (String) -> void
+  def unregister: (String) -> void
 
-  # Returns all current registrations keyed by name (for introspection).
+  # Returns all current registrations keyed by name.
   #
   # --
   # : () -> Hash[String, Riffer::Mcp::Registration]
-  def self.registrations: () -> Hash[String, Riffer::Mcp::Registration]
+  def registrations: () -> Hash[String, Riffer::Mcp::Registration]
 end

data/sig/generated/riffer/messages/assistant.rbs

@@ -1,13 +1,7 @@
 # Generated from lib/riffer/messages/assistant.rb with RBS::Inline
 
-# Represents an assistant (LLM) message in a conversation.
-#
-# May include tool calls when the LLM requests tool execution.
-#
-#   msg = Riffer::Messages::Assistant.new("Hello!")
-#   msg.role        # => :assistant
-#   msg.content     # => "Hello!"
-#   msg.tool_calls  # => []
+# Represents an assistant (LLM) message in a conversation; may include tool
+# calls when the LLM requests tool execution.
 class Riffer::Messages::Assistant < Riffer::Messages::Base
   class ToolCall < Struct[untyped]
     attr_accessor call_id(): untyped

data/sig/generated/riffer/messages/base.rbs

@@ -1,9 +1,13 @@
 # Generated from lib/riffer/messages/base.rb with RBS::Inline
 
-# 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: (Hash[Symbol, untyped] | Riffer::Messages::Base) -> Riffer::Messages::Base
+
   # The message content.
   attr_reader content: String
 
@@ -21,27 +25,18 @@ class Riffer::Messages::Base
   def to_h: () -> Hash[Symbol, untyped]
 
   # Returns the message role.
-  #
-  # Raises NotImplementedError if not implemented by subclass.
-  #
   # --
   # : () -> Symbol
   def role: () -> Symbol
 
-  # 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?: () -> bool
 
-  # 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 +: (untyped) -> Riffer::Messages::Base

data/sig/generated/riffer/messages/file_part.rbs

@@ -1,14 +1,7 @@
 # Generated from lib/riffer/messages/file_part.rb with RBS::Inline
 
-# 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
   @url_string: String?
 
@@ -22,28 +15,25 @@ 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: String, ?data: String?, ?filename: String?, ?url: String?) -> void
 
-  # 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: (String, ?media_type: String?) -> Riffer::Messages::FilePart
 
+  # 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: (Hash[Symbol, untyped] | Riffer::Messages::FilePart) -> Riffer::Messages::FilePart
+
   # Returns the base64-encoded data, or nil for URL-only sources.
   attr_reader data: String?
 

data/sig/generated/riffer/messages/system.rbs

@@ -1,10 +1,6 @@
 # Generated from lib/riffer/messages/system.rb with RBS::Inline
 
 # 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/sig/generated/riffer/messages/tool.rbs

@@ -1,15 +1,6 @@
 # Generated from lib/riffer/messages/tool.rb with RBS::Inline
 
 # 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/sig/generated/riffer/messages/user.rbs

@@ -1,19 +1,10 @@
 # Generated from lib/riffer/messages/user.rb with RBS::Inline
 
 # 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: (String, ?id: String?, ?files: Array[Riffer::Messages::FilePart]) -> void

data/sig/generated/riffer/messages.rbs

@@ -1,11 +1,4 @@
 # Generated from lib/riffer/messages.rb with RBS::Inline
 
-# 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/sig/generated/riffer/params/boolean.rbs

@@ -1,9 +1,7 @@
 # Generated from lib/riffer/params/boolean.rb with RBS::Inline
 
-# 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
 module Riffer::Params::Boolean

data/sig/generated/riffer/params/param.rbs

@@ -1,8 +1,7 @@
 # Generated from lib/riffer/params/param.rb with RBS::Inline
 
-# 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: Hash[Module, String]
@@ -10,54 +9,47 @@ class Riffer::Params::Param
   # Primitive types allowed for the <tt>of:</tt> keyword on Array params
   PRIMITIVE_TYPES: 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: 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: (Symbol, Hash[Symbol, untyped], required: bool) -> Riffer::Params::Param
 
-  # 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: (Module, Hash[Symbol, untyped]) -> [ Module?, Riffer::Params? ]
 
-  # 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: (untyped) -> Module
@@ -78,21 +70,11 @@ class Riffer::Params::Param
   # : () -> String
   def type_name: () -> String
 
-  # 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: bool) -> Hash[Symbol, untyped]

data/sig/generated/riffer/params.rbs

@@ -1,32 +1,23 @@
 # Generated from lib/riffer/params.rb with RBS::Inline
 
-# 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"
 #     optional :units, String, default: "celsius", enum: ["celsius", "fahrenheit"]
 #   end
 class Riffer::Params
+  # The defined parameters.
   attr_reader parameters: Array[Riffer::Params::Param]
 
   # --
   # : () -> void
   def initialize: () -> void
 
-  # 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
@@ -55,12 +46,9 @@ class Riffer::Params
   # : (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def validate: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
-  # 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: bool) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/amazon_bedrock.rbs

@@ -1,28 +1,18 @@
 # Generated from lib/riffer/providers/amazon_bedrock.rb with RBS::Inline
 
-# 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: 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: (?String?) -> singleton(Riffer::Skills::Adapter)
 
-  # Initializes the Amazon Bedrock provider.
-  #
   # --
   # : (?api_token: String?, ?region: String?, **untyped) -> void
   def initialize: (?api_token: String?, ?region: String?, **untyped) -> void
@@ -33,6 +23,17 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # : (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
+  # 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: (Hash[Symbol, untyped], untyped) -> void
+
+  # --
+  # : (untyped) -> Hash[Symbol, untyped]
+  def build_cache_point: (untyped) -> Hash[Symbol, untyped]
+
   # --
   # : (Hash[Symbol, untyped]) -> untyped
   def execute_generate: (Hash[Symbol, untyped]) -> untyped
@@ -53,15 +54,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   # : (Hash[Symbol, untyped], Enumerator::Yielder) -> void
   def execute_stream: (Hash[Symbol, untyped], Enumerator::Yielder) -> void
 
-  # 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!: (untyped) -> void

data/sig/generated/riffer/providers/anthropic.rbs

@@ -1,10 +1,7 @@
 # Generated from lib/riffer/providers/anthropic.rb with RBS::Inline
 
-# 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: String
 
@@ -14,8 +11,6 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   # : (?String?) -> singleton(Riffer::Skills::Adapter)
   def self.skills_adapter: (?String?) -> singleton(Riffer::Skills::Adapter)
 
-  # Initializes the Anthropic provider.
-  #
   # --
   # : (?api_key: String?, **untyped) -> void
   def initialize: (?api_key: String?, **untyped) -> void