feat: Enhance Chroma v2 API support with new endpoints, improved error handling, and major refactoring #16
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ures - Added methods for tenant management: create, update, and retrieve tenants. - Introduced new endpoints for collection management: create, update, delete, and query collections. - Updated existing methods to improve clarity and functionality, including health checks and user identity retrieval. - Enhanced request classes with detailed parameter documentation for better usability. - Refactored existing methods to align with new naming conventions for consistency.
- Replaces hard Guzzle dependency with PSR-18 Client and PSR-17 Factory discovery. - Refactors `Factory`and `Api` to use `ClientInterface` and `RequestFactoryInterface`. - Replaces specific `authToken` handling with generic `headers` support in `Factory` and `Api`. - Deprecates `Factory::withAuthToken()` in favor of `withHeader()`. - Updates all embedding functions to use the discovered PSR-18 client. BREAKING CHANGE: `Factory::withHttpClient` has been removed.
- Adds `ChromaDB::local()` and `ChromaDB::cloud()` helper methods for easier connection configuration. - Deprecates `ChromaDB::client()` in favor of `ChromaDB::local()->connect()` or `ChromaDB::factory()->connect()`. BREAKING CHANGE: `ChromaDB::reset()` has been removed. Use `$client->reset()` instead.
…s and configuration.
…n`, and structured data for `add`.
…on, and enhance request payload generation.
…roduce `Record` data types for items.
…environment variables from ChromaServer process.
- Simplify `Api::handleErrorResponse` to align with Chroma v2 API consistency, utilizing direct JSON decoding and status code mapping (e.g., mapping 409 to `UniqueConstraintException`). - Rename exception classes to remove redundant prefixes (e.g., `ChromaConnectionException` → `ConnectionException`). - Standardize exception instantiation via the `ChromaException::create()` factory. - Implement robust client-side validation in Collection methods for embeddings, `nResults`, IDs, and metadata. - update `ApiTest`, `CollectionTest`, and `QueryFilteringTest` with comprehensive negative test scenarios.
…or parameters optional with null defaults, simplifying test calls.
Note: Collection forking is only supported for Chroma Cloud, not local Chroma instances.
- Extract embedding generation into dedicated prepareEmbeddings method - Support mixed embeddings arrays where some items have embeddings and others are null, generating missing ones in batch while maintaining order - Separate concerns: prepareEmbeddings handles generation only, validate handles all validation logic
…ramsey/composer-install@v3, streamline PHP setup, and remove caching steps
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR builds upon the existing Chroma v2 API migration (from #14 ) by adding new v2 API endpoints, significantly improving error handling, and introducing major architectural improvements and new features. The package has been enhanced with better developer experience, type safety, and additional functionality while maintaining backward compatibility where possible.
Motivation and Context
Chroma has released version 1.0 with a new v2 API that provides a Rust backend and more consistent approach to vector database operations. The previous package version (0.4.0) was built against Chroma 0.4.0 and the v1 API, which had inconsistencies in error handling and response formats.
A previous PR already migrated the package to support Chroma v1.0 and the v2 API. This PR extends that work by:
What's Changed
API Client Enhancements
Apiclass with new v2 API endpoints (collection forking, improved tenant/database management)withHeader()andwithHeaders()methodsCollection Model Simplification
CollectionResourcewrapper class -Collectionis now the direct resource modellistCollections()can be used immediately without conversionsetEmbeddingFunction()method for runtime embedding function assignmentNew Features
RecordandScoredRecordtypes for structured data handlingRecord::make('id')->withDocument('text')->withMetadata(['key' => 'value'])add(),update(), andupsert()now accept arrays ofRecordobjectsget()andquery()responses can be converted to records viaasRecords()Wherequery builder for type-safe filteringWhere::field('category')->eq('news')Where::document()->contains('text')Where::all(),Where::any()Connection Improvements
ChromaDB::local()helper for local/self-hosted instancesChromaDB::cloud()helper for Chroma Cloud connectionsChromaDB::client()in favor of explicitlocal()orfactory()usagereset()from static method to instance method:$client->reset()withAuthToken()with genericwithHeader('X-Chroma-Token', $token)Exception Handling
Generated/Exceptions/toExceptions/namespaceChromaException::create()factory methodConnectionExceptionfor network-level errorsTesting Infrastructure
Feature/directory structureDocumentation and Examples
document-chunking-cloudexample demonstrating real-world usageCode Organization
Requests/andResponses/foldersModels/namespaceTypes/namespace for value objects (Record, ScoredRecord, Includes)Query/namespace for query builder classesEmbedding Functions
Breaking Changes
API Client
ChromaApiClientclass - replaced withApiclassClientInterface(GuzzleHttp still works via discovery)Factory::withHttpClient()method - HTTP client is auto-discoveredConnection Methods
ChromaDB::client()- useChromaDB::local()->connect()orChromaDB::factory()->connect()insteadChromaDB::reset()static method - use$client->reset()instance method insteadFactory::withAuthToken()- useFactory::withHeader('X-Chroma-Token', $token)insteadCollection Resource
CollectionResourceclass -Collectionis now the direct resourcelistCollections()now returnsCollection[]instead ofCollectionResource[]Request/Response Models
Generated/Requests/andGenerated/Responses/namespacesRequests/namespace with updated method signaturesExceptions
ChromaNotFoundException→NotFoundExceptionChromaConnectionException→ConnectionExceptionChromaValueException→ValueExceptionGenerated\ExceptionstoExceptionsChromaException::create()factory instead ofthrowSpecific()Dependencies
guzzlehttp/guzzlemoved fromrequiretorequire-devpsr/http-client,psr/http-factory, andphp-http/discoveryas required dependenciesCloses #12