├── .github └── workflows │ └── tests.yml ├── .gitignore ├── LICENSE ├── README.md ├── composer.json ├── config └── chromadb.php ├── phpunit.xml ├── src ├── ChromaServiceProvider.php ├── Concerns │ └── HasChromaCollection.php ├── Contracts │ └── ChromaModel.php ├── Facades │ └── ChromaDB.php └── Jobs │ ├── DeleteChromaCollectionItemJob.php │ └── UpdateChromaCollectionJob.php ├── tests ├── ChromaServiceProviderTest.php ├── Concerns │ └── HasChromaCollectionTest.php ├── Facades │ └── ChromaDBTest.php ├── Pest.php └── TestCase.php └── workbench ├── app ├── Models │ ├── .gitkeep │ └── TestModel.php └── Providers │ └── WorkbenchServiceProvider.php ├── database ├── factories │ └── .gitkeep ├── migrations │ ├── .gitkeep │ └── 2024_01_16_120226_create_test_models_table.php └── seeders │ ├── .gitkeep │ └── DatabaseSeeder.php ├── resources └── views │ └── .gitkeep └── routes ├── .gitkeep ├── api.php ├── console.php └── web.php /.github/workflows/tests.yml: -------------------------------------------------------------------------------- 1 | name: tests 2 | 3 | on: ['push', 'pull_request'] 4 | 5 | jobs: 6 | ci: 7 | runs-on: ubuntu-latest 8 | strategy: 9 | fail-fast: true 10 | matrix: 11 | php: [8.1, 8.2, 8.3] 12 | laravel: [10.*, 9.*] 13 | dependency-version: [prefer-stable] 14 | 15 | name: Tests on PHP${{ matrix.php }} - Laravel${{ matrix.laravel }} - ${{ matrix.dependency-version }} 16 | 17 | services: 18 | chroma: 19 | image: chromadb/chroma 20 | ports: 21 | - 8000:8000 22 | 23 | steps: 24 | 25 | - name: Checkout 26 | uses: actions/checkout@v3 27 | 28 | - name: Cache dependencies 29 | uses: actions/cache@v3 30 | with: 31 | path: ~/.composer/cache/files 32 | key: dependencies-php-${{ matrix.php }}-L${{ matrix.laravel }}-${{ matrix.dependency-version }}-composer-${{ hashFiles('composer.json') }} 33 | 34 | - name: Setup PHP 35 | uses: shivammathur/setup-php@v2 36 | with: 37 | php-version: ${{ matrix.php }} 38 | extensions: dom, mbstring, zip 39 | coverage: none 40 | 41 | - name: Require Laravel Version 42 | run: > 43 | composer require 44 | "laravel/framework:${{ matrix.laravel }}" 45 | --no-interaction --no-update 46 | 47 | - name: Install Composer dependencies 48 | run: composer update --${{ matrix.dependency-version }} --no-interaction --prefer-dist 49 | 50 | - name: Integration Tests 51 | run: php ./vendor/bin/pest 52 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | /.phpunit.cache 2 | /.php-cs-fixer.cache 3 | /.php-cs-fixer.php 4 | /composer.lock 5 | /vendor/ 6 | *.swp 7 | *.swo 8 | playground/* 9 | .idea -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Obikwelu Kyrian Sochima 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## ChromaDB PHP for Laravel 2 | 3 | **A Laravel convenient wrapper for the ChromaDB PHP library, used to interact 4 | with [Chroma](https://github.com/chroma-core/chroma) vector database seamlessly.** 5 | 6 | [![MIT Licensed](https://img.shields.io/badge/license-mit-blue.svg)](https://github.com/CodeWithKyrian/chromadb-laravel/blob/main/LICENSE) 7 | [![GitHub Tests Action Status](https://github.com/CodeWithKyrian/chromadb-laravel/actions/workflows/tests.yml/badge.svg)](https://github.com/CodeWithKyrian/chromadb-laravel/actions/workflows/tests.yml) 8 | [![Latest Version on Packagist](https://img.shields.io/packagist/v/codewithkyrian/chromadb-laravel.svg)](https://packagist.org/packages/codewithkyrian/chromadb-laravel) 9 | 10 | 11 | > **Note:** This package is a wrapper around the [ChromaDB PHP library](https://github.com/CodeWithKyrian/chromadb-php). 12 | > It is meant to be used in Laravel applications. 13 | > If you are looking for a standalone or framework-agnostic way of interacting with Chroma in PHP, check out 14 | > the [ChromaDB PHP library](https://github.com/CodeWithKyrian/chromadb-php) instead. 15 | 16 | ## Installation 17 | 18 | You can install the package via composer: 19 | 20 | ```bash 21 | composer require codewithkyrian/chromadb-laravel 22 | ``` 23 | 24 | After installing the package, you can publish the configuration file using the following command: 25 | 26 | ```bash 27 | php artisan vendor:publish --provider="Codewithkyrian\ChromaDB\ChromaServiceProvider" --tag="config" 28 | ``` 29 | 30 | This will publish a `chromadb.php` file in your config directory with the following content: 31 | 32 | ```php 33 | return [ 34 | /* 35 | |-------------------------------------------------------------------------- 36 | | ChromaDB Host 37 | |-------------------------------------------------------------------------- 38 | | 39 | | Here you may specify your ChromaDB Host. This is the host where your ChromaDB 40 | | instance is running. This is used to connect to your ChromaDB instance. 41 | */ 42 | 'host' => env('CHROMA_HOST', 'localhost'), 43 | 44 | /* 45 | |-------------------------------------------------------------------------- 46 | | ChromaDB Port 47 | |-------------------------------------------------------------------------- 48 | | 49 | | Here you may specify your ChromaDB Port. This is the port where your ChromaDB 50 | | instance is running. This is used to connect to your ChromaDB instance. 51 | */ 52 | 'port' => env('CHROMA_PORT', 8000), 53 | 54 | /* 55 | |-------------------------------------------------------------------------- 56 | | ChromaDB Tenant 57 | |-------------------------------------------------------------------------- 58 | | 59 | | This is the tenant that you want to connect to. 60 | */ 61 | 'tenant' => env('CHROMA_TENANT', 'default_tenant'), 62 | 63 | /* 64 | |-------------------------------------------------------------------------- 65 | | ChromaDB Database 66 | |-------------------------------------------------------------------------- 67 | | 68 | | This is the database that you want to connect to. 69 | */ 70 | 'database' => env('CHROMA_DATABASE', 'default_database'), 71 | 72 | 73 | /* 74 | |-------------------------------------------------------------------------- 75 | | ChromaDB Sync 76 | |-------------------------------------------------------------------------- 77 | | 78 | | This is the configuration for the ChromaDB Sync feature. This feature 79 | | allows you to sync data from your local database to your ChromaDB 80 | | instance. 81 | */ 82 | 'sync' => [ 83 | 84 | /* 85 | |-------------------------------------------------------------------------- 86 | | ChromaDB Sync Enabled 87 | |-------------------------------------------------------------------------- 88 | | 89 | | This option controls whether the ChromaDB Sync feature is enabled. If 90 | | this is set to false, then the ChromaDB Sync feature will not be 91 | | enabled. 92 | */ 93 | 'enabled' => env('CHROMA_SYNC_ENABLED', true), 94 | 95 | /* 96 | |-------------------------------------------------------------------------- 97 | | ChromaDB Sync Queue 98 | |-------------------------------------------------------------------------- 99 | | 100 | | This option controls which queue the ChromaDB Sync feature will use. 101 | | This is used to queue the sync jobs. Set to false to disable queueing 102 | | and run the sync jobs immediately. 103 | */ 104 | 'queue' => env('CHROMA_SYNC_QUEUE', 'default'), 105 | 106 | /* 107 | |-------------------------------------------------------------------------- 108 | | ChromaDB Sync Connection 109 | |-------------------------------------------------------------------------- 110 | | 111 | | This option controls which connection the ChromaDB Sync feature will use. 112 | | This is used to queue the sync jobs. 113 | */ 114 | 'connection' => env('CHROMA_SYNC_CONNECTION', 'database'), 115 | 116 | /* 117 | |-------------------------------------------------------------------------- 118 | | ChromaDB Sync Tries 119 | |-------------------------------------------------------------------------- 120 | | 121 | | This option controls how many times the Job will be retried if it fails 122 | | while trying to sync the data to ChromaDB. 123 | */ 124 | 'tries' => env('CHROMA_SYNC_TRIES', 3), 125 | 126 | ], 127 | ]; 128 | ``` 129 | 130 | As you can see, all configuration options are retrieved from environment variables, so you can easily set them in 131 | your `.env` file without having to modify the configuration file itself. 132 | 133 | ```dotenv 134 | CHROMA_HOST=http://localhost 135 | CHROMA_PORT=8080 136 | CHROMA_TENANT=default 137 | CHROMA_DATABASE=default 138 | CHROMA_SYNC_ENABLED=true 139 | CHROMA_SYNC_QUEUE=default 140 | CHROMA_SYNC_CONNECTION=database 141 | CHROMA_SYNC_TRIES=3 142 | ``` 143 | 144 | ## Usage 145 | 146 | Of course, you need to have the ChromaDB server running before you can use this package. Instructions on how to run 147 | ChromaDB can be found in the [ChromaDB website](https://docs.trychroma.com/deployment). 148 | 149 | ```php 150 | use Codewithkyrian\ChromaDB\Facades\ChromaDB; 151 | 152 | ChromaDB::version(); // Eg. 0.4.2 153 | 154 | $collection = ChromaDB::createCollection('collection_name'); 155 | 156 | $collection = ChromaDB::getCollection('collection_name'); 157 | 158 | $collection = ChromaDB::deleteCollection('collection_name'); 159 | 160 | $collections = ChromaDB::listCollections(); 161 | ``` 162 | 163 | For more usage examples, check out the [ChromaDB PHP library](https://github.com/CodeWithKyrian/chromadb-php). 164 | 165 | ## Working with Eloquent Models 166 | 167 | This package comes with a trait that you can use to associate your Eloquent models with a ChromaDB collection and 168 | automatically sync them to ChromaDB. To get started, add the ChromaModel interface and HasChromaCollection trait to your 169 | model. 170 | 171 | ```php 172 | use Codewithkyrian\ChromaDB\Contracts\ChromaModel; 173 | use Codewithkyrian\ChromaDB\Concerns\HasChromaCollection; 174 | 175 | class User extends Model implements ChromaModel 176 | { 177 | use HasChromaCollection; 178 | 179 | // ... 180 | } 181 | ``` 182 | 183 | After that, there are a few methods that you need to implement in your model. 184 | 185 | - `documentFields()` - This method should return an array of fields that you want to use to form the document that will 186 | be embedded in the ChromaDB collection. If combines the fields in this array to a string and uses that as the 187 | document. This method is optional, but if you don't implement it, you must implement the `toChromaDocument()` method. 188 | ```php 189 | public function documentFields(): array 190 | { 191 | return [ 192 | 'first_name', 193 | 'last_name', 194 | ]; 195 | } 196 | ``` 197 | 198 | - `embeddingFunction()` - This method should return the name of the embedding function that you want to use to embed 199 | your model in the ChromaDB collection. You can use any of 200 | the [built-in embedding functions](https://github.com/CodeWithKyrian/chromadb-php?tab=readme-ov-file#passing-in-embedding-function) 201 | or create your own embedding function by implementing the EmbeddingFunction interface (including Anonymous Classes). 202 | ```php 203 | use Codewithkyrian\ChromaDB\Embeddings\JinaEmbeddingFunction; 204 | 205 | public function embeddingFunction(): string 206 | { 207 | return new JinaEmbeddingFunction('jina-api-key'); 208 | } 209 | ``` 210 | - `collectionName()` - This method should return the name you want for the ChromaDB collection associated with your 211 | model. By default, it returns the model's table name. 212 | - `toChromaDocument()` (optional) - If you don't like the default way of combining the fields in the `documentFields()` 213 | method, you can implement this method to return the document that will be embedded in the ChromaDB collection. 214 | ```php 215 | public function toChromaDocument(): string 216 | { 217 | return $this->first_name . ' ' . $this->last_name; 218 | } 219 | ``` 220 | - `metadataFields()` (optional) - This method should return an array of fields that you want to use to form the metadata 221 | that will be embedded in the ChromaDB collection. It'll be saved as a json object in the ChromaDB collection. By 222 | default, it only returns the `id` field, so the metadata will be `{ "id": 1 }`. 223 | ```php 224 | public function metadataFields(): array 225 | { 226 | return [ 227 | 'id', 228 | 'first_name', 229 | 'last_name', 230 | ]; 231 | } 232 | ``` 233 | - `toChromaMetadata()` (optional) - If you want more control over the metadata that will be embedded in the ChromaDB 234 | collection, you can implement this method to return the metadata that will be embedded in the ChromaDB collection. Be 235 | sure to return an associative array. 236 | ```php 237 | public function toChromaMetadata(): array 238 | { 239 | return [ 240 | 'id' => $this->id, 241 | 'first_name' => $this->first_name, 242 | 'last_name' => $this->last_name, 243 | ]; 244 | } 245 | ``` 246 | 247 | After implementing the methods above (only two are required), you model now has a `getChromaCollection()` method that 248 | you can use to get the ChromaDB collection associated with your model. 249 | 250 | ```php 251 | $collection = User::getChromaCollection(); 252 | 253 | $collection->name; // users 254 | $collection->count(); 255 | ``` 256 | 257 | ### Syncing Models to ChromaDB 258 | 259 | By default, the package will automatically sync your models to ChromaDB whenever they are created, updated or deleted 260 | provided there was a change in the attributes since the last sync. 261 | You can disable this by setting the `chromadb.sync.enabled` config option to `false` or better still, set 262 | the `CHROMA_SYNC_ENABLED` 263 | to false. 264 | 265 | The syncing of models is queued so be sure to set up your queue and workers the Laravel recommended way. You can set the 266 | queue, connection 267 | and the number tries for the job in the config or using the `CHROMA_SYNC_QUEUE`, `CHROMA_SYNC_CONNECTION` 268 | and `CHROMA_SYNC_TRIES` respectively. 269 | However, you can set the `CHROMA_SYNC_QUEUE` to false to disable using queues to perform the sync. 270 | 271 | ### Querying the collection 272 | 273 | While you can still query the collection after getting it from the `getChromaCollection()` method, you can also query 274 | the collection 275 | using the model. The model has a `queryChromaCollection()` scope that you can use to query the collection. 276 | 277 | ```php 278 | $searchTerm = 'Kyrian'; 279 | 280 | $users = User::queryChromaCollection($searchTerm, 10) 281 | ->where('first_name', 'John') 282 | ->get(); 283 | ``` 284 | 285 | The arguments for the `queryChromaCollection()` method are the same as the `query()` method in the ChromaDB PHP library. 286 | Also, this meethod 287 | sorts the results by the `distance` field in the results. 288 | 289 | ### Truncating the collection 290 | 291 | You can truncate the collection associated with a model using the `truncateChromaCollection()` method on the model. 292 | 293 | ```php 294 | 295 | User::truncateChromaCollection(); 296 | ``` 297 | 298 | ## Testing 299 | 300 | ``` 301 | // Run chroma by running the docker compose file in the repo 302 | docker compose up -d 303 | 304 | composer test 305 | ``` 306 | 307 | ## Contributors 308 | 309 | - [Kyrian Obikwelu](https://github.com/CodeWithKyrian) 310 | - Other contributors are welcome. 311 | 312 | ## License 313 | 314 | This project is licensed under the MIT License. See 315 | the [LICENSE](https://github.com/codewithkyrian/chromadb-php/blob/main/LICENSE) file for more information. 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "codewithkyrian/chromadb-laravel", 3 | "description": "ChromaDB Laravel is a Laravel client for the Chroma Open Source Embedding Database", 4 | "keywords": [ 5 | "chromadb", 6 | "php", 7 | "laravel", 8 | "embedding", 9 | "sdk", 10 | "database", 11 | "vectors", 12 | "semantic", 13 | "search", 14 | "chroma", 15 | "open-source" 16 | ], 17 | "type": "library", 18 | "license": "MIT", 19 | "require": { 20 | "php": "^8.1", 21 | "laravel/framework": "^9.5.0|^10.34.2", 22 | "codewithkyrian/chromadb-php": "^0.1.0" 23 | }, 24 | "require-dev": { 25 | "pestphp/pest": "^1.9.1 | ^2.15", 26 | "symfony/var-dumper": "^6.3 |^7.0.1", 27 | "mockery/mockery": "^1.6", 28 | "orchestra/testbench": "^7.0 | ^8.20" 29 | }, 30 | "autoload": { 31 | "psr-4": { 32 | "Codewithkyrian\\ChromaDB\\": "src/" 33 | } 34 | }, 35 | "authors": [ 36 | { 37 | "name": "Kyrian Obikwelu", 38 | "email": "kyrianobikwelu@gmail.com" 39 | } 40 | ], 41 | "config": { 42 | "allow-plugins": { 43 | "pestphp/pest-plugin": true 44 | } 45 | }, 46 | "minimum-stability": "dev", 47 | "prefer-stable": true, 48 | "extra": { 49 | "laravel": { 50 | "providers": [ 51 | "Codewithkyrian\\ChromaDB\\ChromaServiceProvider" 52 | ] 53 | } 54 | }, 55 | "scripts": { 56 | "test": "vendor/bin/pest", 57 | "test:coverage": "XDEBUG_MODE=coverage ./vendor/bin/pest --coverage", 58 | "post-autoload-dump": [ 59 | "@clear", 60 | "@prepare" 61 | ], 62 | "clear": "@php vendor/bin/testbench package:purge-skeleton --ansi", 63 | "prepare": "@php vendor/bin/testbench package:discover --ansi", 64 | "build": "@php vendor/bin/testbench workbench:build --ansi", 65 | "serve": [ 66 | "Composer\\Config::disableProcessTimeout", 67 | "@build", 68 | "@php vendor/bin/testbench serve" 69 | ] 70 | }, 71 | "autoload-dev": { 72 | "psr-4": { 73 | "Codewithkyrian\\ChromaDB\\Tests\\": "tests/", 74 | "Workbench\\App\\": "workbench/app/", 75 | "Workbench\\Database\\Factories\\": "workbench/database/factories/", 76 | "Workbench\\Database\\Seeders\\": "workbench/database/seeders/" 77 | } 78 | } 79 | } -------------------------------------------------------------------------------- /config/chromadb.php: -------------------------------------------------------------------------------- 1 | env('CHROMA_HOST', 'localhost'), 15 | 16 | /* 17 | |-------------------------------------------------------------------------- 18 | | ChromaDB Port 19 | |-------------------------------------------------------------------------- 20 | | 21 | | Here you may specify your ChromaDB Port. This is the port where your ChromaDB 22 | | instance is running. This is used to connect to your ChromaDB instance. 23 | */ 24 | 'port' => env('CHROMA_PORT', 8000), 25 | 26 | /* 27 | |-------------------------------------------------------------------------- 28 | | ChromaDB Tenant 29 | |-------------------------------------------------------------------------- 30 | | 31 | | This is the tenant that you want to connect to. 32 | */ 33 | 'tenant' => env('CHROMA_TENANT', 'default_tenant'), 34 | 35 | /* 36 | |-------------------------------------------------------------------------- 37 | | ChromaDB Database 38 | |-------------------------------------------------------------------------- 39 | | 40 | | This is the database that you want to connect to. 41 | */ 42 | 'database' => env('CHROMA_DATABASE', 'default_database'), 43 | 44 | 45 | /* 46 | |-------------------------------------------------------------------------- 47 | | ChromaDB Sync 48 | |-------------------------------------------------------------------------- 49 | | 50 | | This is the configuration for the ChromaDB Sync feature. This feature 51 | | allows you to sync data from your local database to your ChromaDB 52 | | instance. 53 | */ 54 | 'sync' => [ 55 | 56 | /* 57 | |-------------------------------------------------------------------------- 58 | | ChromaDB Sync Enabled 59 | |-------------------------------------------------------------------------- 60 | | 61 | | This option controls whether the ChromaDB Sync feature is enabled. If 62 | | this is set to false, then the ChromaDB Sync feature will not be 63 | | enabled. 64 | */ 65 | 'enabled' => env('CHROMA_SYNC_ENABLED', true), 66 | 67 | /* 68 | |-------------------------------------------------------------------------- 69 | | ChromaDB Sync Queue 70 | |-------------------------------------------------------------------------- 71 | | 72 | | This option controls which queue the ChromaDB Sync feature will use. 73 | | This is used to queue the sync jobs. Set to false to disable queueing 74 | | and run the sync jobs immediately. 75 | */ 76 | 'queue' => env('CHROMA_SYNC_QUEUE', 'default'), 77 | 78 | /* 79 | |-------------------------------------------------------------------------- 80 | | ChromaDB Sync Connection 81 | |-------------------------------------------------------------------------- 82 | | 83 | | This option controls which connection the ChromaDB Sync feature will use. 84 | | This is used to queue the sync jobs. 85 | */ 86 | 'connection' => env('CHROMA_SYNC_CONNECTION', 'database'), 87 | 88 | /* 89 | |-------------------------------------------------------------------------- 90 | | ChromaDB Sync Tries 91 | |-------------------------------------------------------------------------- 92 | | 93 | | This option controls how many times the Job will be retried if it fails 94 | | while trying to sync the data to ChromaDB. 95 | */ 96 | 'tries' => env('CHROMA_SYNC_TRIES', 3), 97 | 98 | ], 99 | ]; 100 | 101 | -------------------------------------------------------------------------------- /phpunit.xml: -------------------------------------------------------------------------------- 1 | 2 | 7 | 8 | 9 | ./tests 10 | 11 | 12 | 13 | 14 | ./src 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | -------------------------------------------------------------------------------- /src/ChromaServiceProvider.php: -------------------------------------------------------------------------------- 1 | publishes([ 19 | __DIR__ . '/../config/chromadb.php' => config_path('chromadb.php'), 20 | ], 'config'); 21 | } 22 | 23 | public function register(): void 24 | { 25 | $this->mergeConfigFrom(__DIR__ . '/../config/chromadb.php', 'chromadb'); 26 | 27 | $this->app->singleton('chromadb', function () { 28 | return ChromaDB::factory() 29 | ->withHost(config('chromadb.host')) 30 | ->withPort(config('chromadb.port')) 31 | ->withDatabase(config('chromadb.database')) 32 | ->withTenant(config('chromadb.tenant')) 33 | ->connect(); 34 | }); 35 | } 36 | 37 | public function provides(): array 38 | { 39 | return ['chromadb']; 40 | } 41 | 42 | public function defers() : array 43 | { 44 | return ['chromadb']; 45 | } 46 | } -------------------------------------------------------------------------------- /src/Concerns/HasChromaCollection.php: -------------------------------------------------------------------------------- 1 | wasRecentlyCreated ? $model->getAttributes() : $model->getChanges(); 27 | $changedFields = array_keys($changes); 28 | 29 | if (!config('chromadb.sync.queue', false)) { 30 | UpdateChromaCollectionJob::dispatchSync($model, $changedFields); 31 | } else { 32 | UpdateChromaCollectionJob::dispatch($model, $changedFields); 33 | } 34 | }); 35 | 36 | static::deleted(function (Model&ChromaModel $model) { 37 | if (!config('chromadb.sync.queue', false)) { 38 | DeleteChromaCollectionItemJob::dispatchSync($model::class, $model->getKey()); 39 | } else { 40 | DeleteChromaCollectionItemJob::dispatch($model::class, $model->getKey()); 41 | } 42 | }); 43 | } 44 | } 45 | 46 | public static function getChromaCollection(): CollectionResource 47 | { 48 | $model = new static(); 49 | 50 | static::$chromaCollection = ChromaDB::getOrCreateCollection( 51 | name: $model->collectionName(), 52 | embeddingFunction: $model->embeddingFunction(), 53 | ); 54 | 55 | 56 | return static::$chromaCollection; 57 | } 58 | 59 | public function scopeQueryChromaCollection( 60 | Builder $query, 61 | string $queryText, 62 | int $nResults = 10, 63 | array $where = null, 64 | array $whereDocument = null, 65 | array $include = null 66 | ): void 67 | { 68 | $queryResponse = self::getChromaCollection()->query( 69 | queryTexts: [$queryText], 70 | nResults: $nResults, 71 | where: $where, 72 | whereDocument: $whereDocument, 73 | include: $include 74 | ); 75 | 76 | $ids = $queryResponse->ids[0]; 77 | 78 | // Create a temporary table expression for sorting 79 | $tempTableExpression = collect($ids)->map(function ($id, $index) use ($queryResponse) { 80 | $distance = $queryResponse->distances[0][$index]; 81 | return "SELECT $id AS id, $distance AS distance"; 82 | })->implode(' UNION ALL '); 83 | 84 | // Join with the temporary table expression for sorting 85 | $query->join(DB::raw("($tempTableExpression) AS temp_chroma_sort"), function ($join) { 86 | $join->on("{$this->getTable()}.id", '=', 'temp_chroma_sort.id'); 87 | }); 88 | 89 | // Order the query based on the distances 90 | $query->orderBy('temp_chroma_sort.distance'); 91 | } 92 | 93 | /** 94 | * The fields that should be used to create the Chroma metadata. 95 | * 96 | * @return string[] 97 | */ 98 | public function metadataFields(): array 99 | { 100 | return ['id']; 101 | } 102 | 103 | /** 104 | * The fields that should be used to create the Chroma document. 105 | * 106 | * @return string[] 107 | */ 108 | public function documentFields(): array 109 | { 110 | return []; 111 | } 112 | 113 | /** 114 | * The collection name to use for the model. 115 | */ 116 | public function collectionName(): string 117 | { 118 | return $this->getTable(); 119 | } 120 | 121 | 122 | public function toChromaMetadata(): array 123 | { 124 | 125 | return collect($this->metadataFields()) 126 | ->mapWithKeys(function (string $field) { 127 | return [$field => $this->getAttribute($field)]; 128 | }) 129 | ->toArray(); 130 | } 131 | 132 | public function toChromaDocument(): string 133 | { 134 | return collect($this->documentFields()) 135 | ->map(function (string $field) { 136 | return "$field : {$this->getAttribute($field)}"; 137 | }) 138 | ->join(' ; ', ' and '); 139 | } 140 | 141 | public static function truncateChromaCollection(): void 142 | { 143 | $collection = self::getChromaCollection(); 144 | 145 | $collection->delete($collection->get()->ids); 146 | } 147 | } 148 | -------------------------------------------------------------------------------- /src/Contracts/ChromaModel.php: -------------------------------------------------------------------------------- 1 | $model 19 | * @param string $key 20 | */ 21 | public function __construct(protected string $model, protected string $key) 22 | { 23 | $this->onQueue(config('chromadb.sync.queue')); 24 | $this->onConnection(config('chromadb.sync.connection')); 25 | } 26 | 27 | public function handle(): void 28 | { 29 | $this->model::getChromaCollection()->delete([$this->key]); 30 | } 31 | } 32 | -------------------------------------------------------------------------------- /src/Jobs/UpdateChromaCollectionJob.php: -------------------------------------------------------------------------------- 1 | onQueue(config('chromadb.sync.queue')); 25 | $this->onConnection(config('chromadb.sync.connection')); 26 | } 27 | 28 | public function handle(): void 29 | { 30 | // If there are no changes, no need to update the chroma collection 31 | if (empty($this->changedFields)) return; 32 | 33 | $metadata = null; 34 | $document = null; 35 | 36 | // Helper function to check if any fields in fieldsArray are among the changed attributes 37 | $fieldsChanged = function ($fieldsArray){ 38 | return $fieldsArray && count(array_intersect($fieldsArray, $this->changedFields)) > 0; 39 | }; 40 | 41 | if ($fieldsChanged($this->model->metadataFields())) { 42 | $metadata = $this->model->toChromaMetadata(); 43 | } 44 | 45 | if ($fieldsChanged($this->model->documentFields())) { 46 | $document = $this->model->toChromaDocument(); 47 | } 48 | 49 | // If any of the fields in metadataFields() or documentFields() is among the changed attributes 50 | if ($metadata || $document) { 51 | $this->model::getChromaCollection()->upsert( 52 | ids: [strval($this->model->getKey())], 53 | metadatas: $metadata ? [$metadata] : null, 54 | documents: $document ? [$document] : null, 55 | ); 56 | } 57 | } 58 | 59 | public function tries(): int 60 | { 61 | return config('chromadb.sync.tries'); 62 | } 63 | } 64 | -------------------------------------------------------------------------------- /tests/ChromaServiceProviderTest.php: -------------------------------------------------------------------------------- 1 | get('chromadb'))->toBeInstanceOf(Client::class); 12 | }); 13 | 14 | it('binds the client on the container as singleton', function () { 15 | expect(app()->get('chromadb'))->toBeInstanceOf(Client::class) 16 | ->and(app()->get('chromadb'))->toBe(app()->get('chromadb')); 17 | }); -------------------------------------------------------------------------------- /tests/Concerns/HasChromaCollectionTest.php: -------------------------------------------------------------------------------- 1 | toBeInstanceOf(CollectionResource::class) 20 | ->and($collection->name)->toBe('test_models'); 21 | }); 22 | 23 | it('dispatches an async job to update the collection on save', function () { 24 | Queue::fake(); 25 | 26 | TestModel::create([ 27 | 'title' => 'Test Model', 28 | 'document' => 'This is a test model' 29 | ]); 30 | 31 | Queue::assertPushedOn(config('chromadb.sync.queue'), UpdateChromaCollectionJob::class); 32 | }); 33 | 34 | it('dispatches an async job to update the collection on delete', function () { 35 | Queue::fake(); 36 | 37 | $model = TestModel::create([ 38 | 'title' => 'Test Model', 39 | 'document' => 'This is a test model' 40 | ]); 41 | 42 | $model->delete(); 43 | 44 | Queue::assertPushedOn(config('chromadb.sync.queue'), DeleteChromaCollectionItemJob::class); 45 | }); 46 | 47 | it('dispatches a sync job to update the collection on save', function () { 48 | config(['chromadb.sync.queue' => false]); 49 | 50 | $model = TestModel::create([ 51 | 'title' => 'Test Model', 52 | 'document' => 'This is a test model' 53 | ]); 54 | 55 | $collection = TestModel::getChromaCollection(); 56 | 57 | expect($collection->count())->toBe(1); 58 | }); 59 | 60 | it('dispatches a sync job to update the collection on delete', function () { 61 | config(['chromadb.sync.queue' => false]); 62 | 63 | $model = TestModel::create([ 64 | 'title' => 'Test Model', 65 | 'document' => 'This is a test model' 66 | ]); 67 | 68 | $collection = TestModel::getChromaCollection(); 69 | 70 | expect($collection->count())->toBe(1); 71 | 72 | $model->delete(); 73 | 74 | expect($collection->count())->toBe(0); 75 | }); 76 | 77 | it('does not dispatch a job to update the collection on save when sync is disabled', function () { 78 | config(['chromadb.sync.enabled' => false]); 79 | 80 | Queue::fake(); 81 | 82 | TestModel::create([ 83 | 'title' => 'Test Model', 84 | 'document' => 'This is a test model' 85 | ]); 86 | 87 | Queue::assertNotPushed(UpdateChromaCollectionJob::class); 88 | }); 89 | 90 | it('does not dispatch a job to update the collection on delete when sync is disabled', function () { 91 | config(['chromadb.sync.enabled' => false]); 92 | 93 | Queue::fake(); 94 | 95 | $model = TestModel::create([ 96 | 'title' => 'Test Model', 97 | 'document' => 'This is a test model' 98 | ]); 99 | 100 | $model->delete(); 101 | 102 | Queue::assertNotPushed(DeleteChromaCollectionItemJob::class); 103 | }); 104 | 105 | it('does not dispatch a job to update the collection on save when queue is disabled', function () { 106 | config(['chromadb.sync.queue' => false]); 107 | 108 | Bus::fake(); 109 | 110 | TestModel::create([ 111 | 'title' => 'Test Model', 112 | 'document' => 'This is a test model' 113 | ]); 114 | 115 | Bus::assertDispatchedSync(UpdateChromaCollectionJob::class); 116 | }); 117 | 118 | it('does not dispatch a job to update the collection on delete when queue is disabled', function () { 119 | config(['chromadb.sync.queue' => false]); 120 | 121 | Bus::fake(); 122 | 123 | $model = TestModel::create([ 124 | 'title' => 'Test Model', 125 | 'document' => 'This is a test model' 126 | ]); 127 | 128 | $model->delete(); 129 | 130 | Bus::assertDispatchedSync(DeleteChromaCollectionItemJob::class); 131 | }); 132 | 133 | it('can truncate the collection', function () { 134 | config(['chromadb.sync.queue' => false]); 135 | 136 | $collection = TestModel::getChromaCollection(); 137 | 138 | expect($collection->count())->toBe(0); 139 | 140 | TestModel::create([ 141 | 'title' => 'Test Model', 142 | 'document' => 'This is a test model' 143 | ]); 144 | 145 | expect($collection->count())->toBe(1); 146 | 147 | TestModel::truncateChromaCollection(); 148 | 149 | expect($collection->count())->toBe(0); 150 | }); 151 | 152 | it('applies the correct scope to the query', function () { 153 | $query = TestModel::queryChromaCollection('test'); 154 | 155 | expect($query->toSql()) 156 | ->toContain('test_models', 'temp_chroma_sort'); 157 | }); 158 | 159 | -------------------------------------------------------------------------------- /tests/Facades/ChromaDBTest.php: -------------------------------------------------------------------------------- 1 | toBeString() 14 | ->toMatch('/^[0-9]+\.[0-9]+\.[0-9]+$/'); 15 | }); 16 | 17 | -------------------------------------------------------------------------------- /tests/Pest.php: -------------------------------------------------------------------------------- 1 | beforeEach(fn() => ChromaDB::deleteAllCollections()) 10 | ->in(__DIR__); 11 | 12 | -------------------------------------------------------------------------------- /tests/TestCase.php: -------------------------------------------------------------------------------- 1 | loadMigrationsFrom(workbench_path('database/migrations')); 27 | } 28 | } -------------------------------------------------------------------------------- /workbench/app/Models/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CodeWithKyrian/chromadb-laravel/689ac9dca9c9c0019b96c08418a17d26e04e8a00/workbench/app/Models/.gitkeep -------------------------------------------------------------------------------- /workbench/app/Models/TestModel.php: -------------------------------------------------------------------------------- 1 | id(); 12 | $table->string('title'); 13 | $table->text('document'); 14 | $table->timestamps(); 15 | }); 16 | } 17 | 18 | public function down(): void 19 | { 20 | Schema::dropIfExists('test_models'); 21 | } 22 | }; 23 | -------------------------------------------------------------------------------- /workbench/database/seeders/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/CodeWithKyrian/chromadb-laravel/689ac9dca9c9c0019b96c08418a17d26e04e8a00/workbench/database/seeders/.gitkeep -------------------------------------------------------------------------------- /workbench/database/seeders/DatabaseSeeder.php: -------------------------------------------------------------------------------- 1 | get('/user', function (Request $request) { 18 | // return $request->user(); 19 | // }); 20 | -------------------------------------------------------------------------------- /workbench/routes/console.php: -------------------------------------------------------------------------------- 1 | comment(Inspiring::quote()); 19 | // })->purpose('Display an inspiring quote'); 20 | -------------------------------------------------------------------------------- /workbench/routes/web.php: -------------------------------------------------------------------------------- 1 |