ruby_llm-voyage 0.1.0

data/lib/ruby_llm/voyage.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'ruby_llm/voyage/version'
+require 'ruby_llm/voyage/results'
+require 'ruby_llm/voyage/vector_decoder'
+require 'ruby_llm/providers/voyage'
+
+# RubyLLM framework namespace.
+module RubyLLM
+  # Voyage retrieval APIs for RubyLLM: embeddings, reranking, contextualized
+  # chunk embeddings, and files.
+  module Voyage
+    # Generates embeddings with a Voyage text embedding model.
+    #
+    # This facade exposes Voyage-specific options that are not first-class
+    # keywords on +RubyLLM.embed+ in RubyLLM 1.x. It returns the same
+    # {RubyLLM::Embedding} result type and emits the same instrumentation event.
+    #
+    # @param text [String, Array<String>] one input or a batch of inputs
+    # @param model [String, nil] Voyage model ID, such as +voyage-4-lite+;
+    #   defaults to +config.default_embedding_model+
+    # @param dimensions [Integer, nil] requested output dimensions; defaults
+    #   to +config.voyage_default_output_dimension+
+    # @param input_type [String, Symbol, nil] +query+, +document+, or +nil+
+    # @param truncation [Boolean, nil] whether Voyage may truncate long inputs
+    # @param output_dtype [String, Symbol, nil] +float+, +int8+, +uint8+,
+    #   +binary+, +ubinary+, or +nil+
+    # @param encoding_format [String, Symbol, nil] +base64+ or +nil+
+    # @param provider_options [Hash] trusted fields merged into the Voyage
+    #   request after named options
+    # @param context [RubyLLM::Context, nil] isolated RubyLLM configuration
+    # @return [RubyLLM::Embedding] vectors, model ID, and input-token usage
+    # @raise [RubyLLM::ConfigurationError] when the Voyage API key is missing
+    # @raise [RubyLLM::Error] when Voyage returns an unsuccessful response
+    #
+    # @example Embed a retrieval query
+    #   embedding = RubyLLM::Voyage.embed(
+    #     "How do I configure SSO?",
+    #     model: "voyage-4-lite",
+    #     input_type: :query,
+    #     dimensions: 512
+    #   )
+    #   embedding.vectors #=> Array<Float>
+    def self.embed(text, model: nil, dimensions: nil, input_type: UNSET, truncation: UNSET, output_dtype: UNSET,
+                   encoding_format: UNSET, provider_options: {}, context: nil)
+      validate_input!(:text, text)
+      config = context&.config || RubyLLM.config
+      model ||= config.default_embedding_model
+      provider = Providers::Voyage.new(config)
+      payload = {
+        provider: provider.slug,
+        model: model,
+        input: text,
+        dimensions: dimensions,
+        input_type: input_type,
+        truncation: truncation,
+        output_dtype: output_dtype,
+        encoding_format: encoding_format
+      }.reject { |_key, value| value.equal?(UNSET) }
+
+      RubyLLM.instrument('embedding.ruby_llm', payload, config:) do |event|
+        result = provider.embed(
+          text,
+          model:,
+          dimensions:,
+          input_type:,
+          truncation:,
+          output_dtype:,
+          encoding_format:,
+          provider_options:
+        )
+        event[:result] = result
+        event[:response_model] = result.model
+        event[:input_tokens] = result.input_tokens
+        result
+      end
+    end
+
+    # Embeds search text for the query side of retrieval.
+    #
+    # Equivalent to {.embed} with +input_type: 'query'+. Pair with
+    # {.embed_documents} so Voyage optimizes both sides of retrieval, and
+    # configure +default_embedding_model+ and +voyage_default_output_dimension+ once
+    # to keep call sites small.
+    #
+    # @param text [String, Array<String>] one search input or a batch
+    # @param options [Hash] the same options as {.embed}, except +input_type+
+    # @return [RubyLLM::Embedding]
+    # @raise [ArgumentError] when +input_type+ is passed
+    #
+    # @example
+    #   RubyLLM::Voyage.embed_query('How do I configure SSO?').vectors
+    def self.embed_query(text, **options)
+      embed_side(text, 'query', __method__, options)
+    end
+
+    # Embeds content for the document side of retrieval.
+    #
+    # Equivalent to {.embed} with +input_type: 'document'+. Accepts one text
+    # or a batch of up to 1,000.
+    #
+    # @param texts [String, Array<String>] content to index
+    # @param options [Hash] the same options as {.embed}, except +input_type+
+    # @return [RubyLLM::Embedding]
+    # @raise [ArgumentError] when +input_type+ is passed
+    #
+    # @example
+    #   RubyLLM::Voyage.embed_documents(articles.map(&:content)).vectors
+    def self.embed_documents(texts, **options)
+      embed_side(texts, 'document', __method__, options)
+    end
+
+    # Reranks documents for a query with a Voyage reranker.
+    # @param query [String]
+    # @param documents [Array<String>]
+    # @param model [String]
+    # @param top_k [Integer, nil]
+    # @param return_documents [Boolean]
+    # @param truncation [Boolean]
+    # @param provider_options [Hash]
+    # @param context [RubyLLM::Context, nil]
+    # @return [RubyLLM::Voyage::Reranking]
+    def self.rerank(query:, documents:, model: 'rerank-2.5-lite', top_k: nil, return_documents: UNSET,
+                    truncation: UNSET, provider_options: {}, context: nil)
+      validate_input!(:query, query)
+      validate_input!(:documents, documents)
+      config = context&.config || RubyLLM.config
+      provider = Providers::Voyage.new(config)
+      payload = { model: model, query: query, document_count: documents.length }
+      RubyLLM.instrument('rerank.voyage', payload, config:) do |event|
+        result = provider.rerank(
+          query:, documents:, model:, top_k:, return_documents:, truncation:, provider_options:
+        )
+        event[:result] = result
+        event[:response_model] = result.model
+        event[:input_tokens] = result.input_tokens
+        result
+      end
+    end
+
+    # Generates context-aware embeddings for grouped document chunks.
+    # @param inputs [Array<String>, Array<Array<String>>]
+    # @param model [String]
+    # @param input_type [String, Symbol, nil]
+    # @param dimensions [Integer, nil] defaults to
+    #   +config.voyage_default_output_dimension+
+    # @param output_dtype [String, Symbol, nil]
+    # @param encoding_format [String, Symbol, nil]
+    # @param auto_chunk [Boolean, nil]
+    # @param chunk_size [Integer, nil]
+    # @param chunk_overlap [Integer, nil]
+    # @param provider_options [Hash]
+    # @param context [RubyLLM::Context, nil]
+    # @return [RubyLLM::Voyage::ContextualizedEmbedding]
+    def self.contextualized_embed(inputs, model: 'voyage-context-4', input_type: UNSET, dimensions: nil,
+                                  output_dtype: UNSET, encoding_format: UNSET, auto_chunk: nil, chunk_size: nil,
+                                  chunk_overlap: nil, provider_options: {}, context: nil)
+      validate_input!(:inputs, inputs)
+      config = context&.config || RubyLLM.config
+      provider = Providers::Voyage.new(config)
+      payload = { model: model, input_count: inputs.length, input_type: input_type, auto_chunk: auto_chunk }
+                .reject { |_key, value| value.equal?(UNSET) }
+      RubyLLM.instrument('contextualized_embedding.voyage', payload, config:) do |event|
+        result = provider.contextualized_embed(
+          inputs, model:, input_type:, dimensions:, output_dtype:, encoding_format:, auto_chunk:, chunk_size:,
+                  chunk_overlap:, provider_options:
+        )
+        event[:result] = result
+        event[:response_model] = result.model
+        event[:input_tokens] = result.input_tokens
+        result
+      end
+    end
+
+    # Uploads a JSONL file to Voyage.
+    # @param path [String, Pathname]
+    # @param purpose [String]
+    # @param context [RubyLLM::Context, nil]
+    # @return [RubyLLM::Voyage::VoyageFile]
+    def self.upload_file(path, purpose: 'batch', context: nil)
+      provider_for(context).upload_file(path, purpose:)
+    end
+
+    # Retrieves metadata for one Voyage file.
+    # @param file_id [String]
+    # @param context [RubyLLM::Context, nil]
+    # @return [RubyLLM::Voyage::VoyageFile]
+    def self.retrieve_file(file_id, context: nil)
+      provider_for(context).retrieve_file(file_id)
+    end
+
+    # Lists Voyage files with cursor pagination.
+    # @param purpose [String, nil]
+    # @param limit [Integer, nil]
+    # @param order [String, Symbol, nil]
+    # @param after [String, nil]
+    # @param context [RubyLLM::Context, nil]
+    # @return [RubyLLM::Voyage::Page]
+    def self.list_files(purpose: nil, limit: nil, order: nil, after: nil, context: nil)
+      provider_for(context).list_files(purpose:, limit:, order: order&.to_s, after:)
+    end
+
+    # Downloads a Voyage file's raw contents.
+    # @param file_id [String]
+    # @param context [RubyLLM::Context, nil]
+    # @return [String]
+    def self.file_content(file_id, context: nil)
+      provider_for(context).file_content(file_id)
+    end
+
+    # Deletes one or more Voyage files atomically.
+    # @param file_ids [Array<String>]
+    # @param context [RubyLLM::Context, nil]
+    # @return [RubyLLM::Voyage::FileDeletion]
+    def self.delete_files(file_ids, context: nil)
+      provider_for(context).delete_files(file_ids)
+    end
+
+    class << self
+      # Alias of {.retrieve_file}, matching the +find_file+ naming used by
+      # RubyLLM's provider file API.
+      alias find_file retrieve_file
+
+      # Alias of {.file_content}, matching the +download_file+ naming used by
+      # RubyLLM's provider file API.
+      alias download_file file_content
+    end
+
+    # Builds a configured Voyage provider for resource operations.
+    # @api private
+    def self.provider_for(context)
+      Providers::Voyage.new(context&.config || RubyLLM.config)
+    end
+    private_class_method :provider_for
+
+    # Fails fast on inputs Voyage would reject, before any network request.
+    # @api private
+    def self.validate_input!(name, value)
+      raise ArgumentError, "#{name} cannot be nil" if value.nil?
+      raise ArgumentError, "#{name} cannot be empty" if value.respond_to?(:empty?) && value.empty?
+    end
+    private_class_method :validate_input!
+
+    # Embeds one retrieval side with a fixed input type.
+    # @api private
+    def self.embed_side(text, input_type, method_name, options)
+      if options.key?(:input_type)
+        raise ArgumentError, "#{method_name} sets input_type: '#{input_type}'; use embed to pass another input_type"
+      end
+
+      embed(text, input_type: input_type, **options)
+    end
+    private_class_method :embed_side
+  end
+end
+
+RubyLLM::Provider.register :voyage, RubyLLM::Providers::Voyage

data/lib/ruby_llm-voyage.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'ruby_llm/voyage'

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-voyage
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel Insley
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A RubyLLM extension for Voyage embeddings, reranking, contextualized
+  chunks, and files.
+email:
+- dan@insley.ca
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- SECURITY.md
+- docs/RELEASING.md
+- lib/ruby_llm-voyage.rb
+- lib/ruby_llm/providers/voyage.rb
+- lib/ruby_llm/providers/voyage/contextualized_embeddings.rb
+- lib/ruby_llm/providers/voyage/embeddings.rb
+- lib/ruby_llm/providers/voyage/files.rb
+- lib/ruby_llm/providers/voyage/reranking.rb
+- lib/ruby_llm/voyage.rb
+- lib/ruby_llm/voyage/results.rb
+- lib/ruby_llm/voyage/vector_decoder.rb
+- lib/ruby_llm/voyage/version.rb
+homepage: https://github.com/dinsley/ruby_llm-voyage
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dinsley/ruby_llm-voyage
+  source_code_uri: https://github.com/dinsley/ruby_llm-voyage/tree/v0.1.0
+  changelog_uri: https://github.com/dinsley/ruby_llm-voyage/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dinsley/ruby_llm-voyage/issues
+  documentation_uri: https://www.rubydoc.info/gems/ruby_llm-voyage/0.1.0
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options:
+- "--main"
+- README.md
+- "--markup"
+- markdown
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Voyage retrieval APIs for RubyLLM
+test_files: []