Allow custom Faraday adapter

Add an `adapter:` keyword argument to `Cohere::Client.new`, defaulting
to `Faraday.default_adapter`. This lets callers opt into persistent
adapters (e.g., `:net_http_persistent`) to amortize TCP/TLS handshakes
across requests and reduce tail latency under load.

Author: martinechtner

CHANGELOG.md

@@ -1,4 +1,5 @@
 ## [Unreleased]
+- Add `adapter:` keyword argument to `Cohere::Client.new` for configuring the Faraday HTTP adapter (defaults to `Faraday.default_adapter`). Enables using persistent adapters such as `:net_http_persistent` to amortize TCP/TLS handshakes across requests.
 
 ## [1.0.1] - 2024-11-22
 

README.md

@@ -38,6 +38,30 @@ client = Cohere::Client.new(
 )
 ```
 
+#### Custom HTTP adapter
+
+By default the client uses `Faraday.default_adapter` (Net::HTTP), which opens a
+new TCP/TLS connection per request. For high-throughput use cases, pass a
+persistent adapter to reuse connections across requests:
+
+```ruby
+require "faraday/net_http_persistent"
+
+client = Cohere::Client.new(
+  api_key: ENV['COHERE_API_KEY'],
+  adapter: :net_http_persistent
+)
+```
+
+You can also pass adapter options:
+
+```ruby
+client = Cohere::Client.new(
+  api_key: ENV['COHERE_API_KEY'],
+  adapter: [:net_http_persistent, {name: "cohere", pool_size: 10}]
+)
+```
+
 ### Generate
 
 ```ruby

lib/cohere/client.rb

@@ -4,11 +4,12 @@
 
 module Cohere
   class Client
-    attr_reader :api_key, :connection
+    attr_reader :api_key, :connection, :adapter
 
-    def initialize(api_key:, timeout: nil)
+    def initialize(api_key:, timeout: nil, adapter: Faraday.default_adapter)
       @api_key = api_key
       @timeout = timeout
+      @adapter = adapter
     end
 
     # Generates a text response to a user message and streams it down, token by token
@@ -215,7 +216,7 @@ def v1_connection
         faraday.request :authorization, :Bearer, api_key
         faraday.request :json
         faraday.response :json, content_type: /\bjson$/
-        faraday.adapter Faraday.default_adapter
+        faraday.adapter(*Array(@adapter))
       end
     end
 
@@ -224,7 +225,7 @@ def v2_connection
         faraday.request :authorization, :Bearer, api_key
         faraday.request :json
         faraday.response :json, content_type: /\bjson$/
-        faraday.adapter Faraday.default_adapter
+        faraday.adapter(*Array(@adapter))
       end
     end
   end

spec/cohere/client_spec.rb

@@ -5,6 +5,24 @@
 RSpec.describe Cohere::Client do
   subject { described_class.new(api_key: "123") }
 
+  describe "#initialize" do
+    it "defaults to Faraday.default_adapter" do
+      client = described_class.new(api_key: "x")
+      expect(client.adapter).to eq(Faraday.default_adapter)
+    end
+
+    it "accepts a custom adapter" do
+      client = described_class.new(api_key: "x", adapter: :test)
+      expect(client.adapter).to eq(:test)
+    end
+
+    it "accepts an adapter with options" do
+      adapter = [:net_http_persistent, {name: "cohere", pool_size: 10}]
+      client = described_class.new(api_key: "x", adapter: adapter)
+      expect(client.adapter).to eq(adapter)
+    end
+  end
+
   describe "#generate" do
     let(:generate_result) { JSON.parse(File.read("spec/fixtures/generate.json")) }
     let(:response) { OpenStruct.new(body: generate_result) }