riffer 0.28.0 → 0.29.1

data/lib/riffer/params.rb

@@ -12,7 +12,7 @@
 #   end
 #
 class Riffer::Params
-  attr_reader :parameters #: Array[Riffer::Param]
+  attr_reader :parameters #: Array[Riffer::Params::Param]
 
   #--
   #: () -> void
@@ -23,10 +23,10 @@ class Riffer::Params
   # Defines a required parameter.
   #
   #--
-  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ () -> void } -> void
+  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
   def required(name, type, description: nil, enum: nil, of: nil, &block)
     nested = build_nested(type, of, &block)
-    @parameters << Riffer::Param.new(
+    @parameters << Riffer::Params::Param.new(
       name: name,
       type: type,
       required: true,
@@ -40,10 +40,10 @@ class Riffer::Params
   # Defines an optional parameter.
   #
   #--
-  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ () -> void } -> void
+  #: (Symbol, Class, ?description: String?, ?enum: Array[untyped]?, ?default: untyped, ?of: Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> void
   def optional(name, type, description: nil, enum: nil, default: nil, of: nil, &block)
     nested = build_nested(type, of, &block)
-    @parameters << Riffer::Param.new(
+    @parameters << Riffer::Params::Param.new(
       name: name,
       type: type,
       required: false,
@@ -62,8 +62,8 @@ class Riffer::Params
   #--
   #: (Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def validate(arguments)
-    validated = {}
-    errors = []
+    validated = {} #: Hash[Symbol, untyped]
+    errors = [] #: Array[String]
 
     @parameters.each do |param|
       value = arguments[param.name]
@@ -107,8 +107,8 @@ class Riffer::Params
   #--
   #: (?strict: bool) -> Hash[Symbol, untyped]
   def to_json_schema(strict: false)
-    properties = {}
-    required_params = []
+    properties = {} #: Hash[String, untyped]
+    required_params = [] #: Array[String]
 
     @parameters.each do |param|
       properties[param.name.to_s] = param.to_json_schema(strict: strict)
@@ -126,7 +126,7 @@ class Riffer::Params
   private
 
   #--
-  #: (Class, Class?) ?{ () -> void } -> Riffer::Params?
+  #: (Class, Class?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def build_nested(type, of, &block)
     if of && block
       raise Riffer::ArgumentError, "cannot use both of: and a block"
@@ -136,9 +136,9 @@ class Riffer::Params
       unless type == Array
         raise Riffer::ArgumentError, "of: can only be used with Array type, got #{type}"
       end
-      unless Riffer::Param::PRIMITIVE_TYPES.include?(of)
+      unless Riffer::Params::Param::PRIMITIVE_TYPES.include?(of)
         raise Riffer::ArgumentError,
-          "of: must be a primitive type (#{Riffer::Param::PRIMITIVE_TYPES.map(&:name).join(", ")}), got #{of}"
+          "of: must be a primitive type (#{Riffer::Params::Param::PRIMITIVE_TYPES.map(&:name).join(", ")}), got #{of}"
       end
       return nil
     end
@@ -154,7 +154,7 @@ class Riffer::Params
   end
 
   #--
-  #: (Riffer::Param, untyped, Array[String]) -> untyped
+  #: (Riffer::Params::Param, untyped, Array[String]) -> untyped
   def validate_nested(param, value, errors)
     if param.type == Hash && param.nested_params
       validate_nested_hash(param, value, errors)
@@ -169,9 +169,11 @@ class Riffer::Params
   end
 
   #--
-  #: (Riffer::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
+  #: (Riffer::Params::Param, Hash[Symbol, untyped], Array[String]) -> Hash[Symbol, untyped]
   def validate_nested_hash(param, value, errors)
-    param.nested_params.validate(value)
+    nested = param.nested_params
+    return value unless nested
+    nested.validate(value)
   rescue Riffer::ValidationError => e
     e.message.split("; ").each do |msg|
       errors << "#{param.name}.#{msg}"
@@ -180,14 +182,16 @@ class Riffer::Params
   end
 
   #--
-  #: (Riffer::Param, Array[untyped], Array[String]) -> Array[untyped]
+  #: (Riffer::Params::Param, Array[untyped], Array[String]) -> Array[untyped]
   def validate_nested_array_of_objects(param, value, errors)
+    nested = param.nested_params
+    return value unless nested
     value.map.with_index do |item, i|
       unless item.is_a?(Hash)
         errors << "#{param.name}[#{i}] must be an object"
         next item
       end
-      param.nested_params.validate(item)
+      nested.validate(item)
     rescue Riffer::ValidationError => e
       e.message.split("; ").each do |msg|
         errors << "#{param.name}[#{i}].#{msg}"
@@ -197,14 +201,16 @@ class Riffer::Params
   end
 
   #--
-  #: (Riffer::Param, Array[untyped], Array[String]) -> void
+  #: (Riffer::Params::Param, Array[untyped], Array[String]) -> void
   def validate_typed_array(param, value, errors)
-    type_name = Riffer::Param::TYPE_MAPPINGS[param.item_type]
+    item_type = param.item_type
+    return unless item_type
+    type_name = Riffer::Params::Param::TYPE_MAPPINGS[item_type]
     value.each_with_index do |item, i|
-      valid = if param.item_type == Riffer::Boolean || param.item_type == TrueClass || param.item_type == FalseClass
+      valid = if item_type == Riffer::Params::Boolean || item_type == TrueClass || item_type == FalseClass
         item == true || item == false
       else
-        item.is_a?(param.item_type)
+        item.is_a?(item_type)
       end
       errors << "#{param.name}[#{i}] must be a #{type_name}" unless valid
     end

data/lib/riffer/providers/amazon_bedrock.rb

@@ -63,7 +63,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       system: partitioned_messages[:system],
       messages: partitioned_messages[:conversation],
       **options.except(:tools, :structured_output)
-    }
+    } #: Hash[Symbol, untyped]
 
     if tools && !tools.empty?
       params[:tool_config] = {
@@ -92,18 +92,18 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> Aws::BedrockRuntime::Types::ConverseResponse
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.converse(**params)
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseResponse) -> Riffer::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
-    return nil unless usage
+    typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+    usage = typed_response.usage
 
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens,
       cache_creation_tokens: usage.cache_write_input_tokens,
@@ -112,9 +112,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseResponse) -> String
+  #: (untyped) -> String
   def extract_content(response)
-    content_blocks = response.output&.message&.content
+    typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+    content_blocks = typed_response.output&.message&.content
     return "" if content_blocks.nil? || content_blocks.empty?
 
     text_content = ""
@@ -127,12 +128,13 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseResponse) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
-    content_blocks = response.output&.message&.content
+    typed_response = response #: Aws::BedrockRuntime::Client::_ConverseResponseSuccess
+    content_blocks = typed_response.output&.message&.content
     return [] if content_blocks.nil? || content_blocks.empty?
 
-    tool_calls = []
+    tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
 
     content_blocks.each do |block|
       if block.respond_to?(:tool_use) && block.tool_use
@@ -153,7 +155,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
     current_state = {
       text: nil,
       tool_call: nil
-    }
+    } #: Hash[Symbol, untyped]
 
     @client.converse_stream(**params) do |stream|
       stream.on_event do |event|
@@ -196,28 +198,31 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockStartEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_start_tool_use(event, state:, yielder:)
+    typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockStartEvent
     state[:tool_call] = {
-      id: event.start.tool_use.tool_use_id,
-      name: decode_tool_name(event.start.tool_use.name, tools: @current_tools),
+      id: typed_event.start.tool_use.tool_use_id,
+      name: decode_tool_name(typed_event.start.tool_use.name, tools: @current_tools),
       arguments: ""
     }
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_delta_text_delta(event, state:, yielder:)
-    delta_text = event.delta.text
+    typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
+    delta_text = typed_event.delta.text
     state[:text] ||= ""
     state[:text] += delta_text
     yielder << Riffer::StreamEvents::TextDelta.new(delta_text)
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_delta_tool_use(event, state:, yielder:)
-    input_delta = event.delta.tool_use.input
+    typed_event = event #: Aws::BedrockRuntime::Types::ContentBlockDeltaEvent
+    input_delta = typed_event.delta.tool_use.input
 
     state[:tool_call][:arguments] += input_delta
 
@@ -229,14 +234,14 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_stop_text_delta(_event, state:, yielder:)
     yielder << Riffer::StreamEvents::TextDone.new(state[:text])
     state[:text] = nil
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_stop_tool_use(_event, state:, yielder:)
     tool_call = state[:tool_call]
     yielder << Riffer::StreamEvents::ToolCallDone.new(
@@ -249,14 +254,15 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_metadata_usage(event, state:, yielder:)
+    typed_event = event #: Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::TokenUsage.new(
-        input_tokens: event.usage.input_tokens,
-        output_tokens: event.usage.output_tokens,
-        cache_creation_tokens: event.usage.cache_write_input_tokens,
-        cache_read_tokens: event.usage.cache_read_input_tokens
+      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_read_tokens: typed_event.usage.cache_read_input_tokens
       )
     )
   end
@@ -264,8 +270,8 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   #--
   #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
   def partition_messages(messages)
-    system_prompts = []
-    conversation_messages = []
+    system_prompts = [] #: Array[Hash[Symbol, untyped]]
+    conversation_messages = [] #: Array[Hash[Symbol, untyped]]
 
     messages.each do |message|
       case message
@@ -291,7 +297,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   #--
   #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
   def convert_assistant_to_bedrock_format(message)
-    content = []
+    content = [] #: Array[Hash[Symbol, untyped]]
     content << {text: message.content} if message.content && !message.content.empty?
 
     message.tool_calls.each do |tc|
@@ -326,7 +332,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_bedrock_format(file)
     format = bedrock_format(file.media_type)
 

data/lib/riffer/providers/anthropic.rb

@@ -26,7 +26,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
 
     api_key ||= Riffer.config.anthropic.api_key
 
-    @client = Anthropic::Client.new(api_key: api_key, **options)
+    @client = ::Anthropic::Client.new(api_key: api_key, **options)
   end
 
   private
@@ -46,11 +46,11 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       messages: partitioned_messages[:conversation],
       max_tokens: max_tokens,
       **options.except(:tools, :max_tokens, :structured_output, :web_search)
-    }
+    } #: Hash[Symbol, untyped]
 
     params[:system] = partitioned_messages[:system] if partitioned_messages[:system]
 
-    anthropic_tools = []
+    anthropic_tools = [] #: Array[Hash[Symbol, untyped]]
     anthropic_tools.concat(tools.map { |t| convert_tool_to_anthropic_format(t) }) if tools && !tools.empty?
 
     if web_search
@@ -77,18 +77,18 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> Anthropic::Models::Message
+  #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
     @client.messages.create(**params)
   end
 
   #--
-  #: (Anthropic::Models::Message) -> Riffer::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
-    usage = response.usage
-    return nil unless usage
+    message = response #: Anthropic::Models::Message
+    usage = message.usage
 
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: usage.input_tokens,
       output_tokens: usage.output_tokens,
       cache_creation_tokens: usage.cache_creation_input_tokens,
@@ -97,30 +97,32 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Anthropic::Models::Message) -> String
+  #: (untyped) -> String
   def extract_content(response)
-    content_blocks = response.content
+    message = response #: Anthropic::Models::Message
+    content_blocks = message.content
     return "" if content_blocks.nil? || content_blocks.empty?
 
     text_content = ""
 
     content_blocks.each do |block|
-      text_content = block.text if block.type.to_s == "text"
+      text_content = block.text if block.is_a?(::Anthropic::Models::TextBlock)
     end
 
     text_content
   end
 
   #--
-  #: (Anthropic::Models::Message) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
-    content_blocks = response.content
+    message = response #: Anthropic::Models::Message
+    content_blocks = message.content
     return [] if content_blocks.nil? || content_blocks.empty?
 
-    tool_calls = []
+    tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
 
     content_blocks.each do |block|
-      if block.type.to_s == "tool_use"
+      if block.is_a?(::Anthropic::Models::ToolUseBlock)
         tool_calls << Riffer::Messages::Assistant::ToolCall.new(
           call_id: block.id,
           name: decode_tool_name(block.name, tools: @current_tools),
@@ -142,7 +144,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       web_search_index: nil,
       web_search_json: nil,
       web_search_query: nil
-    }
+    } #: Hash[Symbol, untyped]
 
     # Workaround for anthropics/anthropic-sdk-ruby#182: force identity
     # encoding so Net::HTTP/Zlib doesn't buffer SSE chunks until EOF.
@@ -154,24 +156,24 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     begin
       stream.each do |event|
         case event
-        when Anthropic::Models::RawContentBlockStartEvent
+        when ::Anthropic::Models::RawContentBlockStartEvent
           handle_raw_content_block_start(event, state: current_state)
-        when Anthropic::Models::RawContentBlockDeltaEvent
+        when ::Anthropic::Models::RawContentBlockDeltaEvent
           handle_raw_content_block_delta(event, state: current_state)
-        when Anthropic::Streaming::TextEvent
+        when ::Anthropic::Helpers::Streaming::TextEvent
           handle_text_event(event, state: current_state, yielder: yielder)
-        when Anthropic::Streaming::ThinkingEvent
+        when ::Anthropic::Helpers::Streaming::ThinkingEvent
           handle_thinking_event(event, state: current_state, yielder: yielder)
-        when Anthropic::Streaming::InputJsonEvent
+        when ::Anthropic::Helpers::Streaming::InputJsonEvent
           handle_input_json_event(event, state: current_state, yielder: yielder)
-        when Anthropic::Streaming::ContentBlockStopEvent
-          block_type = event.content_block&.type.to_s
-          handle_content_block_stop_text(event, state: current_state, yielder: yielder) if block_type == "text" && current_state[:text]
-          handle_content_block_stop_tool_use(event, state: current_state, yielder: yielder) if block_type == "tool_use"
-          handle_content_block_stop_thinking(event, state: current_state, yielder: yielder) if block_type == "thinking" && current_state[:reasoning]
-          handle_content_block_stop_server_tool_use(event, state: current_state, yielder: yielder) if block_type == "server_tool_use"
-          handle_content_block_stop_web_search_result(event, state: current_state, yielder: yielder) if block_type == "web_search_tool_result"
-        when Anthropic::Streaming::MessageStopEvent
+        when ::Anthropic::Helpers::Streaming::ContentBlockStopEvent
+          block = event.content_block
+          handle_content_block_stop_text(event, state: current_state, yielder: yielder) if block.is_a?(::Anthropic::Models::TextBlock) && current_state[:text]
+          handle_content_block_stop_tool_use(event, state: current_state, yielder: yielder) if block.is_a?(::Anthropic::Models::ToolUseBlock)
+          handle_content_block_stop_thinking(event, state: current_state, yielder: yielder) if block.is_a?(::Anthropic::Models::ThinkingBlock) && current_state[:reasoning]
+          handle_content_block_stop_server_tool_use(event, state: current_state, yielder: yielder) if block.is_a?(::Anthropic::Models::ServerToolUseBlock)
+          handle_content_block_stop_web_search_result(event, state: current_state, yielder: yielder) if block.is_a?(::Anthropic::Models::WebSearchToolResultBlock)
+        when ::Anthropic::Helpers::Streaming::MessageStopEvent
           handle_message_stop(event, accumulated_message: stream.accumulated_message, yielder: yielder)
         end
       end
@@ -286,13 +288,14 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, accumulated_message: Anthropic::Models::Message?, yielder: Enumerator::Yielder) -> void
+  #: (untyped, accumulated_message: untyped, yielder: Enumerator::Yielder) -> void
   def handle_message_stop(_event, accumulated_message:, yielder:)
-    usage = accumulated_message&.usage
+    message = accumulated_message #: Anthropic::Models::Message?
+    usage = message&.usage
     return unless usage
 
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::TokenUsage.new(
+      token_usage: Riffer::Providers::TokenUsage.new(
         input_tokens: usage.input_tokens,
         output_tokens: usage.output_tokens,
         cache_creation_tokens: usage.cache_creation_input_tokens,
@@ -304,8 +307,8 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
   def partition_messages(messages)
-    system_prompts = []
-    conversation_messages = []
+    system_prompts = [] #: Array[Hash[Symbol, untyped]]
+    conversation_messages = [] #: Array[Hash[Symbol, untyped]]
 
     messages.each do |message|
       case message
@@ -342,7 +345,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
   def convert_assistant_to_anthropic_format(message)
-    content = []
+    content = [] #: Array[Hash[Symbol, untyped]]
     content << {type: "text", text: message.content} if message.content && !message.content.empty?
 
     message.tool_calls.each do |tc|
@@ -358,7 +361,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_anthropic_format(file)
     type = file.image? ? "image" : "document"
 

data/lib/riffer/providers/base.rb

@@ -17,6 +17,8 @@ require "json"
 # [extract_content] extract text content from the SDK response
 # [extract_tool_calls] extract tool calls from the SDK response
 class Riffer::Providers::Base
+  # @rbs @current_tools: Array[singleton(Riffer::Tool)]
+
   include Riffer::Helpers::Dependencies
   include Riffer::Messages::Converter
 
@@ -39,10 +41,10 @@ class Riffer::Providers::Base
   # Generates text using the provider.
   #
   #--
-  #: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, **untyped) -> Riffer::Messages::Assistant
+  #: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Riffer::Messages::Assistant
   def generate_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
-    @current_tools = options[:tools] || []
+    @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
     messages = merge_consecutive_messages(messages)
@@ -65,10 +67,10 @@ class Riffer::Providers::Base
   # Streams text from the provider.
   #
   #--
-  #: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
+  #: (?prompt: String?, ?system: String?, ?messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?model: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
   def stream_text(prompt: nil, system: nil, messages: nil, model: nil, files: nil, **options)
     validate_input!(prompt: prompt, system: system, messages: messages)
-    @current_tools = options[:tools] || []
+    @current_tools = options[:tools] || [] #: Array[singleton(Riffer::Tool)]
     messages = normalize_messages(prompt: prompt, system: system, messages: messages, files: files)
     validate_normalized_messages!(messages)
     messages = merge_consecutive_messages(messages)
@@ -87,7 +89,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (String, tools: Array[Riffer::Tool]) -> String
+  #: (String, tools: Array[singleton(Riffer::Tool)]) -> String
   def decode_tool_name(wire_name, tools:)
     tool = tools.find { |t| encode_tool_name(t.name) == wire_name }
     tool ? tool.name : wire_name
@@ -112,7 +114,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (untyped) -> Riffer::TokenUsage?
+  #: (untyped) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     raise NotImplementedError, "Subclasses must implement #extract_token_usage"
   end
@@ -166,7 +168,7 @@ class Riffer::Providers::Base
   end
 
   #--
-  #: (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?) -> Array[Riffer::Messages::Base]
+  #: (prompt: String?, system: String?, messages: Array[Hash[Symbol, untyped] | Riffer::Messages::Base]?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Array[Riffer::Messages::Base]
   def normalize_messages(prompt:, system:, messages:, files: nil)
     if messages && files && !files.empty?
       raise Riffer::ArgumentError, "cannot provide both files and messages; attach files to individual messages instead"
@@ -176,10 +178,11 @@ class Riffer::Providers::Base
       return messages.map { |msg| convert_to_message_object(msg) }
     end
 
-    result = []
+    result = [] #: Array[Riffer::Messages::Base]
     result << Riffer::Messages::System.new(system) if system
     file_parts = (files || []).map { |f| convert_to_file_part(f) }
-    result << Riffer::Messages::User.new(prompt, files: file_parts)
+    prompt_text = prompt #: String
+    result << Riffer::Messages::User.new(prompt_text, files: file_parts)
     result
   end