Reranker

A flexible Ruby library for reranking arrays of items using pluggable scorers. Useful for improving search result relevance by reordering items based on custom scoring algorithms.

Installation

Reranker is distributed from GitHub releases rather than RubyGems. Add it to an application's Gemfile with a tagged release:

gem "reranker", git: "https://github.com/MITLibraries/reranker.git", tag: "v0.1.0"

Note

If you find this gem useful and would prefer we distribute via RubyGems let us know.

Then install it with Bundler:

bundle install

Usage

Basic Example: Merging Two Lists

require 'reranker'

# Create a zipper merge scorer to combine results from two search APIs
scorer = Reranker::ZipperMergeScorer.new
reranker = Reranker::Reranker.new(scorer)

# Define items from two different sources (already normalized)
list_a = [
  { content: "Result 1 from API A", source: "api_a", score: 0.95 },
  { content: "Result 2 from API A", source: "api_a" }
]

list_b = [
  { content: "Result 1 from API B", source: "api_b", relevance: 0.89 },
  { content: "Result 2 from API B", source: "api_b" }
]

# Merge and rerank the lists
merged = reranker.rerank(list_a, list_b, query: "search term")

# Output: results interleaved alternately: A1, B1, A2, B2
merged.each do |item|
  puts "#{item[:content]} (source: #{item[:source]})"
end

Reranking a Single List

require 'reranker'

# Create a scorer and reranker
scorer = Reranker::RandomScorer.new
reranker = Reranker::Reranker.new(scorer)

# Rerank a single list (no second list)
items = [
  { content: "First result" },
  { content: "Second result" },
  { content: "Third result" }
]

result = reranker.rerank(items, query: "search term")

# When using RandomScorer with a single list, items are shuffled
result.each { |item| puts item[:content] }

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version for application use, update the version number in version.rb, update CHANGELOG.md, merge the changes to main, and create a GitHub Release with a matching tag such as v0.1.0. Applications should reference the release tag in their Gemfile.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/MITLibraries/reranker. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Reranker project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.