Lantern Ruby Client

No Ruby client is required for pg or Sequel. For ActiveRecord and Rails, you can use the lantern gem.

Features

Perform nearest neighbor queries over vectors using vectors or text
Create text embeddings using OpenAI, Cophere, and open-source models

Installation

Add this line to your application's Gemfile:

gem 'lanterndb'

And then execute:

bundle install

Or install it yourself as:

gem install lanterndb

ActiveRecord

Connect to the database

require 'active_record'
require 'lantern'
ActiveRecord::Base.establish_connection("DATABASE_URL")
ActiveRecord::Base.connection.enable_extension("lantern")
conn = ActiveRecord::Base.connection

Create a model

ActiveRecord::Migration.create_table :movies do |t|
  t.column :movie_embedding, :real, array: true
end
conn.execute("INSERT INTO movies (movie_embedding) VALUES ('{0,1,0}'), ('{3,2,4}')")

Embedding generation

embedding1 = Lantern.text_embedding('BAAI/bge-base-en', 'Your text here')

Lantern.set_api_token(openai_token: 'your_openai_token')
embedding2 = Lantern.openai_embedding('text-embedding-3-small', 'Hello')

Lantern.set_api_token(cohere_token: 'your_cohere_token')
embedding3 = Lantern.cohere_embedding('embed-english-v3.0', 'Hello')

A full list of supported models can be found here.

Vector search

This gem provides several ways to perform vector search. We support the following distance metrics:

l2 (Euclidean distance)
cosine (Cosine similarity)

Using pre-computed vectors:

class Document < ApplicationRecord
  has_neighbors :embedding
end

# Find 5 nearest neighbors using L2 distance 
Document.nearest_neighbors(:embedding, [0.1, 0.2, 0.3], distance: 'l2').limit(5)

# Given a document, find 5 nearest neighbors using cosine distance
document = Document.first
document.nearest_neighbors(:embedding, distance: 'cosine').limit(5)

Using text:

class Book < ApplicationRecord
  has_neighbors :embedding
end

# Find 5 nearest neighbors using open-source model
Book.nearest_neighbors(:embedding, 'The quick brown fox', model: 'BAAI/bge-small-en', distance: 'l2').limit(5)

# Find 5 nearest neighbors using OpenAI
Lantern.set_api_token(openai_token: 'your_openai_token')
Book.nearest_neighbors(:embedding, 'The quick brown fox', model: 'openai/text-embedding-3-small', distance: 'cosine').limit(5)

Vector index

To speed up vector search queries, you can add an HNSW index to your model:

class CreateVectorIndex < ActiveRecord::Migration[7.0]
  def up
    add_index :books, :embedding, using: :lantern_hnsw, opclass: :dist_l2sq_ops, name: 'book_embedding_index'
  end
  def down
    remove_index :books, name: 'book_embedding_index'
  end
end

Note: This does not support WITH parameters (e.g., ef_construction, ef, m, dim).

To specify WITH parameters, you can pass them as options with raw SQL:

class CreateHnswIndex < ActiveRecord::Migration[7.0]
  def up
    execute <<-SQL
      CREATE INDEX movie_embedding_hnsw_idx 
      ON movies 
      USING lantern_hnsw (movie_embedding dist_l2sq_ops) 
      WITH (
        ef = 15,
        m = 16,
        ef_construction = 64
      )
    SQL
  end
  def down
    drop index movie_embedding_hnsw_idx
  end
end

Rails

For Rails, enable the Lantern extension using the provided generator:

rails generate lantern:install
rails db:migrate

lanterndb

Development

Runtime