neighbor 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0ab3641b145d2f7b83ab5b9639b63a97243aeaadd82e057ff71d30440eccf86
-  data.tar.gz: 0042cdebaff064ee3c27658f2a1edf348768bc7022e14fc12a15eabf1f4cb20f
+  metadata.gz: 0c8b5d19222742f33f51f2c30f9d03108ebd3ed99908a7e9dd5f4e49caa2e225
+  data.tar.gz: c9cfa942f2cdd8b9757c9ecfe5e89d0aced11263f8a559004ee15fa0c8adb3f4
 SHA512:
-  metadata.gz: 0c500661e9557575032762af3f54b36259a4b87493cd0ed30c559e9fb1b21c18c70b4c410becd1095aed64bbd86d8aac527cbd498a14717708030905ecc84d6e
-  data.tar.gz: 75a62b2a13ecb8a34bb6595b71d0aa5686111a390a32ab610c10bcaf8d1e688541b742073658498e20a4724a9f9a1e7ab718f0a2298a7214e5c1cbffdb47c2e2
+  metadata.gz: e9e0050031ce7691baa9242b3b6b5aa76afb1fe7c63575129e68b2f5c027143b3c08f68a7babfcf2a9b02f1d9327679f75e9c40b95ac2245ea7c8dd3025d3cdb
+  data.tar.gz: a9c505740cba454437617733d4025360848a16ef9a4c9c83fc16d5bc82a3e5521c77e3cba874ef3cf318cf3a1e319567958a6156481f7fd82ef72ebaa87d97eb

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.3.2 (2023-12-12)
+
+- Added deprecation warning for `has_neighbors` without an attribute name
+- Added deprecation warning for `nearest_neighbors` without an attribute name
+
+## 0.3.1 (2023-09-25)
+
+- Added support for passing multiple attributes to `has_neighbors`
+- Fixed error with `nearest_neighbors` scope with Ruby 3.2 and Active Record 6.1
+
 ## 0.3.0 (2023-07-24)
 
 - Dropped support for Ruby < 3 and Active Record < 6.1

data/README.md

@@ -14,7 +14,7 @@ gem "neighbor"
 
 ## Choose An Extension
 
-Neighbor supports two extensions: [cube](https://www.postgresql.org/docs/current/cube.html) and [vector](https://github.com/pgvector/pgvector). cube ships with Postgres, while vector supports approximate nearest neighbor search.
+Neighbor supports two extensions: [cube](https://www.postgresql.org/docs/current/cube.html) and [vector](https://github.com/pgvector/pgvector). cube ships with Postgres, while vector supports more dimensions and approximate nearest neighbor search.
 
 For cube, run:
 
@@ -35,7 +35,7 @@ rails db:migrate
 Create a migration
 
 ```ruby
-class AddNeighborVectorToItems < ActiveRecord::Migration[7.0]
+class AddEmbeddingToItems < ActiveRecord::Migration[7.1]
   def change
     add_column :items, :embedding, :cube
     # or
@@ -114,21 +114,29 @@ end
 For vector, add an approximate index to speed up queries. Create a migration with:
 
 ```ruby
-class AddIndexToItemsNeighborVector < ActiveRecord::Migration[7.0]
+class AddIndexToItemsEmbedding < ActiveRecord::Migration[7.1]
   def change
     add_index :items, :embedding, using: :ivfflat, opclass: :vector_l2_ops
+    # or with pgvector 0.5.0+
+    add_index :items, :embedding, using: :hnsw, opclass: :vector_l2_ops
   end
 end
 ```
 
 Use `:vector_cosine_ops` for cosine distance and `:vector_ip_ops` for inner product.
 
-Set the number of probes
+Set the number of probes with IVFFlat
 
 ```ruby
 Item.connection.execute("SET ivfflat.probes = 3")
 ```
 
+Or the size of the dynamic candidate list with HNSW
+
+```ruby
+Item.connection.execute("SET hnsw.ef_search = 100")
+```
+
 ## Examples
 
 - [OpenAI Embeddings](#openai-embeddings)
@@ -139,14 +147,14 @@ Item.connection.execute("SET ivfflat.probes = 3")
 Generate a model
 
 ```sh
-rails generate model Article content:text embedding:vector{1536}
+rails generate model Document content:text embedding:vector{1536}
 rails db:migrate
 ```
 
 And add `has_neighbors`
 
 ```ruby
-class Article < ApplicationRecord
+class Document < ApplicationRecord
   has_neighbors :embedding
 end
 ```
@@ -184,18 +192,18 @@ embeddings = fetch_embeddings(input)
 Store the embeddings
 
 ```ruby
-articles = []
+documents = []
 input.zip(embeddings) do |content, embedding|
-  articles << {content: content, embedding: embedding}
+  documents << {content: content, embedding: embedding}
 end
-Article.insert_all!(articles) # use create! for Active Record < 6
+Document.insert_all!(documents)
 ```
 
 And get similar articles
 
 ```ruby
-article = Article.first
-article.nearest_neighbors(:embedding, distance: "inner_product").first(5).map(&:content)
+document = Document.first
+document.nearest_neighbors(:embedding, distance: "cosine").first(5).map(&:content)
 ```
 
 See the [complete code](examples/openai_embeddings.rb)

data/lib/neighbor/model.rb

@@ -1,7 +1,12 @@
 module Neighbor
   module Model
-    def has_neighbors(attribute_name = :neighbor_vector, dimensions: nil, normalize: nil)
-      attribute_name = attribute_name.to_sym
+    def has_neighbors(*attribute_names, dimensions: nil, normalize: nil)
+      if attribute_names.empty?
+        warn "[neighbor] has_neighbors without an attribute name is deprecated"
+        attribute_names << :neighbor_vector
+      else
+        attribute_names.map!(&:to_sym)
+      end
 
       class_eval do
         @neighbor_attributes ||= {}
@@ -19,15 +24,28 @@ module Neighbor
           end
         end
 
-        raise Error, "has_neighbors already called for #{attribute_name.inspect}" if neighbor_attributes[attribute_name]
-        @neighbor_attributes[attribute_name] = {dimensions: dimensions, normalize: normalize}
+        attribute_names.each do |attribute_name|
+          raise Error, "has_neighbors already called for #{attribute_name.inspect}" if neighbor_attributes[attribute_name]
+          @neighbor_attributes[attribute_name] = {dimensions: dimensions, normalize: normalize}
+
+          attribute attribute_name, Neighbor::Vector.new(dimensions: dimensions, normalize: normalize, model: self, attribute_name: attribute_name)
+        end
 
-        attribute attribute_name, Neighbor::Vector.new(dimensions: dimensions, normalize: normalize, model: self, attribute_name: attribute_name)
+        return if @neighbor_attributes.size != attribute_names.size
 
-        return if @neighbor_attributes.size != 1
+        scope :nearest_neighbors, ->(attribute_name, vector = nil, options = nil) {
+          # cannot use keyword arguments with scope with Ruby 3.2 and Active Record 6.1
+          # https://github.com/rails/rails/issues/46934
+          if options.nil? && vector.is_a?(Hash)
+            options = vector
+            vector = nil
+          end
+          raise ArgumentError, "missing keyword: :distance" unless options.is_a?(Hash) && options.key?(:distance)
+          distance = options.delete(:distance)
+          raise ArgumentError, "unknown keywords: #{options.keys.map(&:inspect).join(", ")}" if options.any?
 
-        scope :nearest_neighbors, ->(attribute_name, vector = nil, distance:) {
           if vector.nil? && !attribute_name.nil? && attribute_name.respond_to?(:to_a)
+            warn "[neighbor] nearest_neighbors without an attribute name is deprecated"
             vector = attribute_name
             attribute_name = :neighbor_vector
           end
@@ -107,7 +125,11 @@ module Neighbor
             .order(Arel.sql(order))
         }
 
-        def nearest_neighbors(attribute_name = :neighbor_vector, **options)
+        def nearest_neighbors(attribute_name = nil, **options)
+          if attribute_name.nil?
+            warn "[neighbor] nearest_neighbors without an attribute name is deprecated"
+            attribute_name = :neighbor_vector
+          end
           attribute_name = attribute_name.to_sym
           # important! check if neighbor attribute before calling send
           raise ArgumentError, "Invalid attribute" unless self.class.neighbor_attributes[attribute_name]

data/lib/neighbor/type/cube.rb

@@ -0,0 +1,38 @@
+module Neighbor
+  module Type
+    class Cube < ActiveRecord::Type::String
+      def type
+        :cube
+      end
+
+      def cast(value)
+        if value.is_a?(Array)
+          if value.first.is_a?(Array)
+            value.map { |v| cast_point(v) }.join(", ")
+          else
+            cast_point(value)
+          end
+        else
+          super
+        end
+      end
+
+      # TODO uncomment in 0.4.0
+      # def deserialize(value)
+      #   if value.nil?
+      #     super
+      #   elsif value.include?("),(")
+      #     value[1..-1].split("),(").map { |v| v.split(",").map(&:to_f) }
+      #   else
+      #     value[1..-1].split(",").map(&:to_f)
+      #   end
+      # end
+
+      private
+
+      def cast_point(value)
+        "(#{value.map(&:to_f).join(", ")})"
+      end
+    end
+  end
+end

data/lib/neighbor/type/vector.rb

@@ -0,0 +1,14 @@
+module Neighbor
+  module Type
+    class Vector < ActiveRecord::Type::String
+      def type
+        :vector
+      end
+
+      # TODO uncomment in 0.4.0
+      # def deserialize(value)
+      #   value[1..-1].split(",").map(&:to_f) unless value.nil?
+      # end
+    end
+  end
+end

data/lib/neighbor/version.rb

@@ -1,3 +1,3 @@
 module Neighbor
-  VERSION = "0.3.0"
+  VERSION = "0.3.2"
 end

data/lib/neighbor.rb

@@ -10,10 +10,10 @@ module Neighbor
   module RegisterTypes
     def initialize_type_map(m = type_map)
       super
-      m.register_type "cube", ActiveRecord::ConnectionAdapters::PostgreSQL::OID::SpecializedString.new(:cube)
+      m.register_type "cube", Type::Cube.new
       m.register_type "vector" do |_, _, sql_type|
         limit = extract_limit(sql_type)
-        ActiveRecord::ConnectionAdapters::PostgreSQL::OID::SpecializedString.new(:vector, limit: limit)
+        Type::Vector.new(limit: limit)
       end
     end
   end
@@ -22,6 +22,8 @@ end
 ActiveSupport.on_load(:active_record) do
   require_relative "neighbor/model"
   require_relative "neighbor/vector"
+  require_relative "neighbor/type/cube"
+  require_relative "neighbor/type/vector"
 
   extend Neighbor::Model
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: neighbor
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Andrew Kane
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-25 00:00:00.000000000 Z
+date: 2023-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -40,6 +40,8 @@ files:
 - lib/neighbor.rb
 - lib/neighbor/model.rb
 - lib/neighbor/railtie.rb
+- lib/neighbor/type/cube.rb
+- lib/neighbor/type/vector.rb
 - lib/neighbor/vector.rb
 - lib/neighbor/version.rb
 homepage: https://github.com/ankane/neighbor