riffer 0.27.2 → 0.29.0

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,17 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> Aws::BedrockRuntime::Types::ConverseResponse
+  #: (Hash[Symbol, untyped]) -> Aws::BedrockRuntime::Client::_ConverseResponseSuccess
   def execute_generate(params)
     @client.converse(**params)
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseResponse) -> Riffer::TokenUsage?
+  #: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     usage = response.usage
-    return nil unless 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,7 +111,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseResponse) -> String
+  #: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> String
   def extract_content(response)
     content_blocks = response.output&.message&.content
     return "" if content_blocks.nil? || content_blocks.empty?
@@ -127,12 +126,12 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseResponse) -> Array[Riffer::Messages::Assistant::ToolCall]
+  #: (Aws::BedrockRuntime::Client::_ConverseResponseSuccess) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls(response)
     content_blocks = 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 +152,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,7 +195,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockStartEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (Aws::BedrockRuntime::Types::ContentBlockStartEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_start_tool_use(event, state:, yielder:)
     state[:tool_call] = {
       id: event.start.tool_use.tool_use_id,
@@ -206,7 +205,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_content_block_delta_text_delta(event, state:, yielder:)
     delta_text = event.delta.text
     state[:text] ||= ""
@@ -215,7 +214,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (Aws::BedrockRuntime::Types::ContentBlockDeltaEvent, 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
 
@@ -229,14 +228,14 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, 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
+  #: (Aws::BedrockRuntime::Types::ContentBlockStopEvent, 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,10 +248,10 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent, state: Hash[Symbol, untyped], yielder: Enumerator[Riffer::StreamEvents::Base, void]) -> void
+  #: (Aws::BedrockRuntime::Types::ConverseStreamMetadataEvent, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
   def handle_metadata_usage(event, state:, yielder:)
     yielder << Riffer::StreamEvents::TokenUsageDone.new(
-      token_usage: Riffer::TokenUsage.new(
+      token_usage: Riffer::Providers::TokenUsage.new(
         input_tokens: event.usage.input_tokens,
         output_tokens: event.usage.output_tokens,
         cache_creation_tokens: event.usage.cache_write_input_tokens,
@@ -264,8 +263,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 +290,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 +325,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
@@ -83,12 +83,11 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (Anthropic::Models::Message) -> Riffer::TokenUsage?
+  #: (Anthropic::Models::Message) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     usage = response.usage
-    return nil unless 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,
@@ -105,7 +104,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     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
@@ -117,10 +116,10 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     content_blocks = response.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 +141,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 +153,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
@@ -292,7 +291,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
     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 +303,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 +341,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 +357,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

@@ -39,10 +39,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 +65,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 +87,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 +112,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 +166,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 +176,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
 

data/lib/riffer/providers/gemini.rb

@@ -36,7 +36,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     params = {
       model: model,
       contents: partitioned[:contents]
-    }
+    } #: Hash[Symbol, untyped]
 
     params[:systemInstruction] = partitioned[:system_instruction] if partitioned[:system_instruction]
 
@@ -96,12 +96,12 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   end
 
   #--
-  #: (Hash[Symbol, untyped]) -> Riffer::TokenUsage?
+  #: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage?
   def extract_token_usage(response)
     usage = response[:usageMetadata]
     return nil unless usage
 
-    Riffer::TokenUsage.new(
+    Riffer::Providers::TokenUsage.new(
       input_tokens: usage[:promptTokenCount] || 0,
       output_tokens: usage[:candidatesTokenCount] || 0
     )
@@ -114,6 +114,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     body = params.except(:model)
 
     uri = URI("#{BASE_URI}/#{api_path(model, "streamGenerateContent")}?alt=sse")
+    host = uri.hostname #: String
     request = Net::HTTP::Post.new(uri)
     request["Content-Type"] = "application/json"
     request["x-goog-api-key"] = @api_key
@@ -126,7 +127,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       buffer << chunk
 
       while (match = buffer.match(/\r?\n\r?\n/))
-        frame = buffer.slice!(0, match.end(0)).strip
+        match_end = match.end(0) #: Integer
+        frame = buffer.slice!(0, match_end).to_s.strip
         next unless frame.start_with?("data: ")
 
         json_str = frame.delete_prefix("data: ").strip
@@ -155,7 +157,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
         usage = parsed[:usageMetadata]
         if usage && usage[:candidatesTokenCount]
           yielder << Riffer::StreamEvents::TokenUsageDone.new(
-            token_usage: Riffer::TokenUsage.new(
+            token_usage: Riffer::Providers::TokenUsage.new(
               input_tokens: usage[:promptTokenCount] || 0,
               output_tokens: usage[:candidatesTokenCount] || 0
             )
@@ -164,7 +166,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       end
     end
 
-    Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
+    Net::HTTP.start(host, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) do |http|
       http.request(request) do |response|
         handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
 
@@ -182,8 +184,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   #--
   #: (Array[Riffer::Messages::Base]) -> Hash[Symbol, untyped]
   def partition_messages(messages)
-    system_parts = []
-    contents = []
+    system_parts = [] #: Array[Hash[Symbol, untyped]]
+    contents = [] #: Array[Hash[Symbol, untyped]]
 
     messages.each do |message|
       case message
@@ -212,7 +214,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       end
     end
 
-    result = {contents: contents}
+    result = {contents: contents} #: Hash[Symbol, untyped]
     result[:system_instruction] = {parts: system_parts} unless system_parts.empty?
     result
   end
@@ -220,7 +222,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   #--
   #: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
   def convert_assistant_to_gemini_format(message)
-    parts = []
+    parts = [] #: Array[Hash[Symbol, untyped]]
     parts << {text: message.content} if message.content && !message.content.empty?
 
     message.tool_calls.each do |tc|
@@ -236,7 +238,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   end
 
   #--
-  #: (Riffer::FilePart) -> Hash[Symbol, untyped]
+  #: (Riffer::Messages::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_gemini_format(file)
     if file.url?
       raise Riffer::ArgumentError,
@@ -268,11 +270,12 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   #: (String, Hash[Symbol, untyped]) -> Net::HTTPResponse
   def post_request(path, body)
     uri = URI("#{BASE_URI}/#{path}")
+    host = uri.hostname #: String
     request = Net::HTTP::Post.new(uri)
     request["Content-Type"] = "application/json"
     request["x-goog-api-key"] = @api_key
     request.body = body.to_json
-    Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) { |http| http.request(request) }
+    Net::HTTP.start(host, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) { |http| http.request(request) }
   end
 
   #--