feat: add collection forking support

Note: Collection forking is only supported for Chroma Cloud, not local Chroma instances.

Author: CodeWithKyrian

README.md

@@ -119,6 +119,10 @@ $collection = $client->getCollection('my-collection');
 // Get or Create =
 $collection = $client->getOrCreateCollection('my-collection', $ef);
 
+// Fork (creates a copy of an existing collection)
+// Note: Forking is only supported for Chroma Cloud, not local Chroma instances
+$forkedCollection = $client->forkCollection('my-collection', 'my-collection-fork', $ef);
+
 // Delete
 $client->deleteCollection('my-collection');
 ```

src/Api.php

@@ -14,6 +14,7 @@
 use Codewithkyrian\ChromaDB\Requests\CreateDatabaseRequest;
 use Codewithkyrian\ChromaDB\Requests\CreateTenantRequest;
 use Codewithkyrian\ChromaDB\Requests\DeleteItemsRequest;
+use Codewithkyrian\ChromaDB\Requests\ForkCollectionRequest;
 use Codewithkyrian\ChromaDB\Requests\GetEmbeddingRequest;
 use Codewithkyrian\ChromaDB\Requests\QueryItemsRequest;
 use Codewithkyrian\ChromaDB\Requests\UpdateCollectionRequest;
@@ -38,8 +39,7 @@ public function __construct(
         public readonly StreamFactoryInterface $streamFactory,
         public readonly string $baseUri,
         public readonly array $headers = [],
-    ) {
-    }
+    ) {}
 
     /**
      * Retrieves the current user's identity, tenant, and databases.
@@ -288,6 +288,27 @@ public function updateCollection(string $collectionId, string $database, string
         ]);
     }
 
+    /**
+     * Forks an existing collection.
+     * 
+     * @param string $collectionId The UUID of the collection to fork.
+     * @param string $database The database name to fork the collection from.
+     * @param string $tenant The tenant ID to fork the collection from.
+     * @param ForkCollectionRequest $request The request to fork the collection.
+     * 
+     * @return Collection
+     */
+    public function forkCollection(string $collectionId, string $database, string $tenant, ForkCollectionRequest $request): Collection
+    {
+        $response = $this->sendRequest('POST', "/api/v2/tenants/$tenant/databases/$database/collections/$collectionId/fork", [
+            'json' => $request->toArray()
+        ]);
+
+        $result = json_decode($response->getBody()->getContents(), true);
+
+        return Collection::fromArray($result, $this, $database, $tenant);
+    }
+
     /**
      * Deletes a collection in a given database.
      * 
@@ -313,7 +334,6 @@ public function countCollections(string $database, string $tenant): int
         $response = $this->sendRequest('GET', "/api/v2/tenants/$tenant/databases/$database/collections_count");
 
         return json_decode($response->getBody()->getContents(), true);
-
     }
 
     /**
@@ -392,7 +412,7 @@ public function getCollectionItems(string $collectionId, string $database, strin
         $response = $this->sendRequest('POST', "/api/v2/tenants/$tenant/databases/$database/collections/$collectionId/get", [
             'json' => $request->toArray(),
         ]);
- 
+
         $result = json_decode($response->getBody()->getContents(), true);
 
         return GetItemsResponse::fromArray($result);

src/Client.php

@@ -11,6 +11,7 @@
 use Codewithkyrian\ChromaDB\Requests\CreateDatabaseRequest;
 use Codewithkyrian\ChromaDB\Requests\CreateTenantRequest;
 use Codewithkyrian\ChromaDB\Requests\CreateCollectionRequest;
+use Codewithkyrian\ChromaDB\Requests\ForkCollectionRequest;
 
 class Client
 {
@@ -133,6 +134,29 @@ public function getCollection(string $name, ?EmbeddingFunction $embeddingFunctio
         return $collection;
     }
 
+    /**
+     * Forks an existing collection.
+     *
+     * @param string $name The name of the collection to fork.
+     * @param string $newName The name for the forked collection.
+     * @param ?EmbeddingFunction $embeddingFunction Optional custom embedding function for the forked collection.
+     *
+     * @return Collection
+     */
+    public function forkCollection(string $name, string $newName, ?EmbeddingFunction $embeddingFunction = null): Collection
+    {
+        $collection = $this->api->getCollection($name, $this->database, $this->tenant);
+        $request = new ForkCollectionRequest($newName);
+
+        $forkedCollection = $this->api->forkCollection($collection->id, $this->database, $this->tenant, $request);
+
+        if ($embeddingFunction) {
+            $forkedCollection->setEmbeddingFunction($embeddingFunction);
+        }
+
+        return $forkedCollection;
+    }
+
     /**
      * Deletes a collection with the specified name.
      *

src/Requests/ForkCollectionRequest.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+
+namespace Codewithkyrian\ChromaDB\Requests;
+
+/**
+ * Request model for forking a collection.
+ */
+class ForkCollectionRequest
+{
+    /**
+     * @param string $newName The name for the forked collection
+     */
+    public function __construct(
+        public readonly string $newName,
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            newName: $data['new_name'],
+        );
+    }
+
+    public function toArray(): array
+    {
+        return [
+            'new_name' => $this->newName,
+        ];
+    }
+}

tests/Feature/ApiTest.php

@@ -13,6 +13,7 @@
 use Codewithkyrian\ChromaDB\Requests\CreateDatabaseRequest;
 use Codewithkyrian\ChromaDB\Requests\CreateTenantRequest;
 use Codewithkyrian\ChromaDB\Requests\DeleteItemsRequest;
+use Codewithkyrian\ChromaDB\Requests\ForkCollectionRequest;
 use Codewithkyrian\ChromaDB\Requests\GetEmbeddingRequest;
 use Codewithkyrian\ChromaDB\Requests\QueryItemsRequest;
 use Codewithkyrian\ChromaDB\Requests\UpdateCollectionRequest;
@@ -190,6 +191,26 @@
         ->and($updatedCollection->metadata)->toBe(['new' => 'metadata']);
 });
 
+it('can fork a collection', function () {
+    if (str_contains($this->api->baseUri, 'localhost') || !str_contains($this->api->baseUri, 'api.trychroma.com')) {
+        test()->markTestSkipped('Collection forking is not supported for local Chroma');
+    }
+
+    $collectionName = 'test-collection-' . uniqid();
+    $collection = $this->api->createCollection('default_database', 'default_tenant', new CreateCollectionRequest($collectionName, ['original' => 'metadata']));
+
+    $forkedName = 'forked-' . $collectionName;
+    $forkedCollection = $this->api->forkCollection($collection->id, 'default_database', 'default_tenant', new ForkCollectionRequest($forkedName));
+
+    expect($forkedCollection->name)->toBe($forkedName)
+        ->and($forkedCollection->id)->not->toBe($collection->id);
+
+    $collections = $this->api->listCollections('default_database', 'default_tenant');
+    $names = array_map(fn($c) => $c->name, $collections);
+    expect($names)->toContain($collectionName)
+        ->and($names)->toContain($forkedName);
+});
+
 it('can delete a collection', function () {
     $collectionName = 'test-collection-' . uniqid();
     $collection = $this->api->createCollection('default_database', 'default_tenant', new CreateCollectionRequest($collectionName, null));

tests/Feature/ClientTest.php

@@ -3,6 +3,7 @@
 declare(strict_types=1);
 
 namespace Codewithkyrian\ChromaDB\Tests\Feature;
+
 use Codewithkyrian\ChromaDB\ChromaDB;
 use Codewithkyrian\ChromaDB\Embeddings\EmbeddingFunction;
 use Codewithkyrian\ChromaDB\Exceptions\NotFoundException;
@@ -106,6 +107,24 @@ public function generate(array $texts): array
         ->toMatchArray(['test' => 'test_2']);
 });
 
+it('can fork a collection', function () {
+    if (str_contains($this->client->api->baseUri, 'localhost') || !str_contains($this->client->api->baseUri, 'api.trychroma.com')) {
+        test()->markTestSkipped('Collection forking is not supported for local Chroma');
+    }
+
+    $forkedCollection = $this->client->forkCollection('test_collection', 'test_collection_fork', $this->embeddingFunction);
+
+    expect($forkedCollection)
+        ->toBeInstanceOf(Collection::class)
+        ->toHaveProperty('name', 'test_collection_fork')
+        ->and($forkedCollection->id)->not->toBe($this->collection->id);
+
+    $collections = $this->client->listCollections();
+    $names = array_map(fn($c) => $c->name, $collections);
+    expect($names)->toContain('test_collection')
+        ->and($names)->toContain('test_collection_fork');
+});
+
 it('can delete a collection', function () {
     $this->client->deleteCollection('test_collection');