riffer 0.48.0 → 0.49.0

data/lib/riffer/mcp/search_tool.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Searches available MCP tools by name or description.
 class Riffer::Mcp::SearchTool < Riffer::Tool
   IDENTIFIER = "mcp_search"
 
-  # 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)] # @dynamic discovered_tools
 
     #--
@@ -25,7 +22,6 @@ class Riffer::Mcp::SearchTool < Riffer::Tool
     required :query, String, description: "Non-empty substring to filter tools by name or description."
   end
 
-  # Searches progressive MCP tools and returns a +Result+ with +discovered_tools+.
   #--
   #: (context: Riffer::Agent::Context?, query: String) -> Riffer::Tools::Response
   def call(context:, query:)

data/lib/riffer/mcp/tool.rb

@@ -1,23 +1,20 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Base class for MCP-generated tools.
 class Riffer::Mcp::Tool < Riffer::Tool
   # @rbs self.@mcp_server_tool_name: String?
   # @rbs self.@input_schema: Hash[Symbol, untyped]?
 
-  # Returns the unprefixed tool name used for +tools/call+ on the MCP server.
   #--
   #: () -> String
   def self.mcp_server_tool_name
     @mcp_server_tool_name || raise(NotImplementedError, "#{self} must set @mcp_server_tool_name")
   end
 
-  # Returns the server-published input schema, falling back to the params DSL.
-  # MCP schemas are server-defined, so +strict+ is not applied to them.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def self.parameters_schema(strict: false)
+    # MCP schemas are server-defined, so +strict+ is not applied to them.
     @input_schema || super
   end
 end

data/lib/riffer/mcp/tool_factory.rb

@@ -1,15 +1,9 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Generates anonymous Riffer::Mcp::Tool subclasses from MCP tool definitions.
-# Generated tools delegate +#call+ to the MCP client and skip Riffer's param
-# validation — the MCP server validates inputs.
 module Riffer::Mcp::ToolFactory
   extend self
 
-  # Builds one Riffer::Mcp::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::Mcp::Tool)]
   def build(manifest_name, client, tool_defs)
@@ -25,6 +19,8 @@ module Riffer::Mcp::ToolFactory
 
   #: (String, Riffer::Mcp::Client, Hash[Symbol, untyped]) -> singleton(Riffer::Mcp::Tool)
   def build_tool_class(manifest_name, client, descriptor)
+    # Prefixed to avoid cross-server collisions; the server-side name stays on
+    # mcp_server_tool_name.
     prefixed = "#{sanitize_name_component(manifest_name)}__#{sanitize_name_component(descriptor[:name])}"
 
     # steep does not model Class.new's class_eval semantics — the block body
@@ -37,6 +33,7 @@ module Riffer::Mcp::ToolFactory
       @description = descriptor[:description]
       @input_schema = descriptor[:input_schema]
 
+      # No Riffer param validation — the MCP server validates inputs.
       define_method(:call) do |context:, **kwargs|
         text(client.tools_call(self.class.mcp_server_tool_name, kwargs))
       end

data/lib/riffer/mcp.rb

@@ -1,49 +1,28 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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/MCP.md+.
-#
-#   Riffer::Mcp.register(
-#     name: "github",
-#     tags: [:github],
-#     endpoint: "https://mcp.github.com",
-#     discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
-#   )
-#
-#   class MyAgent < Riffer::Agent
-#     model "openai/gpt-4o"
-#     use_mcp :github
-#   end
-#
 module Riffer::Mcp
   extend self
 
-  # Base error for all MCP-related failures.
   class Error < Riffer::Error; end
 
   # Raised when +Riffer.config.mcp.credentials+ returns +nil+ during +tools/call+
-  # after the server's tools were included for this run.
+  # after the server's tools were already included for this run.
   class CredentialsDeniedError < Error; end
 
-  # Registers an MCP server, blocking until tool discovery completes. Raises
-  # on discovery failure.
+  # Blocks until tool discovery completes.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
   def register(manifest_or_hash)
     Registry.register(manifest_or_hash)
   end
 
-  # Removes a registration by name; subsequent agent runs won't see its tools.
   #--
   #: (String) -> void
   def unregister(name)
     Registry.unregister(name)
   end
 
-  # Returns all current registrations keyed by name.
-  #
   #--
   #: () -> Hash[String, Riffer::Mcp::Registration]
   def registrations

data/lib/riffer/messages/assistant/reasoning_part.rb

@@ -1,35 +1,21 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents one block of model reasoning attached to an assistant message.
-# riffer stores and replays a part verbatim rather than interpreting it, so a
-# provider that requires its own thinking blocks back gets them unchanged.
+# Stored and replayed verbatim, never interpreted, so a provider that requires its own thinking
+# blocks back gets them unchanged.
 class Riffer::Messages::Assistant::ReasoningPart
   TYPES = %i[text summary encrypted].freeze #: Array[Symbol]
 
-  # What the part carries: readable reasoning (+:text+), a provider-condensed
-  # digest (+:summary+), or an opaque payload (+:encrypted+).
   attr_reader :type #: Symbol # @dynamic type
-
-  # The reasoning prose, for +:text+ and +:summary+ parts.
   attr_reader :text #: String? # @dynamic text
-
-  # The opaque payload, for +:encrypted+ parts.
   attr_reader :data #: String? # @dynamic data
-
-  # The provider's signature over the part, when it issues one.
   attr_reader :signature #: String? # @dynamic signature
-
-  # The provider's identifier for the part, when it issues one.
   attr_reader :id #: String? # @dynamic id
 
-  # The wire format of the part, owned by the provider adapter that produced it
-  # (e.g. <tt>"anthropic-claude-v1"</tt>). Adapters replay only the formats they
-  # recognize, so it is never validated here.
+  # Owned by the producing adapter (e.g. <tt>"anthropic-claude-v1"</tt>); adapters replay only the
+  # formats they recognize, so it is never validated here.
   attr_reader :format #: String? # @dynamic format
 
-  # Builds a ReasoningPart from a hash, or returns +part+ unchanged when it is
-  # already a ReasoningPart.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart)) -> Riffer::Messages::Assistant::ReasoningPart
   def self.from_hash(part)
@@ -45,7 +31,6 @@ class Riffer::Messages::Assistant::ReasoningPart
     )
   end
 
-  # Raises Riffer::ArgumentError on a +type+ outside TYPES.
   #--
   #: (type: Symbol, ?text: String?, ?data: String?, ?signature: String?, ?id: String?, ?format: String?) -> void
   def initialize(type:, text: nil, data: nil, signature: nil, id: nil, format: nil)
@@ -62,8 +47,6 @@ class Riffer::Messages::Assistant::ReasoningPart
     @format = format
   end
 
-  # Serializes the part to a hash, omitting the fields it doesn't carry.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/messages/assistant/tool_call.rb

@@ -1,20 +1,14 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents one tool invocation the model requested on an assistant message.
 class Riffer::Messages::Assistant::ToolCall
-  # The provider's identifier for the call, echoed back on the tool result.
   attr_reader :call_id #: String # @dynamic call_id
 
-  # The name of the tool to invoke.
   attr_reader :name #: String # @dynamic name
 
-  # The JSON-encoded arguments, exactly as the provider emitted them.
+  # JSON-encoded, exactly as the provider emitted them.
   attr_reader :arguments #: String # @dynamic arguments
 
-  # Builds a ToolCall from a hash, or returns +call+ unchanged when it is
-  # already a ToolCall. Raises Riffer::ArgumentError when the hash is missing
-  # a field.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant::ToolCall)) -> Riffer::Messages::Assistant::ToolCall
   def self.from_hash(call)
@@ -35,8 +29,6 @@ class Riffer::Messages::Assistant::ToolCall
     @arguments = arguments
   end
 
-  # Serializes the call to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/messages/assistant.rb

@@ -1,15 +1,10 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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
-  # The reasoning part types +reasoning_text+ reads; the rest carry no prose.
+  # The other reasoning part types carry no prose.
   REASONING_TEXT_TYPES = %i[text summary].freeze #: Array[Symbol]
 
-  # Builds an Assistant message from a hash, or returns +msg+ unchanged when it
-  # is already an Assistant message. Raises Riffer::ArgumentError on an invalid
-  # tool call, reasoning part, or +finish_reason+.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Messages::Assistant)) -> Riffer::Messages::Assistant
   def self.from_hash(msg)
@@ -27,29 +22,18 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     )
   end
 
-  # Array of tool calls requested by the assistant.
   attr_reader :tool_calls #: Array[Riffer::Messages::Assistant::ToolCall] # @dynamic tool_calls
 
-  # The model's reasoning blocks for this response, in the order the provider
-  # emitted them.
   attr_reader :reasoning #: Array[Riffer::Messages::Assistant::ReasoningPart] # @dynamic reasoning
 
-  # Token usage data for this response.
   attr_reader :token_usage #: Riffer::Providers::TokenUsage? # @dynamic token_usage
 
-  # Parsed structured output hash, or nil when not applicable.
   attr_reader :structured_output #: Hash[Symbol, untyped]? # @dynamic structured_output
 
-  # Normalized reason the provider finished this response, when reported (see
-  # <tt>Riffer::Providers::FinishReason::VALUES</tt>).
   attr_reader :finish_reason #: Symbol? # @dynamic finish_reason
 
-  # The provider's raw finish-reason value behind +finish_reason+, when one
-  # exists on the wire.
   attr_reader :finish_reason_raw #: String? # @dynamic finish_reason_raw
 
-  # Raises Riffer::ArgumentError when +finish_reason+ is outside the
-  # normalized vocabulary.
   #--
   #: (
   #    String,
@@ -109,8 +93,6 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     !@reasoning.empty?
   end
 
-  # The readable reasoning across this message's +:text+ and +:summary+ parts,
-  # joined by blank lines, or nil when it carries none.
   #--
   #: () -> String?
   def reasoning_text
@@ -128,8 +110,6 @@ class Riffer::Messages::Assistant < Riffer::Messages::Base
     )
   end
 
-  # Converts the message to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/messages/base.rb

@@ -3,10 +3,7 @@
 
 require "securerandom"
 
-# 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)
@@ -23,10 +20,8 @@ class Riffer::Messages::Base
     end
   end
 
-  # The message content.
   attr_reader :content #: String # @dynamic content
 
-  # The message id, or nil when +Riffer.config.message_id_strategy+ is +:none+.
   attr_reader :id #: String? # @dynamic id
 
   #--
@@ -36,8 +31,6 @@ class Riffer::Messages::Base
     @id = id || generate_id
   end
 
-  # Converts the message to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
@@ -46,23 +39,18 @@ class Riffer::Messages::Base
     hash
   end
 
-  # Returns the message role.
   #--
   #: () -> Symbol
   def role
     raise NotImplementedError, "Subclasses must implement #role"
   end
 
-  # 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. +Tool+ messages are never
-  # merged.
   #--
   #: (untyped) -> Riffer::Messages::Base
   def +(other)

data/lib/riffer/messages/system.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a system message (instructions) in a conversation.
 class Riffer::Messages::System < Riffer::Messages::Base
-  # Builds a System message from a hash, or returns +msg+ unchanged when it is
-  # already a System message.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Messages::System)) -> Riffer::Messages::System
   def self.from_hash(msg)

data/lib/riffer/messages/tool.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a tool execution result in a conversation.
 class Riffer::Messages::Tool < Riffer::Messages::Base
-  # Builds a Tool message from a hash, or returns +msg+ unchanged when it is
-  # already a Tool message.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Messages::Tool)) -> Riffer::Messages::Tool
   def self.from_hash(msg)
@@ -20,17 +17,9 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
     )
   end
 
-  # The ID of the tool call this result responds to.
   attr_reader :tool_call_id #: String # @dynamic tool_call_id
-
-  # The name of the tool that was called.
   attr_reader :name #: String # @dynamic name
-
-  # The error message if the tool execution failed.
   attr_reader :error #: String? # @dynamic error
-
-  # The type of error (:unknown_tool, :validation_error, :execution_error,
-  # :timeout_error, :unhandled_error).
   attr_reader :error_type #: Symbol? # @dynamic error_type
 
   #--
@@ -43,8 +32,6 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
     @error_type = error_type
   end
 
-  # Returns true if the tool execution resulted in an error.
-  #
   #--
   #: () -> bool
   def error?
@@ -57,8 +44,6 @@ class Riffer::Messages::Tool < Riffer::Messages::Base
     :tool
   end
 
-  # Converts the message to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h

data/lib/riffer/messages/user/file_part.rb

@@ -4,8 +4,6 @@
 require "base64"
 require "uri"
 
-# Represents a file attachment (image or document) — from a URL (+from_url+) or
-# raw base64 data (+new+).
 class Riffer::Messages::User::FilePart
   # @rbs @url_string: String?
   # @rbs @data: String?
@@ -28,17 +26,12 @@ class Riffer::Messages::User::FilePart
   SUPPORTED_MEDIA_TYPES = MEDIA_TYPES.values.uniq.freeze #: Array[String]
   SHA256_PATTERN = /\A[0-9a-f]{64}\z/i #: Regexp
 
-  # The MIME type of the file.
   attr_reader :media_type #: String # @dynamic media_type
 
-  # The filename, if available.
   attr_reader :filename #: String? # @dynamic filename
 
-  # The expected SHA-256 of the file contents, if the caller supplied one.
   attr_reader :sha256 #: String? # @dynamic sha256
 
-  # Raises Riffer::ArgumentError unless +data+ or +url+ is given and
-  # +media_type+ is supported.
   #--
   #: (media_type: String, ?data: String?, ?filename: String?, ?url: String?, ?sha256: String?) -> void
   def initialize(media_type:, data: nil, filename: nil, url: nil, sha256: nil)
@@ -59,17 +52,12 @@ class Riffer::Messages::User::FilePart
     @url_string = url
   end
 
-  # 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?, ?filename: String?, ?sha256: String?) -> Riffer::Messages::User::FilePart
   def self.from_url(url, media_type: nil, filename: nil, sha256: nil)
     new(url: url, media_type: media_type || detect_media_type(url), filename: filename, sha256: sha256)
   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::User::FilePart)) -> Riffer::Messages::User::FilePart
   def self.from_hash(file)
@@ -90,7 +78,6 @@ class Riffer::Messages::User::FilePart
     end
   end
 
-  # Raises Riffer::ArgumentError when the URL's extension isn't a known media type.
   #--
   #: (String) -> String
   def self.detect_media_type(url)
@@ -99,8 +86,6 @@ class Riffer::Messages::User::FilePart
   end
   private_class_method :detect_media_type
 
-  # The base64-encoded contents - caller-supplied, or filled in by the file
-  # resolver after a download.  Nil for a URL source riffer hasn't fetched.
   #--
   #: () -> String?
   def data
@@ -124,60 +109,47 @@ class Riffer::Messages::User::FilePart
     @data_bytes = bytes
   end
 
-  # Whether data was supplied directly, as opposed to filled in later by the
-  # file resolver after a download
   #: () -> bool
   def inline_data?
     !@data.nil?
   end
 
-  # Caches bytes fetched for a URL source.  Deliberately absent from +to_h+:
-  # the agent loop re-sends history on every turn, so the cache saves refreshing
-  # the same file, while persisted history stays free of megabytes of base64
   #--
   #: (String) -> void
   def cache_downloaded_data(data)
     @downloaded_data = data
   end
 
-  # Returns the URL if the source was a URL, nil otherwise.
-  #
   #--
   #: () -> String?
   def url
     @url_string
   end
 
-  # Returns true if the source was a URL.
-  #
   #--
   #: () -> bool
   def url?
     !@url_string.nil?
   end
 
-  # Returns true if the file is an image.
-  #
   #--
   #: () -> bool
   def image?
     media_type.start_with?("image/")
   end
 
-  # Returns true if the file is a document (not an image).
-  #
   #--
   #: () -> bool
   def document?
     !image?
   end
 
-  # Serializes the FilePart to a hash.
-  #
   #--
   #: () -> Hash[Symbol, untyped]
   def to_h
     hash = { media_type: media_type } #: Hash[Symbol, untyped]
+    # Downloaded data is left out so persisted history stays free of megabytes
+    # of base64; the in-memory cache still spares refetching on every turn.
     hash[:data] = @data if @data
     hash[:url] = @url_string if @url_string
     hash[:filename] = filename if filename

data/lib/riffer/messages/user.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Represents a user message in a conversation.
 class Riffer::Messages::User < Riffer::Messages::Base
-  # Builds a User message from a hash, or returns +msg+ unchanged when it is
-  # already a User message. Raises Riffer::ArgumentError on an invalid file.
   #--
   #: ((Hash[Symbol, untyped] | Riffer::Messages::User)) -> Riffer::Messages::User
   def self.from_hash(msg)
@@ -14,7 +11,6 @@ class Riffer::Messages::User < Riffer::Messages::Base
     new(msg[:content], id: msg[:id], files: files)
   end
 
-  # File attachments for this message.
   attr_reader :files #: Array[Riffer::Messages::User::FilePart] # @dynamic files
 
   #--

data/lib/riffer/params/boolean.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# Sentinel type for declaring boolean parameters — Ruby has no +Boolean+ class
-# (+true+/+false+ are +TrueClass+/+FalseClass+).
-#
-#   required :verbose, Riffer::Params::Boolean
-#
+# Ruby has no +Boolean+ class, so params declare booleans with this sentinel.
 module Riffer::Params::Boolean
 end

data/lib/riffer/params/param.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 # rbs_inline: enabled
 
-# 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 = {
     String => "string",
     Integer => "integer",
@@ -16,11 +13,8 @@ class Riffer::Params::Param
     Hash => "object",
   }.freeze #: Hash[Module, String]
 
-  # 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 (inverse of TYPE_MAPPINGS),
-  # collapsing the three boolean spellings onto Riffer::Params::Boolean.
   JSON_TYPE_MAPPINGS = {
     "string" => String,
     "integer" => Integer,
@@ -30,32 +24,22 @@ class Riffer::Params::Param
     "object" => Hash,
   }.freeze #: Hash[String, Module]
 
-  # The parameter name.
   attr_reader :name #: Symbol # @dynamic name
 
-  # The Ruby type.
   attr_reader :type #: Module # @dynamic type
 
-  # Whether the parameter is required.
   attr_reader :required #: bool # @dynamic required
 
-  # The parameter description, if any.
   attr_reader :description #: String? # @dynamic description
 
-  # Allowed values, if constrained.
   attr_reader :enum #: Array[untyped]? # @dynamic enum
 
-  # The default value, if any.
   attr_reader :default #: untyped # @dynamic default
 
-  # Element type for a typed array (+of:+).
   attr_reader :item_type #: Module? # @dynamic item_type
 
-  # Nested Params for object / array-of-object types.
   attr_reader :nested_params #: Riffer::Params? # @dynamic nested_params
 
-  # 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:)
@@ -88,9 +72,6 @@ class Riffer::Params::Param
   end
   private_class_method :resolve_nesting
 
-  # 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)
@@ -112,8 +93,6 @@ class Riffer::Params::Param
     @nested_params = nested_params
   end
 
-  # Validates that a value matches the expected type.
-  #
   #--
   #: (untyped) -> bool
   def valid_type?(value)
@@ -128,28 +107,20 @@ class Riffer::Params::Param
     end
   end
 
-  # Returns the JSON Schema type name for this parameter.
-  #
   #--
   #: () -> String
   def type_name
     TYPE_MAPPINGS[type] || type.to_s.downcase
   end
 
-  # 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>. Raises
-  # Riffer::ArgumentError when +strict+ and a Hash param has no block or an
-  # Array param has neither a block nor <tt>of:</tt>, since strict providers
-  # reject objects without +properties+ and arrays without +items+.
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)
     validate_strict_shape! if strict
+    # Nullable so strict providers can distinguish absent from present.
     nullable = strict && !required
 
+    # Providers like Anthropic reject a nullable type union combined with enum.
     if nullable && enum
       schema = { anyOf: [{ type: type_name, enum: enum }, { type: "null" }] } #: Hash[Symbol, untyped]
       schema[:description] = description if description
@@ -196,6 +167,7 @@ class Riffer::Params::Param
   #--
   #: () -> void
   def validate_strict_shape!
+    # Strict providers reject objects without properties and arrays without items.
     if type == Hash && nested_params.nil?
       raise Riffer::ArgumentError,
             "#{name}: a Hash param requires a block defining its properties under strict schemas"