Chroma v2 API, pull requests 80 and 82, and fixes: continued in ChromaDotNet.Client

[Laurianti]

Status (October 16, 2026): This pull request was meant to bring the work back here, so that the client could continue from this repository. It has had no answer since it was opened on October 3, 2026, so the client now continues in ChromaDotNet/ChromaDB.Client, published as ChromaDotNet.Client: v2 API and Chroma Cloud, tested with Chroma 0.4.10 to 1.5.9, used by the AI and Aspire Community Toolkits of the .NET Foundation. I contacted the owners of ChromaDB.Client through NuGet. This pull request stays as a draft, for reference. Issues and contributions are welcome in ChromaDotNet.

Date	Who	Event
2025-02-17	@cincuranet	Last commit on master
2025-05-06	@inlineHamed	#80 opened: update to the v2 API
2025-07-09	@Laurianti	A workaround for the v2 API in #69: a DelegatingHandler that rewrites the v1 calls
2025-08-06	@ssone95	Last reply from a maintainer, on #80
2025-10-14	@richlander	#82 opened: update to the Chroma v2 API
2026-10-03	@Laurianti	This pull request, with #80, #82 and their authors
2026-10-16	@Laurianti	Owners contacted through NuGet; this pull request moved to draft

---

This pull request collects the work of 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.

Where the packages are used:

• 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):
  • recommended by Semantic Kernel
  • recommended by LangChain.Databases (README)
  • listed in the .NET community projects of Microsoft Agent Framework
  • used by Generative AI for Beginners .NET
  • used by LangChain .NET
  • used by LangChain.Databases (integration tests)
• ChromaDotNet.Client, which I maintain:
  • used by CommunityToolkit.VectorData.Chroma
  • used by the Aspire Community Toolkit (Add Chroma hosting and client integrations CommunityToolkit/Aspire#2219)
  • used by BotSharp
  • used by LLM Tornado
  • proposed as a module in Testcontainers for .NET
  • proposed in eShopLite, the Azure sample, to fix its Chroma scenario

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.

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.