Docs: Add more methods on the package usage

Author: CodeWithKyrian

README.md

@@ -169,13 +169,16 @@ If the tenant or database doesn't exist, the package will automatically create t
 
 ### Creating a Collection
 
+Creating a collection is as simple as calling the `createCollection` method on the client and passing in the name of
+the collection.
+
 ```php
 
 $collection = $chroma->createCollection('test-collection');
 
 ```
 
-If the collection already exists in the database, the package will automatically fetch it for you.
+If the collection already exists in the database, the package will throw an exception.
 
 ### Inserting Documents
 
@@ -231,10 +234,23 @@ that you can use:
 
     $collection = $chromaDB->createCollection('test-collection', embeddingFunction: $embeddingFunction);
     ```
+  You can get your OpenAI API key and organization id from your [OpenAI dashboard](https://beta.openai.com/), and you
+  can omit the organization id if your API key doesn't belong to an organization. The model name is optional as well and
+  defaults to `text-embedding-ada-002`
 
-- `HuggingFaceEmbeddingFunction`: This embedding function uses the HuggingFace API to compute the embeddings. You can
-  use it like this:
+- `JinaEmbeddingFunction`: This is a wrapper for the Jina Embedding models. You can use by passing your Jina API key and
+  the desired model. THis defaults to `jina-embeddings-v2-base-en`
+    ```php
+  use Codewithkyrian\ChromaDB\Embeddings\JinaEmbeddingFunction;
+  
+  $embeddingFunction = new JinaEmbeddingFunction('api-key');
+  
+  $collection = $chromaDB->createCollection('test-collection', embeddingFunction: $embeddingFunction);
+    ```
 
+- `HuggingFaceEmbeddingServerFunction`: This embedding function is a wrapper around the HuggingFace Text Embedding
+  Server. Before using it, you need to have
+  the [HuggingFace Embedding Server](https://github.com/huggingface/text-embeddings-inference) running somewhere locally.  Here's how you can use it:
     ```php
     use CodeWithKyrian\Chroma\EmbeddingFunction\HuggingFaceEmbeddingFunction;
 
@@ -243,7 +259,8 @@ that you can use:
     $collection = $chromaDB->createCollection('test-collection', embeddingFunction: $embeddingFunction);
     ```
 
-You can also create your own embedding function by implementing the `EmbeddingFunctionInterface` interface.
+Besides the built-in embedding functions, you can also create your own embedding function by implementing
+the `EmbeddingFunction` interface (including Anonymous Classes):
 
 ```php
 use CodeWithKyrian\ChromaDB\EmbeddingFunction\EmbeddingFunctionInterface;
@@ -258,6 +275,269 @@ $embeddingFunction = new class implements EmbeddingFunctionInterface {
 $collection = $chroma->createCollection('test-collection', embeddingFunction: $embeddingFunction);
 ```
 
+> The embedding function will be called for each batch of documents that are inserted into the collection, and must be
+> provided either when creating the collection or when querying the collection. If you don't provide an embedding
+> function, and you don't provide the embeddings, the package will throw an exception.
+
+### Inserting Documents into a Collection with an Embedding Function
+
+```php
+$ids = ['test1', 'test2', 'test3'];
+$documents = [
+    'This is a test document',
+    'This is another test document',
+    'This is yet another test document',
+];
+$metadatas = [
+    ['url' => 'https://example.com/test1'],
+    ['url' => 'https://example.com/test2'],
+    ['url' => 'https://example.com/test3'],
+];
+
+$collection->add(
+    ids: $ids, 
+    documents: $documents, 
+    metadatas: $metadatas
+);
+```
+
+### Getting a Collection
+
+```php
+$collection = $chromaDB->getCollection('test-collection');
+```
+
+Or with an embedding function:
+
+```php
+$collection = $chromaDB->getCollection('test-collection', embeddingFunction: $embeddingFunction);
+```
+
+> Make sure that the embedding function you provide is the same one that was used when creating the collection.
+
+### Counting the items in a collection
+
+```php
+$collection->count() // 2
+```
+
+### Updating a collection
+
+```php
+$collection->update(
+    ids: ['test1', 'test2', 'test3'],
+    embeddings: [
+        [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0],
+        [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0],
+        [10.0, 9.0, 8.0, 7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0],
+    ],
+    metadatas: [
+        ['url' => 'https://example.com/test1'],
+        ['url' => 'https://example.com/test2'],
+        ['url' => 'https://example.com/test3'],
+    ]
+);
+```
+
+### Deleting Documents
+
+```php
+$collection->delete(['test1', 'test2', 'test3']);
+```
+
+### Querying a Collection
+
+```php
+$queryResponse = $collection->query(
+    queryEmbeddings: [
+        [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+    ],
+    nResults: 2
+);
+
+echo $queryResponse->ids[0][0]; // test1
+echo $queryResponse->ids[0][1]; // test2
+```
+
+To query a collection, you need to provide the following:
+
+- `queryEmbeddings` (optional): An array of query embeddings. The embeddings must be a 1D array of floats. You
+  can compute the embeddings using any embedding model of your choice (just make sure that's what you use when inserting
+  as
+  well).
+- `nResults`: The number of results to return. Defaults to 10.
+- `queryTexts` (optional): An array of query texts. The texts must be strings. You can omit this if you provide the
+  embeddings. Here's
+  an example:
+    ```php
+    $queryResponse = $collection->query(
+        queryTexts: [
+            'This is a test document'
+        ],
+        nResults: 2
+    );
+    
+    echo $queryResponse->ids[0][0]; // test1
+    echo $queryResponse->ids[0][1]; // test2
+    ```
+- `where` (optional): The where clause to use to filter items based on their metadata. Here's an example:
+  ```php
+  $queryResponse = $collection->query(
+      queryEmbeddings: [
+          [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+      ],
+      nResults: 2,
+      where: [
+          'url' => 'https://example.com/test1'
+      ]
+  );
+      
+  echo $queryResponse->ids[0][0]; // test1
+  ```
+  The where clause must be an array of key-value pairs. The key must be a string, and the value can be a string or
+  an array of valid filter values. Here are the valid filters (`$eq`, `$ne`, `$in`, `$nin`, `$gt`, `$gte`, `$lt`,
+  `$lte`):
+    - `$eq`: Equals
+    - `$ne`: Not equals
+    - `$gt`: Greater than
+    - `$gte`: Greater than or equal to
+    - `$lt`: Less than
+    - `$lte`: Less than or equal to
+
+  Here's an example:
+  ```php
+    $queryResponse = $collection->query(
+        queryEmbeddings: [
+            [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+        ],
+        nResults: 2,
+        where: [
+            'url' => [
+                '$eq' => 'https://example.com/test1'
+            ]
+        ]
+    );
+  ```
+  You can also use multiple filters:
+    ```php
+        $queryResponse = $collection->query(
+            queryEmbeddings: [
+                [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+            ],
+            nResults: 2,
+            where: [
+                'url' => [
+                    '$eq' => 'https://example.com/test1'
+                ],
+                'title' => [
+                    '$ne' => 'Test 1'
+                ]
+            ]
+        );
+    ```
+    - `whereDocument` (optional): The where clause to use to filter items based on their document. Here's an example:
+      ```php
+      $queryResponse = $collection->query(
+          queryEmbeddings: [
+              [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+          ],
+          nResults: 2,
+          whereDocument: [
+              'text' => 'This is a test document'
+          ]
+      );
+          
+      echo $queryResponse->ids[0][0]; // test1
+      ```
+      The where clause must be an array of key-value pairs. The key must be a string, and the value can be a string or
+      an array of valid filter values. In this case, only two filtering keys are supported - `$contains`
+      and `$not_contains`.
+
+      Here's an example:
+      ```php
+        $queryResponse = $collection->query(
+            queryEmbeddings: [
+                [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+            ],
+            nResults: 2,
+            whereDocument: [
+                'text' => [
+                    '$contains' => 'test document'
+                ]
+            ]
+        );
+      ```
+    - `include` (optional): An array of fields to include in the response. Possible values
+      are `embeddings`, `documents`, `metadatas` and `distances`. It defaults to `embeddings`
+      and `metadatas` (`documents` are not included by default because they can be large).
+      ```php
+      $queryResponse = $collection->query(
+          queryEmbeddings: [
+              [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
+          ],
+          nResults: 2,
+          include: ['embeddings']
+      );
+      ```
+      `distances` is only valid for querying and not for getting. It returns the distances between the query embeddings
+      and the embeddings of the results.
+
+  Other relevant information about querying and retrieving a collection can be found in
+  the [ChromaDB Documentation](https://docs.trychroma.com/usage-guide).
+
+### Deleting items in a collection
+
+To delete the documents in a collection, pass in an array of the ids of the items:
+
+```php
+$collection->delete(['test1', 'test2']);
+
+$collection->count() // 1
+```
+
+Passing the ids is optional. You can delete items from a collection using a where filter:
+
+```php
+$collection->add(
+    ['test1', 'test2', 'test3'],
+    [
+        [1.0, 2.0, 3.0, 4.0, 5.0],
+        [6.0, 7.0, 8.0, 9.0, 10.0],
+        [11.0, 12.0, 13.0, 14.0, 15.0],
+    ], 
+     [
+        ['some' => 'metadata1'],
+        ['some' => 'metadata2'],
+        ['some' => 'metadata3'],
+    ]
+);
+
+$collection->delete(
+    where: [
+        'some' => 'metadata1'
+    ]
+);
+
+$collection->count() // 2
+```
+
+### Deleting a collection
+
+Deleting a collection is as simple as passing in the name of the collection to be deleted.
+
+```php
+$chroma->deleteCollection('test_collection');
+```
+
+## Testing
+
+```
+// Run chroma by running the docker compose file in the repo
+docker compose up -d
+
+composer test
+```
+
 ## Contributors
 
 - [Kyrian Obikwelu](https://github.com/CodeWithKyrian)

src/Generated/ChromaApiClient.php

@@ -353,6 +353,7 @@ private function handleChromaApiException(\Exception|ClientExceptionInterface $e
                     $message = $error['detail'];
                     $error_type = ChromaException::inferTypeFromMessage($message);
 
+
                     ChromaException::throwSpecific($message, $error_type, $e->getCode());
                 }
 

src/Generated/Exceptions/ChromaException.php

@@ -19,6 +19,8 @@ public static function throwSpecific(string $message, string $type, int $code)
                 throw new ChromaUniqueConstraintException($message, $code);
             case 'DimensionalityError':
                 throw new ChromaDimensionalityException($message, $code);
+            case 'TypeError':
+                throw new ChromaTypeException($message, $code);
             default:
                 throw new self($message, $code);
         }

src/Generated/Exceptions/ChromaTypeException.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+
+namespace Codewithkyrian\ChromaDB\Generated\Exceptions;
+
+class ChromaTypeException extends ChromaException
+{
+
+}