chromable 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b0b02fff83da824d9195113352c1d68dfaaa06bde568eba6448fb4cb79e0919
-  data.tar.gz: 879ac8e61ba6be8a9490174f13517c509409c0d271fd93e9fd06d6a22cf3f1fe
+  metadata.gz: d44fa49957eefd26d00d3fb2315b51f928bd6ecdac7cdc4f849537cac23f036b
+  data.tar.gz: ab51d49d9b558e6d6ba936640026af66258567c0750f2ce11c7b6e01a0b8fea1
 SHA512:
-  metadata.gz: a5a97a3c29f46ee311eafa1d2ea9d51d032568a2bafa64877d22590403152b623318a93d650328af3db1db005e5315b4a90002185a9bfa0c328fcb81dd374276
-  data.tar.gz: cc14d192452c5e4f72ee090f5423c7b78afe1449e1cd1b25009fcb7d4db29394fe50a2093e107c438f9d4b0d60a46ff8f3230f4a6fd9a1aab5f5b33cdc99798e
+  metadata.gz: 2a6be5bd9ec59535eb33a59fc543baa23954ac43c4bc69b8a6e6d19eaab231d313180ba714781f85342f838bfdd4fd70fcfa32c785f663b880128d6a9425a69e
+  data.tar.gz: f63ffea813494e3143c16ed900e190d52866fa11348bac39db894c09ad885e66115b0cb8d0e492f2fb18846b29d8fcb76c4dbdbf3c271e3fd4f6afb417350ee9

data/.rubocop.yml

@@ -2,7 +2,7 @@ require:
   - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 2.6
+  TargetRubyVersion: 3.0
   NewCops: enable
 
 Layout/LineLength:

data/README.md

@@ -32,8 +32,14 @@ class Post < ApplicationRecord
 
   chromable document: :content, metadata: %i[author category], embedder: :embed
 
-  def embed
-    # Call OpenAI now please :)
+  def self.embed(text, **options)
+    options[:is_query] ||= false
+
+    if options[:is_query]
+      # Call OpenAI API to embed `text` as a search query.
+    else
+      # Call OpenAI API to embed `text` as a post content.
+    end
   end
 end
 ```
@@ -41,22 +47,36 @@ end
 Where:
 - `document:` is a callable represents the text content you want to embed and store in ChromaDB.
 - `metadata:` is the list of attributes to be passed to ChromaDB as metadata to be used to filter.
-- `embedder:` is a callable returns the embedding representation for the current instance.
+- `embedder:` is a callable defined in the model that returns the embedding representation for the given `text` and `options`.
 
 Optionaly you can pass `collection_name:`. If not passed, the plural form of the model name will be used.
 
-All `chromable` method arguments are optional.
+The only required option for `chromable` method is `document:`.
 
-At this point, `chromable` will create, update, and destroy the ChromaDB embeddings for your objects based on Rails callbacks.
+At this point, `chromable` will create, update, and destroy the ChromaDB embeddings for your objects based on Rails `after_save` and `after_destroy` callbacks.
+
+To interact with the ChromaDB collection, `chromable` provides `Model.query` method to query the collection and `Model.collection` method to access the collection directly.
+
+```ruby
+puts Post.collection.count # Gets the number of documents inside the collection. Should always match Post.count.
+
+Post.query(
+  query: params[:query],
+  results: 20,
+  where: chroma_search_filters,
+  type: 'query' # `type` here will be passed to `Post.embed` as an option.
+)
+```
+
+`Model.query` accepts the same arguments accepted by `chroma-db` gem `query` method. Extra arguments will be passed to the `embedder:`. Behind the scene, `Model.query` will embed the given `query:` text, then query the collection, and return the closest `results:` records.
 
-To interact with the ChromaDB collection, `chromable` provides `Model.collection` method to retrieve the collection instance.
 Also, `chromable` provides the following methods for each model instance:
 
 - `embedding`: Retrieves the instance's ChromaDB embedding object.
 - `upsert_embedding`: Creates or updates the instance's ChromaDB embedding object.
 - `destroy_embedding`: Destroys the instance's ChromaDB embedding object.
 
-All these methods (including `Model.collection`) are available with `chroma_` prefix, if you have similar methods defined in your model.
+All these methods (including `Model.query` and `Model.collection`) are available with `chroma_` prefix, if you have similar methods defined in your model.
 
 ## Development
 

data/chromable.gemspec

@@ -32,7 +32,6 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'activesupport', '>= 6.1'
   spec.add_dependency 'chroma-db', '>= 0.6.0'
 
   # For more information and examples about making a new gem, check out our

data/lib/chromable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chromable
-  VERSION = '0.1.4'
+  VERSION = '0.2.0'
 end

data/lib/chromable.rb

@@ -1,25 +1,23 @@
 # frozen_string_literal: true
 
-require 'active_support/concern'
-
 require_relative 'chromable/version'
 
 # Ruby on Rails integration for ChromaDB.
 module Chromable
-  extend ActiveSupport::Concern
-
-  included do
-    after_save :chroma_upsert_embedding
-    after_destroy :chroma_destroy_embedding
+  def self.included(base)
+    base.extend ClassMethods
+    base.class_attribute :collection_name
+    base.class_attribute :document
+    base.class_attribute :metadata
+    base.class_attribute :embedder
 
-    class_attribute :collection_name
-    class_attribute :document
-    class_attribute :metadata
-    class_attribute :embedder
+    base.after_save :chroma_upsert_embedding
+    base.after_destroy :chroma_destroy_embedding
   end
 
-  class_methods do
-    def chromable(collection_name: nil, document: nil, metadata: nil, embedder: nil)
+  # Methods to be added to the model class.
+  module ClassMethods
+    def chromable(document:, metadata: nil, embedder: nil, collection_name: nil)
       self.collection_name = (collection_name.presence || name.underscore.pluralize)
       self.document = document
       self.metadata = metadata
@@ -30,7 +28,25 @@ module Chromable
       Chroma::Resources::Collection.get_or_create(collection_name)
     end
 
-    alias_method :collection, :chroma_collection unless method_defined? :collection
+    def chroma_query( # rubocop:disable Metrics/ParameterLists
+      query:,
+      results: 10,
+      where: {},
+      where_document: {},
+      include: %w[metadatas documents distances],
+      **embedder_options
+    )
+      find(chroma_collection.query(
+        query_embeddings: [send(embedder, query, **embedder_options)],
+        results: results,
+        where: where,
+        where_document: where_document,
+        include: include
+      ).map(&:id))
+    end
+
+    alias collection chroma_collection unless method_defined? :collection
+    alias query chroma_query unless method_defined? :query
   end
 
   def chroma_embedding
@@ -38,14 +54,7 @@ module Chromable
   end
 
   def chroma_upsert_embedding
-    self.class.chroma_collection.upsert(
-      Chroma::Resources::Embedding.new(
-        id: id,
-        document: self.class.document ? send(self.class.document) : nil,
-        embedding: self.class.embedder ? send(self.class.embedder) : nil,
-        metadata: self.class.metadata ? self.class.metadata.index_with { |attribute| send(attribute) } : nil
-      )
-    )
+    self.class.chroma_collection.upsert(build_embedding)
   end
 
   def chroma_destroy_embedding
@@ -55,4 +64,17 @@ module Chromable
   alias embedding chroma_embedding unless method_defined? :embedding
   alias upsert_embedding chroma_upsert_embedding unless method_defined? :upsert_embedding
   alias destroy_embedding chroma_destroy_embedding unless method_defined? :destroy_embedding
+
+  private
+
+  def build_embedding
+    document = send(self.class.document)
+
+    Chroma::Resources::Embedding.new(
+      id: id,
+      document: document,
+      embedding: self.class.embedder && self.class.send(self.class.embedder, document),
+      metadata: self.class.metadata&.index_with { |attribute| send(attribute) }
+    )
+  end
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: chromable
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
 - Ali Hamdi Ali Fadel
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2023-12-08 00:00:00.000000000 Z
+date: 2023-12-11 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: activesupport
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '6.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: chroma-db
   requirement: !ruby/object:Gem::Requirement