voyageai 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2fc61d8673a96f88ae7e69d9cfb27f00c741f077fd05793ff921e27c0fd869a
-  data.tar.gz: 4734e6ac573b6251ca1789a37fbf9a9db8294c5e82d63b51613b20bfea793e10
+  metadata.gz: 8d127480aae597e6c15b398061d16beded7be8961fd433372b2550ea1b643d37
+  data.tar.gz: 0a958352786d2994de9bdfbbb198850e15d245a9aed6971efae0f30518494878
 SHA512:
-  metadata.gz: d403d37213b6f9666fbafb58fbc82fcbb9752be9e5d29a9e88d34ea6a198f43d860e809e2d890906bf0c298254d9054fcace76d3e5e8e3f70620abd8d27ec791
-  data.tar.gz: f1ad0fcaf76b8a0a0296dc46507c46d6d9b7e2f47a21b6ca9e2d7e8140483c18ece161ff4570db71649c344679b7a92e80287648324a3700c720e00a7b6e2854
+  metadata.gz: 346dc805e9a46813198189b83805a6d2718cb1a4c244af08f8a1fb5cc4cc251f0fd7ff1b06104669b588da56b5d8fcda3f06795a64fac5a2ee7dc6e8e86faa1f
+  data.tar.gz: 9cf273cdbf521f0b13fc9b30a58517ae7ebdfce1cb23801e64630bcf4887f17d4ed61058d0eb72533fe801e221a7a1fe91df84b802cb5266d7a405af7b68981a

data/README.md

@@ -44,3 +44,17 @@ embed.model # "..."
 embed.usage # "#<VoyageAI::Usage total_tokens=...>"
 embed.embeddings # [[0.0, ...], ...]
 ```
+
+## Configuration
+
+```ruby
+require 'voyageai'
+
+VoyageAI.configure do |config|
+  config.api_key = 'pa-...' # defaults to ENV['VOYAGEAI_API_KEY']
+  config.host = 'https://api.voyageai.com'
+  config.version = 'v1'
+  config.timeout = 15 # seconds
+  config.logger = Logger.new(STDOUT)
+end
+```

data/lib/voyageai/client.rb

@@ -3,8 +3,6 @@
 module VoyageAI
   # A client for interacting with the VoyageAI API.
   class Client
-    BASE_URL = "https://api.voyageai.com/v1"
-
     # An error raised for any HTTP issues.
     class RequestError < StandardError
       attr_accessor :response
@@ -17,27 +15,35 @@ module VoyageAI
     end
 
     # @param api_key [String] optional if ENV['VOYAGEAI_API_KEY'] otherwise required
-    def initialize(api_key: ENV.fetch("VOYAGEAI_API_KEY", nil))
+    # @param host [String] optional
+    # @param version [String] optional
+    # @param logger [Logger] optional
+    def initialize(
+      api_key: VoyageAI.config.api_key,
+      host: VoyageAI.config.host,
+      version: VoyageAI.config.version,
+      logger: VoyageAI.config.logger
+    )
       @api_key = api_key || raise(ArgumentError, "api_key is required or ENV['VOYAGEAI_API_KEY'] must be present")
+      @host = host
+      @version = version
+      @logger = logger
     end
 
     # @return [String]
     def inspect
       masked_api_key = "#{@api_key[..4]}***"
 
-      "#<#{self.class.name} api_key=#{masked_api_key.inspect}>"
+      "#<#{self.class.name} api_key=#{masked_api_key.inspect} host=#{@host.inspect} version=#{@version.inspect}>"
     end
 
     # @param model [String] optional (e.g. VoyageAI::Model::VOYAGE or "voyage-3")
-    # @param input [Array<String>] required (e.g. ["Sample 1", "Sample 2", ...])
+    # @param input [String, Array<String>] required (e.g. "Sample" or ["Sample 1", "Sample 2", ...])
     #
     # @return [Embedding]
     def embed(input, model: Model::VOYAGE)
       payload = { input: arrayify(input), model: model }
-      response = HTTP
-        .accept(:json)
-        .auth("Bearer #{@api_key}")
-        .post("#{BASE_URL}/embeddings", json: payload)
+      response = http.accept(:json).post("/#{@version}/embeddings", json: payload)
 
       raise RequestError.new(response:) unless response.status.ok?
 
@@ -46,6 +52,16 @@ module VoyageAI
 
     private
 
+    # @return [HTTP::Client]
+    def http
+      @http ||= begin
+        http = HTTP.auth("Bearer #{@api_key}").persistent(@host)
+        http = http.use(instrumentation: { instrumenter: Instrumentation.new(logger: @logger) }) if @logger
+        http = http.timeout(@timeout) if @timeout
+        http
+      end
+    end
+
     def arrayify(input)
       input.is_a?(Array) ? input : [input]
     end

data/lib/voyageai/config.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module VoyageAI
+  # A configuration for VoyageAI.
+  #
+  # @example:
+  #   VoyageAI.configure do |config|
+  #     config.api_key = '...'
+  #     config.host = 'https://api.voyageai.com'
+  #     config.version = 'v1'
+  #     config.logger = Logger.new(STDOUT)
+  #     config.timeout = 15
+  #   end
+  class Config
+    DEFAULT_HOST = "https://api.voyageai.com"
+    DEFAULT_VERSION = "v1"
+
+    # @!attribute [rw] api_key
+    #   @return [String, nil]
+    attr_accessor :api_key
+
+    # @!attribute [rw] host
+    #   @return [String, nil]
+    attr_accessor :host
+
+    # @!attribute [rw] version
+    #   @return [String, nil]
+    attr_accessor :version
+
+    # @!attribute [rw] logger
+    #   @return [Logger, nil]
+    attr_accessor :logger
+
+    # @!attribute [rw] timeout
+    #   @return [Integer, nil]
+    attr_accessor :timeout
+
+    # @param api_key [String] optional - defaults to `ENV['VOYAGE_API_KEY']`
+    # @param host [String] optional - defaults to `ENV['VOYAGEAI_HOST']`` w/ fallback to `https://api.voyageai.com`
+    # @param version [String] optional - defaults to `ENV['DEFAULT_VERSION']` w/ fallback to `v1`
+    # @param logger [Logger] optional
+    # @param timeout [Integer] optional
+    def initialize(
+      api_key: ENV.fetch("VOYAGEAI_API_KEY", nil),
+      host: ENV.fetch("VOYAGEAI_HOST", DEFAULT_HOST),
+      version: ENV.fetch("VOYAGEAI_VERSION", DEFAULT_VERSION),
+      logger: nil,
+      timeout: nil
+    )
+      @api_key = api_key
+      @host = host
+      @version = version
+      @logger = logger
+      @timeout = timeout
+    end
+  end
+end

data/lib/voyageai/instrumentation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module VoyageAI
+  # Used for logging via HTTP.
+  class Instrumentation
+    # @param logger [Logger]
+    def initialize(logger:)
+      @logger = logger
+    end
+
+    # @param name [String]
+    # @param payload [Hash]
+    # @option payload [Exception] :error
+    def instrument(name, payload = {})
+      error = payload[:error]
+      return unless error
+
+      @logger.error("#{name}: #{error.message}")
+    end
+
+    # @param payload [Hash]
+    # @option payload [HTTP::Request] :request
+    def start(_, payload)
+      request = payload[:request]
+      @logger.info("#{request.verb.upcase} #{request.uri}")
+    end
+
+    # @param payload [Hash]
+    # @option payload [HTTP::Response] :response
+    def finish(_, payload)
+      response = payload[:response]
+      @logger.info("#{response.status.code} #{response.status.reason}")
+    end
+  end
+end

data/lib/voyageai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VoyageAI
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/lib/voyageai.rb

@@ -7,6 +7,15 @@ loader = Zeitwerk::Loader.for_gem
 loader.inflector.inflect "voyageai" => "VoyageAI"
 loader.setup
 
+# The main entrypoint for VoyageAI.
 module VoyageAI
-  class Error < StandardError; end
+  # @return [VoyageAI::Config]
+  def self.config
+    @config ||= Config.new
+  end
+
+  # @yield [VoyageAI::Config]
+  def self.configure
+    yield config
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: voyageai
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Kevin Sylvestre
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-10-21 00:00:00.000000000 Z
+date: 2024-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http
@@ -38,7 +38,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A library for generating embeddings with https://voyageai.com.
+description: A library for generating embeddings with https://voyageai.com
 email:
 - kevin@ksylvest.com
 executables: []
@@ -51,16 +51,18 @@ files:
 - bin/setup
 - lib/voyageai.rb
 - lib/voyageai/client.rb
+- lib/voyageai/config.rb
 - lib/voyageai/embed.rb
+- lib/voyageai/instrumentation.rb
 - lib/voyageai/model.rb
 - lib/voyageai/usage.rb
 - lib/voyageai/version.rb
-homepage: https://github.com/ksylvest/voyageai.
+homepage: https://github.com/ksylvest/voyageai
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/ksylvest/voyageai.
-  changelog_uri: https://github.com/ksylvest/voyageai./releases
+  homepage_uri: https://github.com/ksylvest/voyageai
+  changelog_uri: https://github.com/ksylvest/voyageai/releases
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []