chroma-db 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd1f6255d588aae1829e27a9b6c75f33367fb131d22ed7aa6074aebe9f1a63e
-  data.tar.gz: 7b5d9c7bec11e80bcce275af7b2c1f4ea33965fd92a2955b8d835853d2ea5e2d
+  metadata.gz: 2d7ef50774b1e00c56ee2f67670afc3b7d2fd0760ace64627985ed6460701b7b
+  data.tar.gz: 9e4f771c7ab2fe8b3ceead3efa3dbe3e03155d2ab8823c895b90e72ac78f7f9b
 SHA512:
-  metadata.gz: 453ba9818006fc4a28e56160919d1b85cd797c5f67de92a4b06c05a3a9edc15e33b32b1ef819fba96f6ee55a83f4557b3ff188892ec95b544406993e9d5ccc73
-  data.tar.gz: 05fa61d8ab158ec6e4f00b7f517dac756a4adba6a7ea1025d5d37f8a032de63613311157209b1888e32cd25c83783c8fbe8a6e8ffee98369826a1f5f58dc2c95
+  metadata.gz: 3dee2d6604b17ac0baf2872ba0b807ebe7acafdbce4c3fdbc1453f737161e1916b30fe80e7a09daf34d0ced994a918d604e74b4aac355381fff1f89b635fc2ce
+  data.tar.gz: bb8a63c2937041c4123d08f89704fa755a2096724e57176e37c8fed2d3902d7c6df2889c621cb7ced4372938a70870f47525560c09615c7d8d48520192d3ae4f

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.5.0] 2023-05-26
+
+- Adds method `get_or_create` to Collection class.
+
+## [0.4.0] 2023-05-23
+
+- This version implements Chroma's API change where Collection uses its collection id for many operations. Changes in the
+  gem are internals, public API remains the same. Just be aware you need Chroma 0.3.25 or better with this gem version.
+
 ## [0.3.0] 2023-05-19
 
 - Uses Ruby Next to transpile newer Ruby to older Ruby versions in order to support Ruby 2.7, 3.0, and 3.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    chroma-db (0.2.0)
+    chroma-db (0.5.0)
       dry-monads (~> 1.6)
       ruby-next (>= 0.15.0)
 

data/README.md

@@ -7,8 +7,7 @@ This Ruby gem is a client to connect to Chroma's database via its API.
 Find more information about Chroma on how to install at their website. [https://www.trychroma.com/](https://www.trychroma.com/)
 
 ## Description
-Chroma-rb is a Ruby client for Chroma Database. It works with version
-0.3.22 or better.
+Chroma-rb is a Ruby client for Chroma Database. It works with version 0.3.22 or better **(Please see requirements below)**.
 
 A small example usage
 
@@ -42,7 +41,9 @@ For a complete example, please refer to the Jupyter Noterbook [Chroma gem](https
 
 ## Requirements
 - Ruby 2.7.8 or newer
-- Chroma Database 0.3.22 or later running as a client/server model.
+- Chroma Database 0.3.25 or later running as a client/server model.
+
+For Chroma database 0.3.22 or older, please use version 0.3.0 of this gem.
 
 ## Installation
 To install the gem and add to the application's Gemfile, execute:

data/lib/.rbnext/2.7/chroma/api_operations/request.rb

@@ -2,7 +2,7 @@
 
 module Chroma
   module APIOperations
-    # using RubyNext
+    using RubyNext
 
     # Request's response Data object.
     #
@@ -56,8 +56,7 @@ module Chroma
         end
 
         private def build_response(response)
-          puts "BUILDING RESPONSE OLD RUBY"
-          case; when ((__m__ = response)) && false
+          case; when ((__m__ = response)) && false 
           when (((success_response,) = nil) || ((Net::HTTPSuccess === __m__) && ((success_response = __m__) || true)))
 
 
@@ -101,7 +100,7 @@ module Chroma
             response.is_a?(Net::HTTPSuccess) ? nil : response
           )
 
-          case; when ((__m__ = response)) && false
+          case; when ((__m__ = response)) && false 
           when (Net::HTTPSuccess === __m__)
             return Success(response_data)
           else

data/lib/.rbnext/2.7/chroma/resources/collection.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: true
 
 module Chroma
-    using RubyNext
+  using RubyNext
+
   module Resources
     # A Collection class represents a store for your embeddings, documents, and any additional metadata.
     # This class can be instantiated by receiving the collection's name and metadata hash.
     class Collection
       include Chroma::APIOperations::Request
 
+      attr_reader :id
       attr_reader :name
       attr_reader :metadata
 
-      def initialize(name:, metadata: nil)
+      def initialize(id:, name:, metadata: nil)
+        @id = id
         @name = name
         @metadata = metadata
       end
@@ -40,7 +43,7 @@ module Chroma
           include: include
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/query", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/query", payload)
 
         if result.success?
           build_embeddings_response(result.success.body)
@@ -84,7 +87,7 @@ module Chroma
           include: include
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/get", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/get", payload)
 
         if result.success?
           build_embeddings_response(result.success.body)
@@ -109,7 +112,7 @@ module Chroma
 
         payload = build_embeddings_payload(embeddings_array)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/add", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/add", payload)
 
         return true if result.success?
 
@@ -135,7 +138,7 @@ module Chroma
           where_document: where_document
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/delete", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/delete", payload)
 
         return result.success.body if result.success?
 
@@ -159,7 +162,7 @@ module Chroma
         payload = build_embeddings_payload(embeddings_array)
         payload.delete(:increment_index)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/update", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/update", payload)
 
         return true if result.success?
 
@@ -186,7 +189,7 @@ module Chroma
 
         payload = build_embeddings_payload(embeddings_array)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/upsert", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/upsert", payload)
 
         return true if result.success?
 
@@ -202,7 +205,7 @@ module Chroma
       #
       # Returns the count of embeddings in the collection.
       def count
-        result = self.class.execute_request(:get, "#{Chroma.api_url}/collections/#{name}/count")
+        result = self.class.execute_request(:get, "#{Chroma.api_url}/collections/#{id}/count")
 
         return result.success.body if result.success?
 
@@ -224,7 +227,7 @@ module Chroma
         payload = {new_name: new_name}
         payload[:new_metadata] = new_metadata if new_metadata.any?
 
-        result = self.class.execute_request(:put, "#{Chroma.api_url}/collections/#{name}", payload)
+        result = self.class.execute_request(:put, "#{Chroma.api_url}/collections/#{id}", payload)
 
         if result.success?
           @name = new_name
@@ -243,7 +246,7 @@ module Chroma
       #
       # Returns true on success or raise a Chroma::Error on failure.
       def create_index
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/create_index")
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/create_index")
 
         return true if result.success?
 
@@ -269,7 +272,7 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          new(name: data["name"], metadata: data["metadata"])
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
         else
           raise_failure_error(result)
         end
@@ -289,7 +292,32 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          new(name: data["name"], metadata: data["metadata"])
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
+        else
+          raise_failure_error(result)
+        end
+      end
+
+      # Get or create a collection on the database.
+      #
+      # name - The name of the collection. Name needs to be between 3-63 characters, starts and ends
+      #   with an alphanumeric character, contains only alphanumeric characters, underscores or hyphens (-), and
+      #   contains no two consecutive periods
+      # metadata - A hash of additional metadata associated with the collection, this is used if collection is created.
+      #
+      # Examples
+      #
+      #   collection = Chorma::Resources::Collection.get_or_create("ruby-documentation", {source: "Ruby lang website"})
+      #
+      # Returns the created collection object.
+      def self.get_or_create(name, metadata = nil)
+        payload = {name: name, metadata: metadata, get_or_create: true}
+
+        result = execute_request(:post, "#{Chroma.api_url}/collections", payload)
+
+        if result.success?
+          data = result.success.body
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
         else
           raise_failure_error(result)
         end
@@ -307,7 +335,7 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          data.map { |item| new(name: item["name"], metadata: item["metadata"]) }
+          data.map { |item| new(id: item["id"], name: item["name"], metadata: item["metadata"]) }
         else
           raise_failure_error(result)
         end

data/lib/.rbnext/3.1/chroma/api_operations/request.rb

@@ -2,7 +2,7 @@
 
 module Chroma
   module APIOperations
-    # using RubyNext
+    using RubyNext
 
     # Request's response Data object.
     #

data/lib/.rbnext/3.1/chroma/resources/collection.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: true
 
 module Chroma
-    using RubyNext
+  using RubyNext
+
   module Resources
     # A Collection class represents a store for your embeddings, documents, and any additional metadata.
     # This class can be instantiated by receiving the collection's name and metadata hash.
     class Collection
       include Chroma::APIOperations::Request
 
+      attr_reader :id
       attr_reader :name
       attr_reader :metadata
 
-      def initialize(name:, metadata: nil)
+      def initialize(id:, name:, metadata: nil)
+        @id = id
         @name = name
         @metadata = metadata
       end
@@ -40,7 +43,7 @@ module Chroma
           include: include
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/query", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/query", payload)
 
         if result.success?
           build_embeddings_response(result.success.body)
@@ -84,7 +87,7 @@ module Chroma
           include: include
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/get", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/get", payload)
 
         if result.success?
           build_embeddings_response(result.success.body)
@@ -109,7 +112,7 @@ module Chroma
 
         payload = build_embeddings_payload(embeddings_array)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/add", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/add", payload)
 
         return true if result.success?
 
@@ -135,7 +138,7 @@ module Chroma
           where_document: where_document
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/delete", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/delete", payload)
 
         return result.success.body if result.success?
 
@@ -159,7 +162,7 @@ module Chroma
         payload = build_embeddings_payload(embeddings_array)
         payload.delete(:increment_index)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/update", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/update", payload)
 
         return true if result.success?
 
@@ -186,7 +189,7 @@ module Chroma
 
         payload = build_embeddings_payload(embeddings_array)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/upsert", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/upsert", payload)
 
         return true if result.success?
 
@@ -202,7 +205,7 @@ module Chroma
       #
       # Returns the count of embeddings in the collection.
       def count
-        result = self.class.execute_request(:get, "#{Chroma.api_url}/collections/#{name}/count")
+        result = self.class.execute_request(:get, "#{Chroma.api_url}/collections/#{id}/count")
 
         return result.success.body if result.success?
 
@@ -224,7 +227,7 @@ module Chroma
         payload = {new_name: new_name}
         payload[:new_metadata] = new_metadata if new_metadata.any?
 
-        result = self.class.execute_request(:put, "#{Chroma.api_url}/collections/#{name}", payload)
+        result = self.class.execute_request(:put, "#{Chroma.api_url}/collections/#{id}", payload)
 
         if result.success?
           @name = new_name
@@ -243,7 +246,7 @@ module Chroma
       #
       # Returns true on success or raise a Chroma::Error on failure.
       def create_index
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/create_index")
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/create_index")
 
         return true if result.success?
 
@@ -269,7 +272,7 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          new(name: data["name"], metadata: data["metadata"])
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
         else
           raise_failure_error(result)
         end
@@ -289,7 +292,32 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          new(name: data["name"], metadata: data["metadata"])
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
+        else
+          raise_failure_error(result)
+        end
+      end
+
+      # Get or create a collection on the database.
+      #
+      # name - The name of the collection. Name needs to be between 3-63 characters, starts and ends
+      #   with an alphanumeric character, contains only alphanumeric characters, underscores or hyphens (-), and
+      #   contains no two consecutive periods
+      # metadata - A hash of additional metadata associated with the collection, this is used if collection is created.
+      #
+      # Examples
+      #
+      #   collection = Chorma::Resources::Collection.get_or_create("ruby-documentation", {source: "Ruby lang website"})
+      #
+      # Returns the created collection object.
+      def self.get_or_create(name, metadata = nil)
+        payload = {name: name, metadata: metadata, get_or_create: true}
+
+        result = execute_request(:post, "#{Chroma.api_url}/collections", payload)
+
+        if result.success?
+          data = result.success.body
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
         else
           raise_failure_error(result)
         end
@@ -307,7 +335,7 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          data.map { |item| new(name: item["name"], metadata: item["metadata"]) }
+          data.map { |item| new(id: item["id"], name: item["name"], metadata: item["metadata"]) }
         else
           raise_failure_error(result)
         end

data/lib/chroma/resources/collection.rb

@@ -1,17 +1,20 @@
 # frozen_string_literal: true
 
 module Chroma
-    using RubyNext
+  using RubyNext
+
   module Resources
     # A Collection class represents a store for your embeddings, documents, and any additional metadata.
     # This class can be instantiated by receiving the collection's name and metadata hash.
     class Collection
       include Chroma::APIOperations::Request
 
+      attr_reader :id
       attr_reader :name
       attr_reader :metadata
 
-      def initialize(name:, metadata: nil)
+      def initialize(id:, name:, metadata: nil)
+        @id = id
         @name = name
         @metadata = metadata
       end
@@ -40,7 +43,7 @@ module Chroma
           include:
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/query", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/query", payload)
 
         if result.success?
           build_embeddings_response(result.success.body)
@@ -84,7 +87,7 @@ module Chroma
           include:
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/get", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/get", payload)
 
         if result.success?
           build_embeddings_response(result.success.body)
@@ -109,7 +112,7 @@ module Chroma
 
         payload = build_embeddings_payload(embeddings_array)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/add", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/add", payload)
 
         return true if result.success?
 
@@ -135,7 +138,7 @@ module Chroma
           where_document:
         }
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/delete", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/delete", payload)
 
         return result.success.body if result.success?
 
@@ -159,7 +162,7 @@ module Chroma
         payload = build_embeddings_payload(embeddings_array)
         payload.delete(:increment_index)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/update", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/update", payload)
 
         return true if result.success?
 
@@ -186,7 +189,7 @@ module Chroma
 
         payload = build_embeddings_payload(embeddings_array)
 
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/upsert", payload)
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/upsert", payload)
 
         return true if result.success?
 
@@ -202,7 +205,7 @@ module Chroma
       #
       # Returns the count of embeddings in the collection.
       def count
-        result = self.class.execute_request(:get, "#{Chroma.api_url}/collections/#{name}/count")
+        result = self.class.execute_request(:get, "#{Chroma.api_url}/collections/#{id}/count")
 
         return result.success.body if result.success?
 
@@ -224,7 +227,7 @@ module Chroma
         payload = {new_name:}
         payload[:new_metadata] = new_metadata if new_metadata.any?
 
-        result = self.class.execute_request(:put, "#{Chroma.api_url}/collections/#{name}", payload)
+        result = self.class.execute_request(:put, "#{Chroma.api_url}/collections/#{id}", payload)
 
         if result.success?
           @name = new_name
@@ -243,7 +246,7 @@ module Chroma
       #
       # Returns true on success or raise a Chroma::Error on failure.
       def create_index
-        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{name}/create_index")
+        result = self.class.execute_request(:post, "#{Chroma.api_url}/collections/#{id}/create_index")
 
         return true if result.success?
 
@@ -269,7 +272,7 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          new(name: data["name"], metadata: data["metadata"])
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
         else
           raise_failure_error(result)
         end
@@ -289,7 +292,32 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          new(name: data["name"], metadata: data["metadata"])
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
+        else
+          raise_failure_error(result)
+        end
+      end
+
+      # Get or create a collection on the database.
+      #
+      # name - The name of the collection. Name needs to be between 3-63 characters, starts and ends
+      #   with an alphanumeric character, contains only alphanumeric characters, underscores or hyphens (-), and
+      #   contains no two consecutive periods
+      # metadata - A hash of additional metadata associated with the collection, this is used if collection is created.
+      #
+      # Examples
+      #
+      #   collection = Chorma::Resources::Collection.get_or_create("ruby-documentation", {source: "Ruby lang website"})
+      #
+      # Returns the created collection object.
+      def self.get_or_create(name, metadata = nil)
+        payload = {name:, metadata:, get_or_create: true}
+
+        result = execute_request(:post, "#{Chroma.api_url}/collections", payload)
+
+        if result.success?
+          data = result.success.body
+          new(id: data["id"], name: data["name"], metadata: data["metadata"])
         else
           raise_failure_error(result)
         end
@@ -307,7 +335,7 @@ module Chroma
 
         if result.success?
           data = result.success.body
-          data.map { |item| new(name: item["name"], metadata: item["metadata"]) }
+          data.map { |item| new(id: item["id"], name: item["name"], metadata: item["metadata"]) }
         else
           raise_failure_error(result)
         end

data/lib/chroma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Chroma
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chroma-db
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Mario Alberto Chávez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-19 00:00:00.000000000 Z
+date: 2023-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-monads