riffer 0.40.0 → 0.41.0

data/lib/riffer/providers/gemini.rb

@@ -2,20 +2,11 @@
 # rbs_inline: enabled
 
 require "json"
-require "net/http"
 require "securerandom"
-require "uri"
 
 # Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
-  # @rbs @api_key: String?
-  # @rbs @open_timeout: Integer
-  # @rbs @read_timeout: Integer
-
-  BASE_URI = URI("https://generativelanguage.googleapis.com") #: URI::Generic
   VALID_MODEL_PATTERN = /\A[a-zA-Z0-9._-]+\z/ #: Regexp
-  DEFAULT_OPEN_TIMEOUT = 10 #: Integer
-  DEFAULT_READ_TIMEOUT = 60 #: Integer
 
   FINISH_REASONS = {
     "STOP" => :stop,
@@ -36,17 +27,19 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     "gcp.gemini"
   end
 
+  private
+
   #--
-  #: (?api_key: String?, ?open_timeout: Integer?, ?read_timeout: Integer?, **untyped) -> void
-  def initialize(api_key: nil, open_timeout: nil, read_timeout: nil, **_options)
-    super()
-    api_key ||= Riffer.config.gemini.api_key
-    @api_key = api_key
-    @open_timeout = open_timeout || Riffer.config.gemini.open_timeout || DEFAULT_OPEN_TIMEOUT
-    @read_timeout = read_timeout || Riffer.config.gemini.read_timeout || DEFAULT_READ_TIMEOUT
+  #: () -> untyped
+  def global_client
+    Riffer.config.gemini.client
   end
 
-  private
+  #--
+  #: () -> untyped
+  def build_client
+    Riffer::Providers::Gemini::Client.new(**{ api_key: Riffer.config.gemini.api_key }.compact)
+  end
 
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -89,9 +82,7 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   def execute_generate(params)
     model = params[:model]
     body = params.except(:model)
-    response = post_request(api_path(model, "generateContent"), body)
-    handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
-    JSON.parse(response.body, symbolize_names: true)
+    client.post(api_path(model, "generateContent"), body)
   end
 
   #--
@@ -171,13 +162,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     model = params[:model]
     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
-    request.body = body.to_json
-
     full_text = +""
     buffer = +""
     raw_finish_reason = nil #: String?
@@ -224,17 +208,8 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
       end
     end
 
-    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)
-
-        begin
-          response.read_body { |chunk| process_chunk.call(chunk) }
-        rescue IOError
-          process_chunk.call(response.body)
-        end
-      end
-    end
+    path = "#{api_path(model, 'streamGenerateContent')}?alt=sse"
+    client.post_stream(path, body) { |chunk| process_chunk.call(chunk) }
 
     yielder << Riffer::StreamEvents::TextDone.new(full_text) unless full_text.empty?
     yield_finish_reason(yielder, build_finish_reason(raw_finish_reason, tool_calls: saw_function_call))
@@ -325,18 +300,6 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
     args.is_a?(String) ? args : args.to_json
   end
 
-  #--
-  #: (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(host, uri.port, use_ssl: true, open_timeout: @open_timeout, read_timeout: @read_timeout) { |http| http.request(request) }
-  end
-
   #--
   #: (String, String) -> String
   def api_path(model, method)
@@ -370,16 +333,4 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
 
     schema
   end
-
-  #--
-  #: (Net::HTTPResponse) -> void
-  def handle_api_error!(response)
-    body = begin
-      JSON.parse(response.body, symbolize_names: true)
-    rescue JSON::ParserError
-      { message: response.body }
-    end
-    error_message = body.dig(:error, :message) || body[:message] || response.body
-    raise Riffer::Error, "Gemini API error (#{response.code}): #{error_message}"
-  end
 end

data/lib/riffer/providers/mock.rb

@@ -28,7 +28,8 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   attr_reader :calls #: Array[Hash[Symbol, untyped]]
 
   # +responses:+ pre-configures canned responses (same shape as
-  # +#stub_response+), typically set via +provider_options responses: [...]+.
+  # +#stub_response+) for standalone use; agent tests queue responses on
+  # <tt>agent.provider</tt> via +#stub_response+ instead.
   #
   #   Riffer::Providers::Mock.new(responses: [
   #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
@@ -36,10 +37,10 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
   #   ])
   #
   #--
-  #: (**untyped) -> void
-  def initialize(**options)
+  #: (?responses: Array[Hash[Symbol, untyped]]) -> void
+  def initialize(responses: [])
     super()
-    @responses = (options[:responses] || []).map { |r| normalize_response(r) }
+    @responses = responses.map { |r| normalize_response(r) }
     @current_index = 0
     @calls = []
     @stubbed_responses = []

data/lib/riffer/providers/open_ai.rb

@@ -13,17 +13,32 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   end
 
   #--
-  #: (**untyped) -> void
-  def initialize(**options)
-    super()
+  #: () -> void
+  def initialize
+    super
     depends_on "openai"
-
-    api_key = options.fetch(:api_key, Riffer.config.openai.api_key)
-    @client = ::OpenAI::Client.new(api_key: api_key, **options.except(:api_key))
   end
 
   private
 
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.openai.client
+  end
+
+  # Compacted so an unset value stays absent: the SDK reads +OPENAI_API_KEY+ /
+  # +OPENAI_BASE_URL+ only for a missing argument, and an explicit nil would
+  # suppress that fallback.
+  #--
+  #: () -> untyped
+  def build_client
+    ::OpenAI::Client.new(**{
+      api_key: Riffer.config.openai.api_key,
+      base_url: Riffer.config.openai.base_url,
+    }.compact)
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)
@@ -81,7 +96,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
-    @client.responses.create(params)
+    client.responses.create(params)
   end
 
   #--
@@ -190,7 +205,7 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
       tool_info: {},
     } #: Hash[Symbol, untyped]
 
-    stream = @client.responses.stream(params)
+    stream = client.responses.stream(params)
     begin
       stream.each do |event|
         case event.type

data/lib/riffer/providers/open_router.rb

@@ -5,7 +5,7 @@ require "json"
 
 # OpenRouter provider (https://openrouter.ai). Requires the +openai+ gem —
 # OpenRouter exposes an OpenAI-compatible endpoint, so this reuses the OpenAI
-# SDK with a +base_url+ override. +api_key+ falls back to config, then
+# SDK with a +base_url+ override. +api_key+ resolves from config, then
 # +OPENROUTER_API_KEY+.
 class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   BASE_URL = "https://openrouter.ai/api/v1" #: String
@@ -27,17 +27,31 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   end
 
   #--
-  #: (?api_key: String?, **untyped) -> void
-  def initialize(api_key: nil, **)
-    super()
+  #: () -> void
+  def initialize
+    super
     depends_on "openai"
+  end
 
-    api_key ||= Riffer.config.openrouter.api_key || ENV.fetch("OPENROUTER_API_KEY", nil)
+  private
 
-    @client = ::OpenAI::Client.new(api_key: api_key, base_url: BASE_URL, **)
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.openrouter.client
   end
 
-  private
+  # Deliberately not compacted: this borrows the OpenAI SDK to talk to a
+  # different vendor, so omitting an unset +api_key+ would let the SDK fall
+  # back to +OPENAI_API_KEY+ and send an OpenAI credential to OpenRouter.
+  # Passing nil raises in the SDK instead. +OPENROUTER_API_KEY+ is read here
+  # rather than left to the SDK for the same reason.
+  #--
+  #: () -> untyped
+  def build_client
+    api_key = Riffer.config.openrouter.api_key || ENV.fetch("OPENROUTER_API_KEY", nil)
+    ::OpenAI::Client.new(api_key: api_key, base_url: BASE_URL)
+  end
 
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -84,7 +98,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
-    @client.chat.completions.create(**params)
+    client.chat.completions.create(**params)
   end
 
   #--
@@ -174,7 +188,7 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
     # events. We want raw ChatCompletionChunk objects with
     # +choices.first.delta+ so we can map deltas to Riffer::StreamEvents
     # ourselves.
-    stream = @client.chat.completions.stream_raw(**stream_params)
+    stream = client.chat.completions.stream_raw(**stream_params)
     begin
       stream.each do |chunk|
         handle_stream_chunk(chunk, state: state, yielder: yielder)

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.40.0" #: String
+  VERSION = "0.41.0" #: String
 end

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

@@ -1,4 +1,6 @@
-# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+# `client` is typed against the SDK, so this narrowing stays in _private (never ships)
 class Riffer::Providers::AmazonBedrock
-  @client: ::Aws::BedrockRuntime::Client
+  private
+
+  def client: () -> ::Aws::BedrockRuntime::Client
 end

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

@@ -1,4 +1,6 @@
-# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+# `client` is typed against the SDK, so this narrowing stays in _private (never ships)
 class Riffer::Providers::Anthropic
-  @client: ::Anthropic::Client
+  private
+
+  def client: () -> ::Anthropic::Client
 end

data/sig/_private/riffer/providers/gemini.rbs

@@ -0,0 +1,7 @@
+# Narrows the private `client` to riffer's Gemini transport, mirroring the
+# SDK-typed narrowings alongside it.
+class Riffer::Providers::Gemini
+  private
+
+  def client: () -> Riffer::Providers::Gemini::Client
+end

data/sig/_private/riffer/providers/open_ai.rbs

@@ -1,4 +1,6 @@
-# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+# `client` is typed against the SDK, so this narrowing stays in _private (never ships)
 class Riffer::Providers::OpenAI
-  @client: ::OpenAI::Client
+  private
+
+  def client: () -> ::OpenAI::Client
 end

data/sig/_private/riffer/providers/open_router.rbs

@@ -1,4 +1,6 @@
-# `@client` is typed against the SDK, so this ivar stub stays in _private (never ships)
+# `client` is typed against the SDK, so this narrowing stays in _private (never ships)
 class Riffer::Providers::OpenRouter
-  @client: ::OpenAI::Client
+  private
+
+  def client: () -> ::OpenAI::Client
 end

data/sig/generated/riffer/agent/config.rbs

@@ -15,9 +15,6 @@ class Riffer::Agent::Config
   # The configured instructions.
   attr_reader instructions: (String | Proc)?
 
-  # Options passed to the provider client.
-  attr_accessor provider_options: Hash[Symbol, untyped]
-
   # Options passed to generate_text/stream_text.
   attr_accessor model_options: Hash[Symbol, untyped]
 
@@ -49,7 +46,6 @@ class Riffer::Agent::Config
   #    ?identifier: String?,
   #    ?model: (String | Proc)?,
   #    ?instructions: (String | Proc)?,
-  #    ?provider_options: Hash[Symbol, untyped],
   #    ?model_options: Hash[Symbol, untyped],
   #    ?structured_output: Riffer::Params?,
   #    ?max_steps: Numeric?,
@@ -59,7 +55,7 @@ class Riffer::Agent::Config
   #    ?skills_config: Riffer::Skills::Config?,
   #    ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]
   #  ) -> void
-  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?provider_options: Hash[Symbol, untyped], ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
+  def initialize: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric?, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc, ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
 
   # Sets +identifier+, coercing the value to String.
   # --

data/sig/generated/riffer/agent.rbs

@@ -45,12 +45,6 @@ class Riffer::Agent
   # : (?(String | Proc)?) -> (String | Proc)?
   def self.instructions: (?(String | Proc)?) -> (String | Proc)?
 
-  # Gets or sets provider options passed to the provider client.
-  #
-  # --
-  # : (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
-  def self.provider_options: (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
-
   # Gets or sets model options passed to generate_text/stream_text.
   #
   # --

data/sig/generated/riffer/config.rbs

@@ -7,15 +7,19 @@ class Riffer::Config
 
     attr_accessor region(): untyped
 
-    def self.new: (?untyped api_token, ?untyped region) -> instance
-                | (?api_token: untyped, ?region: untyped) -> instance
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_token, ?untyped region, ?untyped client) -> instance
+                | (?api_token: untyped, ?region: untyped, ?client: untyped) -> instance
   end
 
   class Anthropic < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?untyped api_key) -> instance
-                | (?api_key: untyped) -> instance
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_key, ?untyped client) -> instance
+                | (?api_key: untyped, ?client: untyped) -> instance
   end
 
   class AzureOpenAI < Struct[untyped]
@@ -23,33 +27,39 @@ class Riffer::Config
 
     attr_accessor endpoint(): untyped
 
-    def self.new: (?untyped api_key, ?untyped endpoint) -> instance
-                | (?api_key: untyped, ?endpoint: untyped) -> instance
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_key, ?untyped endpoint, ?untyped client) -> instance
+                | (?api_key: untyped, ?endpoint: untyped, ?client: untyped) -> instance
   end
 
   class Gemini < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    attr_accessor open_timeout(): untyped
-
-    attr_accessor read_timeout(): untyped
+    attr_accessor client(): untyped
 
-    def self.new: (?untyped api_key, ?untyped open_timeout, ?untyped read_timeout) -> instance
-                | (?api_key: untyped, ?open_timeout: untyped, ?read_timeout: untyped) -> instance
+    def self.new: (?untyped api_key, ?untyped client) -> instance
+                | (?api_key: untyped, ?client: untyped) -> instance
   end
 
   class OpenAI < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?untyped api_key) -> instance
-                | (?api_key: untyped) -> instance
+    attr_accessor base_url(): untyped
+
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_key, ?untyped base_url, ?untyped client) -> instance
+                | (?api_key: untyped, ?base_url: untyped, ?client: untyped) -> instance
   end
 
   class OpenRouter < Struct[untyped]
     attr_accessor api_key(): untyped
 
-    def self.new: (?untyped api_key) -> instance
-                | (?api_key: untyped) -> instance
+    attr_accessor client(): untyped
+
+    def self.new: (?untyped api_key, ?untyped client) -> instance
+                | (?api_key: untyped, ?client: untyped) -> instance
   end
 
   class Evals < Struct[untyped]

data/sig/generated/riffer/evals/judge.rbs

@@ -3,8 +3,6 @@
 # Executes LLM-as-judge evaluations, using tool calling internally to get
 # structured output from the judge model.
 class Riffer::Evals::Judge
-  @provider_options: Hash[Symbol, untyped]
-
   @provider_instance: Riffer::Providers::Base?
 
   @provider_name: String?
@@ -23,8 +21,8 @@ class Riffer::Evals::Judge
 
   # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   # --
-  # : (model: String, ?provider_options: Hash[Symbol, untyped]) -> void
-  def initialize: (model: String, ?provider_options: Hash[Symbol, untyped]) -> void
+  # : (model: String) -> void
+  def initialize: (model: String) -> void
 
   # Evaluates an input/output pair using the configured LLM.
   # --

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

@@ -21,11 +21,22 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   def self.semconv_provider_name: () -> String
 
   # --
-  # : (?api_token: String?, ?region: String?, **untyped) -> void
-  def initialize: (?api_token: String?, ?region: String?, **untyped) -> void
+  # : () -> void
+  def initialize: () -> void
 
   private
 
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # Compacted so an unset region stays absent: the AWS SDK resolves +AWS_REGION+
+  # and the shared config only for a missing argument, and raises
+  # +Aws::Errors::MissingRegionError+ on an explicit nil.
+  # --
+  # : () -> untyped
+  def build_client: () -> untyped
+
   # --
   # : (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]

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

@@ -19,11 +19,22 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   def self.semconv_provider_name: () -> String
 
   # --
-  # : (?api_key: String?, **untyped) -> void
-  def initialize: (?api_key: String?, **untyped) -> void
+  # : () -> void
+  def initialize: () -> void
 
   private
 
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # Compacted for the same reason as the other providers: never hand an SDK an
+  # explicit nil credential, so its own +ANTHROPIC_API_KEY+ resolution stays
+  # reachable regardless of how that SDK distinguishes nil from absent.
+  # --
+  # : () -> untyped
+  def build_client: () -> untyped
+
   # --
   # : (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]

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

@@ -1,15 +1,25 @@
 # Generated from lib/riffer/providers/azure_open_ai.rb with RBS::Inline
 
 # Azure OpenAI provider for GPT models hosted on Azure. Requires the +openai+
-# gem. Credentials resolve from kwargs, then config, then
-# +AZURE_OPENAI_API_KEY+ / +AZURE_OPENAI_ENDPOINT+.
+# gem. Credentials resolve from config, then +AZURE_OPENAI_API_KEY+ /
+# +AZURE_OPENAI_ENDPOINT+.
 class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
   # The GenAI semconv well-known provider name.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
 
+  private
+
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # Deliberately not compacted: this borrows the OpenAI SDK to talk to Azure, so
+  # omitting an unset argument would let the SDK fall back to +OPENAI_API_KEY+
+  # and +OPENAI_BASE_URL+ — sending Azure traffic, and an OpenAI credential, to
+  # whatever those name. Passing nil raises in the SDK instead.
   # --
-  # : (**untyped) -> void
-  def initialize: (**untyped) -> void
+  # : () -> untyped
+  def build_client: () -> untyped
 end

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

@@ -5,6 +5,8 @@
 # +extract_token_usage+, +extract_content+, +extract_tool_calls+) and the base
 # class orchestrates them.
 class Riffer::Providers::Base
+  @client: untyped
+
   @current_model: String?
 
   @current_tools: Array[singleton(Riffer::Tool)]
@@ -42,6 +44,24 @@ class Riffer::Providers::Base
   # : (String) -> true
   def depends_on: (String) -> true
 
+  # Returns the client for the current LLM call. A configured client wins,
+  # resolved on every call so a Proc can vary the client by process or
+  # credential lifetime; otherwise the provider builds one from the configured
+  # credentials, memoized for the life of the provider.
+  # --
+  # : () -> untyped
+  def client: () -> untyped
+
+  # Returns the consumer-configured client for this provider; nil when none is
+  # configured, and for providers that take no configuration at all.
+  # --
+  # : () -> untyped
+  def global_client: () -> untyped
+
+  # --
+  # : () -> untyped
+  def build_client: () -> untyped
+
   # --
   # : (String) -> String
   def encode_tool_name: (String) -> String

data/sig/generated/riffer/providers/gemini/client.rbs

@@ -0,0 +1,65 @@
+# Generated from lib/riffer/providers/gemini/client.rb with RBS::Inline
+
+# HTTP transport for the Gemini REST API. Riffer builds one from the
+# configured +api_key+ by default; construct your own to tune the HTTP knobs
+# and assign it to <tt>Riffer.config.gemini.client</tt>. Any object
+# implementing +post+ and +post_stream+ with these contracts works there —
+# the class is a default implementation, not a required base.
+#
+#   Riffer.configure do |config|
+#     config.gemini.client = Riffer::Providers::Gemini::Client.new(
+#       api_key: ENV["GEMINI_API_KEY"],
+#       read_timeout: 120
+#     )
+#   end
+class Riffer::Providers::Gemini::Client
+  @proxy_port: Integer?
+
+  @proxy_address: String?
+
+  @write_timeout: Integer?
+
+  @read_timeout: Integer
+
+  @open_timeout: Integer
+
+  @base_url: String
+
+  @api_key: String?
+
+  DEFAULT_BASE_URL: String
+
+  DEFAULT_OPEN_TIMEOUT: Integer
+
+  DEFAULT_READ_TIMEOUT: Integer
+
+  # : (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
+  def initialize: (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
+
+  # POSTs a JSON body to an API path and returns the parsed response hash.
+  # Raises Riffer::Error when the API responds with a non-success status.
+  # --
+  # : (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def post: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+
+  # POSTs a JSON body to an API path, yielding raw response body chunks as
+  # they arrive. Raises Riffer::Error when the API responds with a
+  # non-success status.
+  # --
+  # : (String, Hash[Symbol, untyped]) { (String) -> void } -> void
+  def post_stream: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
+
+  private
+
+  # --
+  # : (URI::Generic, Hash[Symbol, untyped]) -> Net::HTTP::Post
+  def build_request: (URI::Generic, Hash[Symbol, untyped]) -> Net::HTTP::Post
+
+  # --
+  # : [R] (URI::Generic) { (Net::HTTP) -> R } -> R
+  def start_http: [R] (URI::Generic) { (Net::HTTP) -> R } -> R
+
+  # --
+  # : (Net::HTTPResponse) -> void
+  def handle_api_error!: (Net::HTTPResponse) -> void
+end