chromadb 3.3.2 → 3.4.0

package/dist/chromadb.mjs

@@ -508,6 +508,22 @@ var CollectionService = class {
       }
     });
   }
+  /**
+   * Get fork count
+   * Returns the number of forks for a collection.
+   */
+  static forkCount(options) {
+    return (options.client ?? client).get({
+      security: [
+        {
+          name: "x-chroma-token",
+          type: "apiKey"
+        }
+      ],
+      url: "/api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/fork_count",
+      ...options
+    });
+  }
   /**
    * Get number of collections
    * Returns the total number of collections in a database.
@@ -1516,7 +1532,9 @@ var pythonEmbeddingFunctions = {
   default: "default-embed",
   together_ai: "together-ai",
   sentence_transformer: "sentence-transformer",
+  google_gemini: "google-gemini",
   google_genai: "google-gemini"
+  // Backward compatibility alias
 };
 var unsupportedEmbeddingFunctions = /* @__PURE__ */ new Set([
   "amazon_bedrock",
@@ -1555,32 +1573,11 @@ var registerSparseEmbeddingFunction = (name, fn) => {
   knownSparseEmbeddingFunctions.set(name, fn);
 };
 var getEmbeddingFunction = async (args) => {
-  const { collectionName, client: client2, efConfig } = args;
-  if (!efConfig) {
-    console.warn(
-      `No embedding function configuration found for collection ${collectionName}. 'add' and 'query' will fail unless you provide them embeddings directly.`
-    );
-    return void 0;
-  }
-  if (efConfig.type === "legacy") {
-    console.warn(
-      `No embedding function configuration found for collection ${collectionName}. 'add' and 'query' will fail unless you provide them embeddings directly.`
-    );
-    return void 0;
-  }
-  if (efConfig.type === "unknown") {
-    console.warn(
-      `Unknown embedding function configuration for collection ${collectionName}. 'add' and 'query' will fail unless you provide them embeddings directly.`
-    );
-    return void 0;
-  }
-  if (efConfig.type !== "known") {
+  const { client: client2, efConfig } = args;
+  if (efConfig?.type !== "known") {
     return void 0;
   }
   if (unsupportedEmbeddingFunctions.has(efConfig.name)) {
-    console.warn(
-      `Embedding function ${efConfig.name} is not supported in the JS/TS SDK. 'add' and 'query' will fail unless you provide them embeddings directly.`
-    );
     return void 0;
   }
   const packageName = pythonEmbeddingFunctions[efConfig.name] || efConfig.name;
@@ -1596,42 +1593,24 @@ var getEmbeddingFunction = async (args) => {
     } catch (error) {
     }
     if (!embeddingFunction) {
-      console.warn(
-        `Collection ${collectionName} was created with the ${packageName} embedding function. However, the @chroma-core/${packageName} package is not installed. 'add' and 'query' will fail unless you provide them embeddings directly, or install the @chroma-core/${packageName} package.`
-      );
       return void 0;
     }
   }
-  let constructorConfig = efConfig.type === "known" ? efConfig.config : {};
+  const constructorConfig = efConfig.config ?? {};
   try {
     if (embeddingFunction.buildFromConfig) {
       return embeddingFunction.buildFromConfig(constructorConfig, client2);
     }
-    console.warn(
-      `Embedding function ${packageName} does not define a 'buildFromConfig' function. 'add' and 'query' will fail unless you provide them embeddings directly.`
-    );
     return void 0;
   } catch (e) {
-    console.warn(
-      `Embedding function ${packageName} failed to build with config: ${constructorConfig}. 'add' and 'query' will fail unless you provide them embeddings directly. Error: ${e}`
-    );
     return void 0;
   }
 };
-var getSparseEmbeddingFunction = async (collectionName, client2, efConfig) => {
-  if (!efConfig) {
-    return void 0;
-  }
-  if (efConfig.type === "legacy") {
-    return void 0;
-  }
-  if (efConfig.type !== "known") {
+var getSparseEmbeddingFunction = async (client2, efConfig) => {
+  if (efConfig?.type !== "known") {
     return void 0;
   }
   if (unsupportedSparseEmbeddingFunctions.has(efConfig.name)) {
-    console.warn(
-      "Embedding function ${efConfig.name} is not supported in the JS/TS SDK. 'add' and 'query' will fail unless you provide them embeddings directly."
-    );
     return void 0;
   }
   const packageName = pythonSparseEmbeddingFunctions[efConfig.name] || efConfig.name;
@@ -1644,25 +1623,16 @@ var getSparseEmbeddingFunction = async (collectionName, client2, efConfig) => {
     } catch (error) {
     }
     if (!sparseEmbeddingFunction) {
-      console.warn(
-        `Collection ${collectionName} was created with the ${packageName} sparse embedding function. However, the @chroma-core/${packageName} package is not installed.`
-      );
       return void 0;
     }
   }
-  let constructorConfig = efConfig.type === "known" ? efConfig.config : {};
+  const constructorConfig = efConfig.config ?? {};
   try {
     if (sparseEmbeddingFunction.buildFromConfig) {
       return sparseEmbeddingFunction.buildFromConfig(constructorConfig, client2);
     }
-    console.warn(
-      `Sparse embedding function ${packageName} does not define a 'buildFromConfig' function.`
-    );
     return void 0;
   } catch (e) {
-    console.warn(
-      `Sparse embedding function ${packageName} failed to build with config: ${constructorConfig}. Error: ${e}`
-    );
     return void 0;
   }
 };
@@ -1788,7 +1758,6 @@ var processUpdateCollectionConfig = async ({
     );
   }
   const embeddingFunction = currentEmbeddingFunction || await getEmbeddingFunction({
-    collectionName,
     client: client2,
     efConfig: currentConfiguration.embeddingFunction ?? void 0
   });
@@ -3886,7 +3855,6 @@ var Schema = class _Schema {
       spann: json.spann ? cloneObject(json.spann) : null
     });
     config.embeddingFunction = await getEmbeddingFunction({
-      collectionName: "schema deserialization",
       client: client2,
       efConfig: json.embedding_function
     });
@@ -3901,7 +3869,6 @@ var Schema = class _Schema {
       bm25: typeof json.bm25 === "boolean" ? json.bm25 : null
     });
     const embeddingFunction = await getSparseEmbeddingFunction(
-      "schema deserialization",
       client2,
       json.embedding_function
     ) ?? config.embeddingFunction ?? void 0;
@@ -3987,7 +3954,7 @@ var CollectionImpl = class _CollectionImpl {
     const embeddingFunction = this._embeddingFunction ?? this.getSchemaEmbeddingFunction();
     if (!embeddingFunction) {
       throw new ChromaValueError(
-        "Embedding function must be defined for operations requiring embeddings."
+        `No embedding function found for collection '${this._name}'. You can either provide embeddings directly, or ensure the appropriate embedding function package (e.g. @chroma-core/default-embed) is installed.`
       );
     }
     if (isQuery && embeddingFunction.generateForQueries) {
@@ -4048,10 +4015,8 @@ var CollectionImpl = class _CollectionImpl {
           }
           if (index < documentsList.length) {
             const doc = documentsList[index];
-            if (typeof doc === "string") {
-              inputs.push(doc);
-              positions.push(index);
-            }
+            inputs.push(doc);
+            positions.push(index);
           }
         });
         if (inputs.length === 0) {
@@ -4471,6 +4436,13 @@ var CollectionImpl = class _CollectionImpl {
       configuration: data.configuration_json
     });
   }
+  async forkCount() {
+    const { data } = await CollectionService.forkCount({
+      client: this.apiClient,
+      path: await this.path()
+    });
+    return data.count;
+  }
   async update({
     ids,
     embeddings,
@@ -4557,6 +4529,75 @@ var CollectionImpl = class _CollectionImpl {
     return data;
   }
 };
+var HANDLE_EMBEDDING_ERROR = "This operation requires an embedding function, which is not available on a collection obtained via client.collection(id). Provide pre-computed embeddings directly, or use client.getCollection() to get a full collection with embedding support.";
+var HANDLE_NOT_SUPPORTED_ERROR = "is not supported on a collection obtained via client.collection(id). Use client.getCollection() to get a full collection instance.";
+var CollectionHandle = class extends CollectionImpl {
+  constructor({ chromaClient, apiClient, id, tenant, database }) {
+    super({
+      chromaClient,
+      apiClient,
+      id,
+      tenant,
+      database,
+      name: "",
+      configuration: {}
+    });
+  }
+  async add(args) {
+    if (!args.embeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.add(args);
+  }
+  async update(args) {
+    if (!args.embeddings && args.documents) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.update(args);
+  }
+  async upsert(args) {
+    if (!args.embeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.upsert(args);
+  }
+  async query(args) {
+    if (!args.queryEmbeddings) {
+      throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+    }
+    return super.query(args);
+  }
+  async search(searches, options) {
+    const items = Array.isArray(searches) ? searches : [searches];
+    for (const search of items) {
+      const payload = toSearch(search).toPayload();
+      if (this.hasStringKnnQuery(payload.rank)) {
+        throw new ChromaValueError(HANDLE_EMBEDDING_ERROR);
+      }
+    }
+    return super.search(searches, options);
+  }
+  async modify(_args) {
+    throw new ChromaValueError(`modify() ${HANDLE_NOT_SUPPORTED_ERROR}`);
+  }
+  async fork(_args) {
+    throw new ChromaValueError(`fork() ${HANDLE_NOT_SUPPORTED_ERROR}`);
+  }
+  hasStringKnnQuery(obj) {
+    if (!obj || typeof obj !== "object") return false;
+    if (Array.isArray(obj)) {
+      return obj.some((item) => this.hasStringKnnQuery(item));
+    }
+    const record = obj;
+    if ("$knn" in record && isPlainObject(record.$knn)) {
+      const knn = record.$knn;
+      if (typeof knn.query === "string") return true;
+    }
+    return Object.values(record).some(
+      (value) => this.hasStringKnnQuery(value)
+    );
+  }
+};
 
 // src/next.ts
 function withChroma(userNextConfig = {}) {
@@ -4918,7 +4959,6 @@ var ChromaClient = class {
         );
         const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(schema);
         const resolvedEmbeddingFunction = await getEmbeddingFunction({
-          collectionName: collection.name,
           client: this,
           efConfig: collection.configuration_json.embedding_function ?? void 0
         }) ?? schemaEmbeddingFunction;
@@ -4988,7 +5028,6 @@ var ChromaClient = class {
     );
     const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(serverSchema);
     const resolvedEmbeddingFunction = embeddingFunction ?? await getEmbeddingFunction({
-      collectionName: data.name,
       client: this,
       efConfig: data.configuration_json.embedding_function ?? void 0
     }) ?? schemaEmbeddingFunction;
@@ -5024,7 +5063,6 @@ var ChromaClient = class {
     const schema = await Schema.deserializeFromJSON(data.schema ?? null, this);
     const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(schema);
     const resolvedEmbeddingFunction = embeddingFunction ?? await getEmbeddingFunction({
-      collectionName: data.name,
       client: this,
       efConfig: data.configuration_json.embedding_function ?? void 0
     }) ?? schemaEmbeddingFunction;
@@ -5055,7 +5093,6 @@ var ChromaClient = class {
     const schema = await Schema.deserializeFromJSON(data.schema ?? null, this);
     const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(schema);
     const resolvedEmbeddingFunction = await getEmbeddingFunction({
-      collectionName: data.name,
       efConfig: data.configuration_json.embedding_function ?? void 0,
       client: this
     }) ?? schemaEmbeddingFunction;
@@ -5131,7 +5168,6 @@ var ChromaClient = class {
     );
     const schemaEmbeddingFunction = resolveSchemaEmbeddingFunction(serverSchema);
     const resolvedEmbeddingFunction = embeddingFunction ?? await getEmbeddingFunction({
-      collectionName: name,
       efConfig: data.configuration_json.embedding_function ?? void 0,
       client: this
     }) ?? schemaEmbeddingFunction;
@@ -5148,6 +5184,30 @@ var ChromaClient = class {
       schema: serverSchema
     });
   }
+  /**
+   * Returns a lightweight collection handle for the given collection ID.
+   * The handle supports operations that don't require an embedding function
+   * or schema (e.g., add with pre-computed embeddings, get, delete, count, search).
+   * Operations that require an embedding function will throw a clear error
+   * directing you to use {@link getCollection} instead.
+   * @param id - The collection ID
+   * @returns A Collection handle for the given ID
+   * @throws ChromaValueError if tenant or database are not set on the client
+   */
+  collection(id) {
+    if (!this._tenant || !this._database) {
+      throw new ChromaValueError(
+        "tenant and database must be set on the client before calling collection(). Provide them in the ChromaClient constructor or use getCollection() instead."
+      );
+    }
+    return new CollectionHandle({
+      chromaClient: this,
+      apiClient: this.apiClient,
+      id,
+      tenant: this._tenant,
+      database: this._database
+    });
+  }
   /**
    * Deletes a collection and all its data.
    * @param options - Deletion options
@@ -5284,6 +5344,7 @@ export {
   CloudClient,
   Cmek,
   CmekProvider,
+  CollectionHandle,
   DOCUMENT_KEY,
   Div,
   EMBEDDING_KEY,