Update to the Chroma v2 API, with pull requests 80 and 82, and fixes

[Laurianti]

This pull request brings back here the work collected in ChromaDotNet/ChromaDB.Client: the pending pull requests #80 by @inlineHamed and #82 by @richlander, fixes for the open issues, and new features. Each change keeps its own commit and author. The branch follows the fork's main, so the pull request stays current. If you merge it, a merge commit or a rebase keeps the original commits and their authors in the history.

The fork's client is used by:

• CommunityToolkit.VectorData.Chroma, the Chroma provider for Microsoft.Extensions.VectorData in the AI Community Toolkit of the .NET Foundation (Chroma: add the MEVD provider CommunityToolkit/AI#58).
• The Chroma integrations for Aspire in the Aspire Community Toolkit (Add Chroma hosting and client integrations CommunityToolkit/Aspire#2219), whose client integration is built on it.

What it brings:

• The whole Chroma v2 API, from update to api 2 #80 and Update to Chroma v2 API #82. The v1 API stays available for the servers that have only it.
• Chroma Cloud: the Search API, sparse vectors and BM25, collection forking, and writes in batches within its limits.
• Tenants and databases, collection settings (HNSW, SPANN, schema), lists in metadata, $contains and $regex filters, URIs.
• Dependency injection, OpenTelemetry traces and metrics, clients that can be mocked.
• .NET 8 and later, .NET 10 included; .NET Framework 4.6.2 and later; .NET Standard 2.0, which covers .NET Core 3.1 and .NET 5 to 7. Trimming and NativeAOT.
• Security: CodeQL, OpenSSF Scorecard and Dependabot, GitHub Actions pinned by hash, and release packages signed with Sigstore and with build provenance attestations.
• Fixes for the issues below, and for the answers of older servers.

The CI runs the whole suite against Chroma versions from 0.4.10 to 1.5.9, with both APIs; docs/COMPATIBILITY.md lists the versions tested and their differences. Every change is in the release notes.

Breaking changes: the asynchronous methods end in Async, lists and metadata are read-only, and a few types changed. The migration guide shows how to adapt.

Without the repository variables of the fork, the package id stays ChromaDB.Client and the CI publishes with NUGET_API_KEY, as today. The README and the migration guide describe the fork: those parts would need to change here.

Fixes #69 (opened by @cincuranet)
Fixes #78 (reported by @Lingchar, with the fix proposed there)
Fixes #79 (reported by @hannahhaken)
Fixes #81 (reported by @mubarak0443)
Fixes #76 (opened by @luisquintanilla)
Fixes #83 (reported by @Chris-Maina)
Fixes #5
Fixes #33
Fixes #6

Supersedes #80 and #82.

Co-authored-by: Rich 2608468+richlander@users.noreply.github.com
Co-authored-by: Hamed 11094468+inlineHamed@users.noreply.github.com

[Copilot]

Copilot review overview

🟡 Changes recommended

Fork-specific branding and package instructions contradict the target repository’s package identity.

Review effort: Balanced
Findings: 2

Open (2)

• Rewrite fork-specific README references for the target repository · New
• Correct migration guide package references to use ChromaDB.Client · New

What changed in this PR

Migrates the client to Chroma API v2 while improving compatibility, cancellation, error handling, dependency injection, and CI coverage.

Changes:

• Migrates endpoints and defaults to API v2.
• Adds cancellation support and fixes response/request handling.
• Expands tests and CI across Chroma and .NET versions.

File	Description
v2-migration/​MIGRATION_GUIDE_V2.md	Adds migration guidance.
Samples/​ChromaDB.Client.Sample/​Program.cs	Uses the v2 endpoint.
README.md	Documents compatibility and migration.
ChromaDB.Client/​Models/​Responses/​GeneralError.cs	Supports v2 error fields.
ChromaDB.Client/​Models/​Responses/​CollectionEntriesQueryResponse.cs	Handles optional distances and data.
ChromaDB.Client/​Models/​Responses/​CollectionEntriesGetResponse.cs	Makes response data optional.
ChromaDB.Client/​Models/​Requests/​CollectionModifyRequest.cs	Corrects modify field names.
ChromaDB.Client/​Common/​HttpClientHelpers.cs	Adds cancellation, URI construction, and error handling.
ChromaDB.Client/​Common/​CollectionQueryEntryMapper.cs	Maps optional distances.
ChromaDB.Client/​Common/​ClientConstants.cs	Changes the default endpoint to v2.
ChromaDB.Client/​Common/​ChromaHttpClient.cs	Avoids mutating shared HTTP clients.
ChromaDB.Client/​ChromaDB.Client.csproj	Updates version and package metadata.
ChromaDB.Client/​ChromaCollectionQueryEntry.cs	Makes distance nullable.
ChromaDB.Client/​ChromaCollectionClient.cs	Migrates collection operations to v2.
ChromaDB.Client/​ChromaClient.cs	Migrates client operations to v2.
ChromaDB.Client.Tests/​TestContainer/​ChromaDBBuilder.cs	Makes the tested Chroma image configurable.
ChromaDB.Client.Tests/​DependencyInjectionTests.cs	Tests DI registration.
ChromaDB.Client.Tests/​CollectionClientTests.cs	Strengthens modify and embedding tests.
ChromaDB.Client.Tests/​CollectionClientQueryTests.cs	Tests omitted distances.
ChromaDB.Client.Tests/​CollectionClientCUDTests.cs	Adapts CRUD tests across server versions.
ChromaDB.Client.Tests/​ClientTests.cs	Tests shared HTTP clients and errors.
ChromaDB.Client.Tests/​ClientResetTests.cs	Handles version-specific reset settings.
ChromaDB.Client.Tests/​ClientAuthTests.cs	Skips removed Chroma 1.x authentication.
ChromaDB.Client.Tests/​ChromaTestsBase.cs	Adds version-aware test helpers.
ChromaDB.Client.Tests/​ChromaDB.Client.Tests.csproj	Tests alternate client target frameworks.
ChromaDB.Client.Tests/​CancellationTests.cs	Verifies cancellation propagation.
ChromaDB.Client.DependencyInjection/​ChromaDB.Client.DependencyInjection.csproj	Updates DI package metadata.
ChromaDB.Client.DependencyInjection/​ChromaClientExtensions.cs	Registers configuration options.
.github/​workflows/​ci.yml	Adds server matrix, packaging, and publishing updates.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.