reranker-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b72a0d8a77aa8b43a90df33ef1aca6e74f886795cedb9decbc2f412f6d788da
+  data.tar.gz: 236483d06f4ca930556ef2bf90a757a7b171cb5175a479cf538086030dbd71a0
+SHA512:
+  metadata.gz: 5bed85be6192b79df97d15732b17d688d596393099e0b8ef70d117f686151fef88a409254726fdd090af0f1f708e208b070ae55867fb2d8c7ca92f328a75b0be
+  data.tar.gz: a1ed43eba939509a20439604d0783ebd49942c6b01a4934ca576d91d29aab156a4703b7ebafd00812386f0f80cb4d967c7e8184f429220074d7a8f52241f6d01

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 0.1.0 (2026-03-08)
+
+- Initial release with all four phases
+- Cohere Rerank API v2 support
+- Jina Reranker API support
+- Local ONNX cross-encoder inference with auto-download from HuggingFace
+- Tokenization via tokenizers gem
+- Sigmoid score normalization for local models
+- Support for ms-marco-MiniLM and BGE reranker models
+- Ensemble reranker with weighted score aggregation
+- Score calibration (min-max, softmax, sigmoid normalization)
+- Concurrent batch reranking with configurable thread pool
+- Logging and metrics with event callbacks
+- Pipeline middleware for RAG integration
+- Rails configuration via initializer (rails generate reranker_ruby:install)
+- ActiveJob for async reranking (RerankerRuby::RerankJob)
+- Global configuration and convenience API (RerankerRuby.rerank)
+- Reciprocal Rank Fusion (RRF)
+- In-memory and Redis caching with TTL
+- String and hash document support with metadata preservation

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johannes Dwi Cahyo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,91 @@
+# reranker-ruby
+
+Cross-encoder reranking for Ruby RAG pipelines. The single biggest quality improvement you can add to retrieval-augmented generation.
+
+Vector search finds candidates fast (approximate). Reranking makes them accurate (precise).
+
+## Installation
+
+```ruby
+gem "reranker-ruby"
+```
+
+## Usage
+
+### Cohere Rerank
+
+```ruby
+require "reranker_ruby"
+
+reranker = RerankerRuby::Cohere.new(api_key: ENV["COHERE_API_KEY"])
+
+query = "What is the capital of France?"
+documents = [
+  "Paris is the capital and largest city of France.",
+  "France is a country in Western Europe.",
+  "The Eiffel Tower is located in Paris.",
+  "Berlin is the capital of Germany.",
+  "Lyon is the second-largest city in France."
+]
+
+results = reranker.rerank(query, documents, top_k: 3)
+
+results.each do |r|
+  puts "#{r.score.round(4)} | #{r.text[0..60]}"
+end
+```
+
+### Jina Rerank
+
+```ruby
+reranker = RerankerRuby::Jina.new(api_key: ENV["JINA_API_KEY"])
+results = reranker.rerank(query, documents, top_k: 3)
+```
+
+### Hash Documents with Metadata
+
+```ruby
+documents = [
+  { text: "Paris is the capital...", source: "wiki", id: "doc1" },
+  { text: "France is a country...", source: "wiki", id: "doc2" },
+]
+
+results = reranker.rerank(query, documents, top_k: 3)
+results.first.metadata  # => { source: "wiki", id: "doc1" }
+```
+
+### Reciprocal Rank Fusion
+
+Combine results from multiple retrieval strategies:
+
+```ruby
+vector_results = ["doc1", "doc3", "doc5"]
+keyword_results = ["doc2", "doc1", "doc4"]
+
+fused = RerankerRuby::RRF.fuse(vector_results, keyword_results, k: 60)
+```
+
+### Caching
+
+```ruby
+reranker = RerankerRuby::Cohere.new(
+  api_key: ENV["COHERE_API_KEY"],
+  cache: RerankerRuby::Cache::Memory.new(ttl: 3600)
+)
+
+reranker.rerank(query, docs, top_k: 5)  # API call
+reranker.rerank(query, docs, top_k: 5)  # cache hit
+```
+
+## Result Object
+
+```ruby
+result.text      # => "Paris is the capital..."
+result.score     # => 0.9987
+result.index     # => 0 (original position)
+result.metadata  # => {} (preserved from input)
+```
+
+## License
+
+MIT

data/lib/reranker_ruby/base.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module RerankerRuby
+  class Error < StandardError; end
+  class APIError < Error; end
+
+  class Base
+    def initialize(api_key: nil, cache: nil)
+      @api_key = api_key
+      @cache = cache
+    end
+
+    def rerank(query, documents, top_k: 10)
+      raise NotImplementedError, "#{self.class}#rerank must be implemented"
+    end
+
+    private
+
+    def instrument(query:, document_count:, top_k:, &block)
+      Logging.instrument(
+        reranker_class: self.class.name,
+        query: query,
+        document_count: document_count,
+        top_k: top_k,
+        &block
+      )
+    end
+
+    def extract_texts(documents)
+      documents.map { |d| d.is_a?(Hash) ? d[:text] || d["text"] : d.to_s }
+    end
+
+    def extract_metadata(document)
+      return {} unless document.is_a?(Hash)
+
+      document.reject { |k, _| k == :text || k == "text" }
+    end
+
+    def cache_key(query, documents)
+      require "digest"
+      Digest::SHA256.hexdigest("#{query}:#{documents.map(&:to_s).join("|")}")
+    end
+
+    def with_cache(query, documents, &block)
+      return yield unless @cache
+
+      key = cache_key(query, documents)
+      cached = @cache.get(key)
+      return cached if cached
+
+      result = yield
+      @cache.set(key, result)
+      result
+    end
+
+    def post(url, body, headers: {})
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Content-Type"] = "application/json"
+      headers.each { |k, v| request[k] = v }
+      request.body = JSON.generate(body)
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise APIError, "HTTP #{response.code}: #{response.body}"
+      end
+
+      JSON.parse(response.body)
+    end
+  end
+end

data/lib/reranker_ruby/batch.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  # Batch reranking — run multiple queries against the same document set concurrently.
+  #
+  # Usage:
+  #   results = RerankerRuby::Batch.rerank(reranker, queries, documents, top_k: 5, threads: 4)
+  #   results[0]  # => results for queries[0]
+  #   results[1]  # => results for queries[1]
+  #
+  class Batch
+    # @param reranker [Base] any reranker instance
+    # @param queries [Array<String>] list of queries
+    # @param documents [Array] shared document set
+    # @param top_k [Integer] number of results per query
+    # @param threads [Integer] concurrency level
+    # @return [Array<Array<Result>>] results per query
+    def self.rerank(reranker, queries, documents, top_k: 10, threads: 4)
+      if threads <= 1
+        return queries.map { |q| reranker.rerank(q, documents, top_k: top_k) }
+      end
+
+      results = Array.new(queries.length)
+      mutex = Mutex.new
+      queue = Queue.new
+
+      queries.each_with_index { |q, i| queue << [q, i] }
+      threads.times { queue << nil } # sentinel values
+
+      workers = threads.times.map do
+        Thread.new do
+          while (item = queue.pop)
+            query, idx = item
+            result = reranker.rerank(query, documents, top_k: top_k)
+            mutex.synchronize { results[idx] = result }
+          end
+        end
+      end
+
+      workers.each(&:join)
+      results
+    end
+  end
+end

data/lib/reranker_ruby/cache/memory.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  module Cache
+    class Memory
+      def initialize(ttl: 3600)
+        @ttl = ttl
+        @store = {}
+      end
+
+      def get(key)
+        entry = @store[key]
+        return nil unless entry
+
+        if Time.now.to_f - entry[:time] > @ttl
+          @store.delete(key)
+          return nil
+        end
+
+        entry[:value]
+      end
+
+      def set(key, value)
+        @store[key] = { value: value, time: Time.now.to_f }
+      end
+
+      def clear
+        @store.clear
+      end
+
+      def size
+        @store.size
+      end
+    end
+  end
+end

data/lib/reranker_ruby/cache/redis.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  module Cache
+    class Redis
+      def initialize(redis:, ttl: 3600, prefix: "reranker:")
+        @redis = redis
+        @ttl = ttl
+        @prefix = prefix
+      end
+
+      def get(key)
+        data = @redis.get("#{@prefix}#{key}")
+        return nil unless data
+
+        Marshal.load(data) # rubocop:disable Security/MarshalLoad
+      end
+
+      def set(key, value)
+        @redis.setex("#{@prefix}#{key}", @ttl, Marshal.dump(value))
+      end
+
+      def clear
+        keys = @redis.keys("#{@prefix}*")
+        @redis.del(*keys) if keys.any?
+      end
+    end
+  end
+end

data/lib/reranker_ruby/cohere.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  class Cohere < Base
+    API_URL = "https://api.cohere.com/v2/rerank"
+    DEFAULT_MODEL = "rerank-v3.5"
+
+    def initialize(api_key:, model: DEFAULT_MODEL, **options)
+      super(**options)
+      @api_key = api_key
+      @model = model
+    end
+
+    def rerank(query, documents, top_k: 10, model: nil)
+      instrument(query: query, document_count: documents.length, top_k: top_k) do
+        with_cache(query, documents) do
+          texts = extract_texts(documents)
+
+          response = post(API_URL, {
+            model: model || @model,
+            query: query,
+            documents: texts,
+            top_n: top_k,
+            return_documents: false
+          }, headers: {
+            "Authorization" => "Bearer #{@api_key}"
+          })
+
+          response["results"].map do |r|
+            idx = r["index"]
+            Result.new(
+              text: texts[idx],
+              score: r["relevance_score"],
+              index: idx,
+              metadata: extract_metadata(documents[idx])
+            )
+          end.sort
+        end
+      end
+    end
+  end
+end

data/lib/reranker_ruby/configuration.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  class Configuration
+    attr_accessor :default_provider, :cohere_api_key, :jina_api_key,
+                  :default_model, :default_top_k, :cache_store, :cache_ttl,
+                  :logger, :onnx_model, :onnx_model_path, :onnx_cache_dir
+
+    def initialize
+      @default_provider = :cohere
+      @cohere_api_key = nil
+      @jina_api_key = nil
+      @default_model = nil
+      @default_top_k = 10
+      @cache_store = nil
+      @cache_ttl = 3600
+      @logger = nil
+      @onnx_model = nil
+      @onnx_model_path = nil
+      @onnx_cache_dir = nil
+    end
+
+    # Build a reranker instance from configuration
+    def build_reranker
+      cache = build_cache
+
+      case default_provider
+      when :cohere
+        raise Error, "cohere_api_key is required" unless cohere_api_key
+        opts = { api_key: cohere_api_key, cache: cache }
+        opts[:model] = default_model if default_model
+        Cohere.new(**opts)
+      when :jina
+        raise Error, "jina_api_key is required" unless jina_api_key
+        opts = { api_key: jina_api_key, cache: cache }
+        opts[:model] = default_model if default_model
+        Jina.new(**opts)
+      when :onnx
+        opts = { cache: cache }
+        opts[:model] = onnx_model if onnx_model
+        opts[:model_path] = onnx_model_path if onnx_model_path
+        opts[:cache_dir] = onnx_cache_dir if onnx_cache_dir
+        Onnx.new(**opts)
+      else
+        raise Error, "Unknown provider: #{default_provider}"
+      end
+    end
+
+    private
+
+    def build_cache
+      case cache_store
+      when :memory
+        Cache::Memory.new(ttl: cache_ttl)
+      when :redis
+        require "redis"
+        Cache::Redis.new(redis: ::Redis.new, ttl: cache_ttl)
+      when nil
+        nil
+      else
+        # Allow passing a pre-built cache instance
+        cache_store
+      end
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+      @reranker = nil
+    end
+
+    # Global reranker instance built from configuration
+    def reranker
+      @reranker ||= configuration.build_reranker
+    end
+
+    # Convenience method for quick reranking
+    def rerank(query, documents, top_k: nil)
+      top_k ||= configuration.default_top_k
+      reranker.rerank(query, documents, top_k: top_k)
+    end
+  end
+end

data/lib/reranker_ruby/ensemble.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  # Combines results from multiple rerankers using weighted score aggregation.
+  #
+  # Usage:
+  #   ensemble = RerankerRuby::Ensemble.new(
+  #     rerankers: [cohere_reranker, jina_reranker],
+  #     weights: [0.6, 0.4],
+  #     normalize: :min_max
+  #   )
+  #   results = ensemble.rerank(query, documents, top_k: 5)
+  #
+  class Ensemble < Base
+    # @param rerankers [Array<Base>] list of reranker instances
+    # @param weights [Array<Float>, nil] weights for each reranker (default: equal)
+    # @param normalize [Symbol] normalization strategy (:min_max, :softmax, :sigmoid, or :none)
+    def initialize(rerankers:, weights: nil, normalize: :min_max, **options)
+      super(**options)
+      @rerankers = rerankers
+      @weights = weights || Array.new(rerankers.length, 1.0 / rerankers.length)
+      @normalize = normalize
+
+      if @weights.length != @rerankers.length
+        raise ArgumentError, "weights length (#{@weights.length}) must match rerankers length (#{@rerankers.length})"
+      end
+    end
+
+    def rerank(query, documents, top_k: 10)
+      with_cache(query, documents) do
+        texts = extract_texts(documents)
+
+        # Collect and normalize results from each reranker
+        all_results = @rerankers.map do |reranker|
+          raw = reranker.rerank(query, documents, top_k: texts.length)
+          normalize_results(raw)
+        end
+
+        # Aggregate scores by original document index
+        aggregated = Hash.new(0.0)
+        all_results.each_with_index do |results, reranker_idx|
+          weight = @weights[reranker_idx]
+          results.each do |result|
+            aggregated[result.index] += result.score * weight
+          end
+        end
+
+        # Build final results sorted by aggregated score
+        aggregated.map do |idx, score|
+          Result.new(
+            text: texts[idx],
+            score: score,
+            index: idx,
+            metadata: extract_metadata(documents[idx])
+          )
+        end.sort.first(top_k)
+      end
+    end
+
+    private
+
+    def normalize_results(results)
+      case @normalize
+      when :min_max  then ScoreNormalizer.min_max(results)
+      when :softmax  then ScoreNormalizer.softmax(results)
+      when :sigmoid  then ScoreNormalizer.sigmoid(results)
+      when :none     then results
+      else raise ArgumentError, "Unknown normalization: #{@normalize}"
+      end
+    end
+  end
+end

data/lib/reranker_ruby/generators/install_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RerankerRuby
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      desc "Creates a RerankerRuby initializer file"
+
+      def create_initializer_file
+        create_file "config/initializers/reranker_ruby.rb", <<~RUBY
+          # frozen_string_literal: true
+
+          RerankerRuby.configure do |config|
+            # Choose your reranking provider: :cohere, :jina, or :onnx
+            config.default_provider = :cohere
+
+            # API keys (use credentials or environment variables)
+            config.cohere_api_key = ENV["COHERE_API_KEY"]
+            # config.jina_api_key = ENV["JINA_API_KEY"]
+
+            # Default number of top results to return
+            config.default_top_k = 10
+
+            # Optional: specify a model
+            # config.default_model = "rerank-v3.5"
+
+            # Optional: enable caching (:memory or :redis)
+            # config.cache_store = :memory
+            # config.cache_ttl = 3600
+
+            # Optional: ONNX local model settings
+            # config.default_provider = :onnx
+            # config.onnx_model = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+          end
+        RUBY
+      end
+    end
+  end
+end

data/lib/reranker_ruby/jina.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  class Jina < Base
+    API_URL = "https://api.jina.ai/v1/rerank"
+    DEFAULT_MODEL = "jina-reranker-v2-base-multilingual"
+
+    def initialize(api_key:, model: DEFAULT_MODEL, **options)
+      super(**options)
+      @api_key = api_key
+      @model = model
+    end
+
+    def rerank(query, documents, top_k: 10, model: nil)
+      instrument(query: query, document_count: documents.length, top_k: top_k) do
+        with_cache(query, documents) do
+          texts = extract_texts(documents)
+
+          response = post(API_URL, {
+            model: model || @model,
+            query: query,
+            documents: texts.map { |t| { text: t } },
+            top_n: top_k
+          }, headers: {
+            "Authorization" => "Bearer #{@api_key}"
+          })
+
+          response["results"].map do |r|
+            idx = r["index"]
+            Result.new(
+              text: texts[idx],
+              score: r["relevance_score"],
+              index: idx,
+              metadata: extract_metadata(documents[idx])
+            )
+          end.sort
+        end
+      end
+    end
+  end
+end

data/lib/reranker_ruby/logging.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module RerankerRuby
+  # Global logging and metrics for reranking operations.
+  #
+  # Usage:
+  #   RerankerRuby::Logging.logger = Logger.new($stdout)
+  #   RerankerRuby::Logging.on_rerank do |event|
+  #     puts "#{event[:reranker]} took #{event[:duration_ms]}ms for #{event[:document_count]} docs"
+  #   end
+  #
+  module Logging
+    class << self
+      attr_writer :logger
+
+      def logger
+        @logger ||= Logger.new($stdout, level: Logger::WARN)
+      end
+
+      # Register a callback for rerank events
+      def on_rerank(&block)
+        callbacks << block
+      end
+
+      def callbacks
+        @callbacks ||= []
+      end
+
+      def clear_callbacks
+        @callbacks = []
+      end
+
+      # Wrap a rerank call with logging and metrics
+      def instrument(reranker_class:, query:, document_count:, top_k:)
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = yield
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round(2)
+
+        event = {
+          reranker: reranker_class,
+          query: query,
+          document_count: document_count,
+          top_k: top_k,
+          result_count: result.length,
+          duration_ms: duration_ms,
+          top_score: result.first.respond_to?(:score) ? result.first.score : nil
+        }
+
+        logger.info { "[RerankerRuby] #{reranker_class} reranked #{document_count} docs in #{duration_ms}ms" }
+        callbacks.each { |cb| cb.call(event) }
+
+        result
+      end
+    end
+  end
+end

data/lib/reranker_ruby/middleware.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  # Pipeline middleware for integration with rag-ruby or any RAG pipeline.
+  # Accepts candidates from a retrieval step and reranks them.
+  #
+  # Usage:
+  #   middleware = RerankerRuby::Middleware.new(
+  #     reranker: RerankerRuby::Cohere.new(api_key: "..."),
+  #     top_k: 5,
+  #     text_key: :content  # key to extract text from candidate hashes
+  #   )
+  #
+  #   reranked = middleware.call(query: "test", candidates: candidates)
+  #
+  class Middleware
+    def initialize(reranker: nil, top_k: nil, text_key: :text)
+      @reranker = reranker
+      @top_k = top_k
+      @text_key = text_key
+    end
+
+    def call(query:, candidates:, top_k: nil)
+      reranker = @reranker || RerankerRuby.reranker
+      top_k ||= @top_k || RerankerRuby.configuration.default_top_k
+
+      documents = candidates.map do |candidate|
+        case candidate
+        when Hash
+          text = candidate[@text_key] || candidate[@text_key.to_s]
+          metadata = candidate.reject { |k, _| k == @text_key || k == @text_key.to_s }
+          { text: text }.merge(metadata)
+        when String
+          candidate
+        else
+          # Duck-type: try to call the text_key method
+          if candidate.respond_to?(@text_key)
+            { text: candidate.send(@text_key) }
+          else
+            candidate.to_s
+          end
+        end
+      end
+
+      reranker.rerank(query, documents, top_k: top_k)
+    end
+  end
+end

data/lib/reranker_ruby/model_downloader.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "fileutils"
+
+module RerankerRuby
+  class ModelDownloader
+    HF_BASE_URL = "https://huggingface.co"
+    DEFAULT_CACHE_DIR = File.join(Dir.home, ".cache", "reranker-ruby", "models")
+
+    # Known ONNX model paths for popular cross-encoder models
+    ONNX_PATHS = {
+      "cross-encoder/ms-marco-MiniLM-L-6-v2" => "onnx/model.onnx",
+      "cross-encoder/ms-marco-MiniLM-L-12-v2" => "onnx/model.onnx",
+      "BAAI/bge-reranker-base" => "onnx/model.onnx",
+      "BAAI/bge-reranker-large" => "onnx/model.onnx",
+      "BAAI/bge-reranker-v2-m3" => "onnx/model.onnx"
+    }.freeze
+
+    def initialize(cache_dir: DEFAULT_CACHE_DIR, token: nil)
+      @cache_dir = cache_dir
+      @token = token
+    end
+
+    # Downloads model and tokenizer files, returns paths
+    # @return [Hash] { model_path:, tokenizer_path: }
+    def download(repo_id)
+      model_dir = File.join(@cache_dir, repo_id.gsub("/", "--"))
+      FileUtils.mkdir_p(model_dir)
+
+      onnx_path = ONNX_PATHS.fetch(repo_id, "onnx/model.onnx")
+
+      model_path = File.join(model_dir, "model.onnx")
+      tokenizer_path = File.join(model_dir, "tokenizer.json")
+
+      download_file(repo_id, onnx_path, model_path) unless File.exist?(model_path)
+      download_file(repo_id, "tokenizer.json", tokenizer_path) unless File.exist?(tokenizer_path)
+
+      { model_path: model_path, tokenizer_path: tokenizer_path }
+    end
+
+    private
+
+    def download_file(repo_id, remote_path, local_path)
+      url = URI("#{HF_BASE_URL}/#{repo_id}/resolve/main/#{remote_path}")
+      download_with_redirects(url, local_path)
+    end
+
+    def download_with_redirects(url, local_path, limit: 5)
+      raise Error, "Too many redirects downloading #{url}" if limit == 0
+
+      Net::HTTP.start(url.host, url.port, use_ssl: url.scheme == "https") do |http|
+        request = Net::HTTP::Get.new(url)
+        request["Authorization"] = "Bearer #{@token}" if @token
+
+        http.request(request) do |response|
+          case response
+          when Net::HTTPRedirection
+            redirect_url = URI(response["location"])
+            return download_with_redirects(redirect_url, local_path, limit: limit - 1)
+          when Net::HTTPSuccess
+            File.open(local_path, "wb") do |file|
+              response.read_body { |chunk| file.write(chunk) }
+            end
+          else
+            raise Error, "Failed to download #{url}: HTTP #{response.code}"
+          end
+        end
+      end
+
+      local_path
+    end
+  end
+end

data/lib/reranker_ruby/onnx.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  class Onnx < Base
+    DEFAULT_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+    MAX_LENGTH = 512
+
+    def initialize(model: nil, model_path: nil, tokenizer: nil, cache_dir: nil, **options)
+      super(**options)
+      require_dependencies!
+
+      if model_path
+        @model_path = model_path
+        tokenizer_id = tokenizer || DEFAULT_MODEL
+        @tokenizer = Tokenizers.from_pretrained(tokenizer_id)
+      else
+        repo_id = model || DEFAULT_MODEL
+        downloader = ModelDownloader.new(cache_dir: cache_dir || ModelDownloader::DEFAULT_CACHE_DIR)
+        paths = downloader.download(repo_id)
+        @model_path = paths[:model_path]
+        @tokenizer = Tokenizers.from_file(paths[:tokenizer_path])
+      end
+
+      @session = OnnxRuntime::InferenceSession.new(@model_path)
+      @tokenizer.enable_truncation(MAX_LENGTH)
+    end
+
+    def rerank(query, documents, top_k: 10)
+      with_cache(query, documents) do
+        texts = extract_texts(documents)
+
+        scores = texts.map { |text| score_pair(query, text) }
+
+        results = texts.each_with_index.map do |text, idx|
+          Result.new(
+            text: text,
+            score: scores[idx],
+            index: idx,
+            metadata: extract_metadata(documents[idx])
+          )
+        end
+
+        results.sort.first(top_k)
+      end
+    end
+
+    private
+
+    def require_dependencies!
+      require "onnxruntime" unless defined?(OnnxRuntime)
+      require "tokenizers" unless defined?(Tokenizers)
+    rescue LoadError => e
+      raise Error, "Missing dependency for local inference: #{e.message}. " \
+                   "Install with: gem install onnxruntime tokenizers"
+    end
+
+    def score_pair(query, document)
+      encoding = @tokenizer.encode(query, document, add_special_tokens: true)
+
+      inputs = {
+        "input_ids" => [encoding.ids],
+        "attention_mask" => [encoding.attention_mask]
+      }
+
+      # Some models also need token_type_ids
+      if @session.inputs.any? { |i| i[:name] == "token_type_ids" }
+        inputs["token_type_ids"] = [encoding.type_ids]
+      end
+
+      output = @session.run(nil, inputs)
+      logit = output[0][0][0]
+
+      sigmoid(logit)
+    end
+
+    def sigmoid(x)
+      1.0 / (1.0 + Math.exp(-x))
+    end
+  end
+end

data/lib/reranker_ruby/railtie.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  class Railtie < ::Rails::Railtie
+    initializer "reranker_ruby.configure" do
+      # Apply Rails logger if none configured
+      config.after_initialize do
+        if RerankerRuby.configuration.logger.nil?
+          RerankerRuby::Logging.logger = Rails.logger
+        else
+          RerankerRuby::Logging.logger = RerankerRuby.configuration.logger
+        end
+      end
+    end
+
+    generators do
+      require_relative "generators/install_generator"
+    end
+  end
+end

data/lib/reranker_ruby/rerank_job.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  # ActiveJob for async reranking of large result sets.
+  #
+  # Usage:
+  #   RerankerRuby::RerankJob.perform_later(
+  #     query: "What is Ruby?",
+  #     documents: ["doc1", "doc2", ...],
+  #     top_k: 5,
+  #     callback: "MyCallback"
+  #   )
+  #
+  # The callback class must implement .on_rerank_complete(query, results):
+  #
+  #   class MyCallback
+  #     def self.on_rerank_complete(query, results)
+  #       # results is an array of hashes: [{ text:, score:, index:, metadata: }, ...]
+  #     end
+  #   end
+  #
+  class RerankJob < ActiveJob::Base
+    queue_as :default
+
+    def perform(query:, documents:, top_k: nil, callback: nil)
+      top_k ||= RerankerRuby.configuration.default_top_k
+      results = RerankerRuby.rerank(query, documents, top_k: top_k)
+
+      if callback
+        callback_class = Object.const_get(callback)
+        callback_class.on_rerank_complete(query, results.map(&:to_h))
+      end
+
+      results
+    end
+  end
+end

data/lib/reranker_ruby/result.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  class Result
+    attr_reader :text, :score, :index, :metadata
+
+    def initialize(text:, score:, index:, metadata: {})
+      @text = text
+      @score = score.to_f
+      @index = index
+      @metadata = metadata
+    end
+
+    def to_h
+      { text: @text, score: @score, index: @index, metadata: @metadata }
+    end
+
+    def <=>(other)
+      other.score <=> @score
+    end
+  end
+end

data/lib/reranker_ruby/rrf.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  class RRF
+    def self.fuse(*ranked_lists, k: 60)
+      scores = Hash.new(0.0)
+      ranked_lists.each do |list|
+        list.each_with_index do |id, rank|
+          scores[id] += 1.0 / (k + rank + 1)
+        end
+      end
+      scores.sort_by { |_, score| -score }.map(&:first)
+    end
+  end
+end

data/lib/reranker_ruby/score_normalizer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  # Normalizes scores across different reranker models to a common [0, 1] scale.
+  # Different models produce scores on different scales — this makes them comparable.
+  module ScoreNormalizer
+    # Min-max normalization to [0, 1]
+    def self.min_max(results)
+      return results if results.empty?
+
+      scores = results.map(&:score)
+      min = scores.min
+      max = scores.max
+      range = max - min
+
+      return results.map { |r| with_score(r, 1.0) } if range.zero?
+
+      results.map { |r| with_score(r, (r.score - min) / range) }
+    end
+
+    # Softmax normalization — scores sum to 1.0, preserves relative ordering
+    def self.softmax(results)
+      return results if results.empty?
+
+      scores = results.map(&:score)
+      max_score = scores.max
+      exps = scores.map { |s| Math.exp(s - max_score) } # subtract max for numerical stability
+      sum = exps.sum
+
+      results.each_with_index.map do |r, i|
+        with_score(r, exps[i] / sum)
+      end
+    end
+
+    # Sigmoid normalization — each score independently mapped to [0, 1]
+    def self.sigmoid(results)
+      results.map { |r| with_score(r, 1.0 / (1.0 + Math.exp(-r.score))) }
+    end
+
+    def self.with_score(result, new_score)
+      Result.new(
+        text: result.text,
+        score: new_score,
+        index: result.index,
+        metadata: result.metadata
+      )
+    end
+    private_class_method :with_score
+  end
+end

data/lib/reranker_ruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RerankerRuby
+  VERSION = "0.1.0"
+end

data/lib/reranker_ruby.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "reranker_ruby/version"
+require_relative "reranker_ruby/result"
+require_relative "reranker_ruby/base"
+require_relative "reranker_ruby/cohere"
+require_relative "reranker_ruby/jina"
+require_relative "reranker_ruby/rrf"
+require_relative "reranker_ruby/model_downloader"
+require_relative "reranker_ruby/score_normalizer"
+require_relative "reranker_ruby/ensemble"
+require_relative "reranker_ruby/batch"
+require_relative "reranker_ruby/logging"
+require_relative "reranker_ruby/cache/memory"
+require_relative "reranker_ruby/configuration"
+require_relative "reranker_ruby/middleware"
+
+module RerankerRuby
+  autoload :Onnx, "reranker_ruby/onnx"
+  autoload :RerankJob, "reranker_ruby/rerank_job"
+end
+
+require_relative "reranker_ruby/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: reranker-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Johannes Dwi Cahyo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A cross-encoder reranking library for Ruby. Supports Cohere, Jina, and
+  local ONNX models. The single biggest quality improvement you can add to a RAG pipeline.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/reranker_ruby.rb
+- lib/reranker_ruby/base.rb
+- lib/reranker_ruby/batch.rb
+- lib/reranker_ruby/cache/memory.rb
+- lib/reranker_ruby/cache/redis.rb
+- lib/reranker_ruby/cohere.rb
+- lib/reranker_ruby/configuration.rb
+- lib/reranker_ruby/ensemble.rb
+- lib/reranker_ruby/generators/install_generator.rb
+- lib/reranker_ruby/jina.rb
+- lib/reranker_ruby/logging.rb
+- lib/reranker_ruby/middleware.rb
+- lib/reranker_ruby/model_downloader.rb
+- lib/reranker_ruby/onnx.rb
+- lib/reranker_ruby/railtie.rb
+- lib/reranker_ruby/rerank_job.rb
+- lib/reranker_ruby/result.rb
+- lib/reranker_ruby/rrf.rb
+- lib/reranker_ruby/score_normalizer.rb
+- lib/reranker_ruby/version.rb
+homepage: https://github.com/johannesdwicahyo/reranker-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/johannesdwicahyo/reranker-ruby
+  source_code_uri: https://github.com/johannesdwicahyo/reranker-ruby
+  changelog_uri: https://github.com/johannesdwicahyo/reranker-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Cross-encoder reranking for Ruby RAG pipelines
+test_files: []