chromadb-experimental 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fae99389435684425baadb4d7c94dcd59b4ff2b1b304b157ce63c1a35b541fd8
-  data.tar.gz: d231d2cdc468b5eb1301470e6025d032fde0743f7127a1b21cb679f7f717b2e1
+  metadata.gz: 2638e8c25b5a39193b9d3ec22a8196b9f093dd09a0bd39df754fd69d26969fa5
+  data.tar.gz: 14147058836b4dc4f1e5bf0fc1d763c756686bfe2fe604ce4341966ac78658fc
 SHA512:
-  metadata.gz: 752dfdd6d4ef1b99bc8412910d6c8cf1add8f6fe346d91ffbfc53086b69186aa6d91caed18281b9e6b0f1662a6e308eb69fc53fc7bc05e6e8d4446561f8c0597
-  data.tar.gz: 740a7ff83040ce0c8c8c7db33d4d568858d83a3c21113ec79b008cba7a8b7eb5c63ca1d1b3c12c1b4818395c3632b7685da9bc8ccc30fca973984813558bd086
+  metadata.gz: bddbe461695418288ae99b9f11d2d2d8fd64e054f8c897b28b89c1bdbfea3a4a121a62dff7412378e51e1cd4995d0a3680daa3a010eefaedb47caf8205845feb
+  data.tar.gz: 825d6d1999f39010968528ede4fa5144c32be4d7fb646a30b0b98c28ba7b2a0dee54d05c8cfd18dc797bf1465be5357ecee22b961cf1a594e03c6e65e98e06eb

data/lib/chromadb/client.rb

@@ -293,18 +293,21 @@ module Chroma
   end
 
   class CloudClient < Client
-    def initialize(cloud_host: "api.trychroma.com", cloud_port: 443, enable_ssl: true, headers: nil,
-                   tenant: nil, database: nil, api_key: nil, ssl_verify: true, timeout: nil)
-      api_key ||= ENV["CHROMA_API_KEY"]
+    def initialize(api_key: nil, headers: nil, tenant: nil, database: nil, ssl_verify: true, timeout: nil)
+      config = Chroma.configuration
+      api_key ||= config.cloud_api_key
       raise ArgumentError, "CHROMA_API_KEY is required for CloudClient" if api_key.nil? || api_key.empty?
 
+      tenant ||= config.cloud_tenant
+      database ||= config.cloud_database
+
       merged_headers = (headers || {}).dup
       merged_headers["x-chroma-token"] ||= api_key
 
       super(
-        host: cloud_host,
-        port: cloud_port,
-        ssl: enable_ssl,
+        host: config.cloud_host,
+        port: config.cloud_port,
+        ssl: config.cloud_ssl,
         headers: merged_headers,
         tenant: tenant,
         database: database,

data/lib/chromadb/client_configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Chroma
+  class ClientConfiguration
+    attr_accessor :cloud_api_key, :cloud_host, :cloud_port, :cloud_ssl, :cloud_tenant, :cloud_database
+
+    def initialize
+      @cloud_api_key = ENV["CHROMA_API_KEY"]
+      @cloud_host = ENV.fetch("CHROMA_CLOUD_HOST", "api.trychroma.com")
+      @cloud_port = normalize_port(ENV.fetch("CHROMA_CLOUD_PORT", "443"))
+      @cloud_ssl = ENV.fetch("CHROMA_CLOUD_SSL", "true").downcase != "false"
+      @cloud_tenant = ENV["CHROMA_TENANT"]
+      @cloud_database = ENV["CHROMA_DATABASE"]
+    end
+
+    private
+
+    def normalize_port(value)
+      Integer(value)
+    rescue ArgumentError, TypeError
+      443
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= ClientConfiguration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      if defined?(Chroma::SharedState)
+        SharedState.register_cloud_api_key(configuration.cloud_api_key)
+      end
+      configuration
+    end
+
+    def reset_configuration!
+      @configuration = ClientConfiguration.new
+      if defined?(Chroma::SharedState)
+        SharedState.register_cloud_api_key(@configuration.cloud_api_key)
+      end
+      @configuration
+    end
+  end
+end

data/lib/chromadb/collection.rb

@@ -176,7 +176,7 @@ module Chroma
       response = @client.transport.request(
         :post,
         "/tenants/#{path[:tenant]}/databases/#{path[:database]}/collections/#{path[:collection_id]}/fork",
-        json: { "name" => name },
+        json: { "new_name" => name },
       )
       @client.send(:build_collection, response)
     end
@@ -489,6 +489,7 @@ module Chroma
         return Chroma::Search::Search.new(
           where: item[:where] || item["where"],
           rank: item[:rank] || item["rank"],
+          group_by: item[:group_by] || item["group_by"],
           limit: item[:limit] || item["limit"],
           select: item[:select] || item["select"],
         ).to_h

data/lib/chromadb/openapi/lib/chromadb/version.rb

@@ -11,5 +11,5 @@ OpenAPI Generator version: 6.6.0
 =end
 
 module Chromadb
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/chromadb/search/group_by.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Chroma
+  module Search
+    module GroupByHelpers
+      module_function
+
+      def normalize_keys(keys, label)
+        raise ArgumentError, "#{label} cannot be empty" if keys.nil?
+
+        values = if keys.is_a?(Array) || keys.is_a?(Set)
+          keys.to_a
+        else
+          [ keys ]
+        end
+
+        raise ArgumentError, "#{label} cannot be empty" if values.empty?
+
+        values.map do |value|
+          normalized = value.respond_to?(:name) ? value.name : value
+          unless normalized.is_a?(String)
+            raise TypeError, "#{label} must be strings or Key instances"
+          end
+          normalized
+        end
+      end
+
+      def normalize_k(value, label)
+        unless value.is_a?(Integer) && value.positive?
+          raise TypeError, "#{label} must be a positive integer"
+        end
+        value
+      end
+
+      def fetch_value(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+    end
+    private_constant :GroupByHelpers
+
+    class Aggregate
+      def to_h
+        raise NotImplementedError
+      end
+
+      def self.from(input)
+        return input if input.is_a?(Aggregate)
+        unless input.is_a?(Hash)
+          raise TypeError, "Aggregate input must be an Aggregate or Hash"
+        end
+        raise ArgumentError, "Aggregate hash must contain exactly one operator" unless input.length == 1
+
+        operator, config = input.first
+        operator = operator.to_s
+
+        case operator
+        when "$min_k"
+          MinK.from_config(config)
+        when "$max_k"
+          MaxK.from_config(config)
+        else
+          raise ArgumentError, "Unknown aggregate operator: #{operator}"
+        end
+      end
+    end
+
+    class MinK < Aggregate
+      attr_reader :keys, :k
+
+      def initialize(keys:, k:)
+        @keys = GroupByHelpers.normalize_keys(keys, "MinK keys")
+        @k = GroupByHelpers.normalize_k(k, "MinK k")
+      end
+
+      def to_h
+        { "$min_k" => { "keys" => @keys.dup, "k" => @k } }
+      end
+
+      def self.from_config(config)
+        unless config.is_a?(Hash)
+          raise TypeError, "$min_k requires a Hash"
+        end
+
+        keys = GroupByHelpers.fetch_value(config, :keys)
+        k = GroupByHelpers.fetch_value(config, :k)
+        raise ArgumentError, "$min_k requires 'keys' field" if keys.nil?
+        raise ArgumentError, "$min_k requires 'k' field" if k.nil?
+
+        new(keys: keys, k: k)
+      end
+    end
+
+    class MaxK < Aggregate
+      attr_reader :keys, :k
+
+      def initialize(keys:, k:)
+        @keys = GroupByHelpers.normalize_keys(keys, "MaxK keys")
+        @k = GroupByHelpers.normalize_k(k, "MaxK k")
+      end
+
+      def to_h
+        { "$max_k" => { "keys" => @keys.dup, "k" => @k } }
+      end
+
+      def self.from_config(config)
+        unless config.is_a?(Hash)
+          raise TypeError, "$max_k requires a Hash"
+        end
+
+        keys = GroupByHelpers.fetch_value(config, :keys)
+        k = GroupByHelpers.fetch_value(config, :k)
+        raise ArgumentError, "$max_k requires 'keys' field" if keys.nil?
+        raise ArgumentError, "$max_k requires 'k' field" if k.nil?
+
+        new(keys: keys, k: k)
+      end
+    end
+
+    class GroupBy
+      attr_reader :keys, :aggregate
+
+      def initialize(keys: nil, aggregate: nil)
+        if keys.nil? && aggregate.nil?
+          @keys = []
+          @aggregate = nil
+          return
+        end
+
+        raise ArgumentError, "GroupBy requires 'keys' field" if keys.nil?
+        raise ArgumentError, "GroupBy requires 'aggregate' field" if aggregate.nil?
+
+        @keys = GroupByHelpers.normalize_keys(keys, "GroupBy keys")
+        @aggregate = Aggregate.from(aggregate)
+      end
+
+      def self.from(input)
+        return input if input.is_a?(GroupBy)
+        return nil if input.nil?
+        unless input.is_a?(Hash)
+          raise TypeError, "GroupBy input must be a GroupBy or Hash"
+        end
+
+        return GroupBy.new if input.empty?
+
+        keys = GroupByHelpers.fetch_value(input, :keys)
+        aggregate = GroupByHelpers.fetch_value(input, :aggregate)
+
+        GroupBy.new(keys: keys, aggregate: aggregate)
+      end
+
+      def empty?
+        @keys.empty? || @aggregate.nil?
+      end
+
+      def to_h
+        return {} if empty?
+
+        {
+          "keys" => @keys.dup,
+          "aggregate" => @aggregate.to_h
+        }
+      end
+    end
+  end
+end

data/lib/chromadb/search/search.rb

@@ -4,11 +4,12 @@ require "set"
 module Chroma
   module Search
     class Search
-      attr_reader :where_clause, :rank_expression, :limit_config, :select_config
+      attr_reader :where_clause, :rank_expression, :group_by_config, :limit_config, :select_config
 
-      def initialize(where: nil, rank: nil, limit: nil, select: nil)
+      def initialize(where: nil, rank: nil, group_by: nil, limit: nil, select: nil)
         @where_clause = WhereExpression.from(where) if where
         @rank_expression = RankExpression.from(rank) if rank
+        @group_by_config = GroupBy.from(group_by) if group_by
         @limit_config = Limit.from(limit)
         @select_config = Select.from(select)
       end
@@ -21,6 +22,10 @@ module Chroma
         clone_with(rank: RankExpression.from(rank))
       end
 
+      def group_by(group_by = nil)
+        clone_with(group_by: GroupBy.from(group_by))
+      end
+
       def limit(limit = nil, offset = nil)
         if limit.is_a?(Numeric)
           clone_with(limit: Limit.from(limit.to_i, offset))
@@ -55,15 +60,20 @@ module Chroma
 
         payload["filter"] = @where_clause.to_h if @where_clause
         payload["rank"] = @rank_expression.to_h if @rank_expression
+        if @group_by_config && !@group_by_config.empty?
+          payload["group_by"] = @group_by_config.to_h
+        end
         payload
       end
 
       private
 
-      def clone_with(where: @where_clause, rank: @rank_expression, limit: @limit_config, select: @select_config)
+      def clone_with(where: @where_clause, rank: @rank_expression, group_by: @group_by_config,
+                     limit: @limit_config, select: @select_config)
         instance = self.class.allocate
         instance.instance_variable_set(:@where_clause, where)
         instance.instance_variable_set(:@rank_expression, rank)
+        instance.instance_variable_set(:@group_by_config, group_by)
         instance.instance_variable_set(:@limit_config, limit)
         instance.instance_variable_set(:@select_config, select)
         instance

data/lib/chromadb/search.rb

@@ -3,6 +3,7 @@
 require_relative "search/key"
 require_relative "search/where"
 require_relative "search/rank"
+require_relative "search/group_by"
 require_relative "search/limit"
 require_relative "search/select"
 require_relative "search/search"

data/lib/chromadb/version.rb

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

data/lib/chromadb.rb

@@ -9,6 +9,7 @@ require_relative "chromadb/types"
 require_relative "chromadb/schema"
 require_relative "chromadb/search"
 require_relative "chromadb/embedding_functions"
+require_relative "chromadb/client_configuration"
 require_relative "chromadb/http_client"
 require_relative "chromadb/client"
 require_relative "chromadb/admin_client"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: chromadb-experimental
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Chroma Core
 bindir: bin
 cert_chain: []
-date: 2025-12-31 00:00:00.000000000 Z
+date: 2026-01-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -107,7 +107,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.23'
-description: Ruby client for Chroma's HTTP API (dense + sparse embeddings).
+description: Experimental Ruby client for Chroma
 email:
 - support@trychroma.com
 executables: []
@@ -117,6 +117,7 @@ files:
 - lib/chromadb.rb
 - lib/chromadb/admin_client.rb
 - lib/chromadb/client.rb
+- lib/chromadb/client_configuration.rb
 - lib/chromadb/collection.rb
 - lib/chromadb/embedding_functions.rb
 - lib/chromadb/embedding_functions/chroma_bm25.rb
@@ -198,6 +199,7 @@ files:
 - lib/chromadb/schemas/chroma-cloud-splade.json
 - lib/chromadb/schemas/chroma_bm25.json
 - lib/chromadb/search.rb
+- lib/chromadb/search/group_by.rb
 - lib/chromadb/search/key.rb
 - lib/chromadb/search/limit.rb
 - lib/chromadb/search/rank.rb
@@ -229,5 +231,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Chroma Ruby client
+summary: Chroma Ruby client (experimental)
 test_files: []