Skip to content

Add Chroma hosting and client integrations - #2219

Open
Laurianti wants to merge 8 commits into
CommunityToolkit:mainfrom
Laurianti:chroma-integration
Open

Add Chroma hosting and client integrations#2219
Laurianti wants to merge 8 commits into
CommunityToolkit:mainfrom
Laurianti:chroma-integration

Conversation

@Laurianti

@Laurianti Laurianti commented Oct 4, 2026 •
edited
Loading

Copy link
Copy Markdown

Closes #2218

Picks up #1132 by @ali-Hamza817: his commits are kept as they are.

  • ChromaDB.Client 1.0.0 (v1 API only, removed in Chroma 1.x) replaced by ChromaDotNet.Client 2.10.2. Image chromadb/chroma:1.5.9, health check on /api/v2/heartbeat, connection string Endpoint=http://{host}:{port}.
  • [AspireExport] on the hosting API, ChromaResource in Aspire.Hosting.ApplicationModel, TypeScript AppHost example and test.
  • The example service gets its collection clients from the ChromaClient, so the workaround that rebuilt the endpoint is gone.
  • WithDataVolume and WithDataBindMount mount /data, where Chroma 1.x persists.
  • The client integration creates the ChromaClient with CreateChromaClient of ChromaDotNet.Client.DependencyInjection, so each request goes through the current handler of the HttpClient named after the connection, and cancels the health check at HealthCheckTimeout. Like the other client integrations, it reads its settings from Aspire:Chroma:Client and names the health checks Chroma and Chroma_{connectionName}.
  • Traces and metrics of the client, a span for each operation and db.client.operation.duration, with DisableTracing and DisableMetrics, and the conformance tests of the toolkit.
  • Like the client integrations of Aspire, the client integration is AOT compatible and binds its settings with the configuration binding generator, so trimmed and native AOT apps read them.
  • Chroma Cloud: the connection string also takes the token, the tenant and the database, Endpoint=https://api.trychroma.com;Token=...;Tenant=...;Database=..., and so do the settings. The token goes in the X-Chroma-Token header.
  • Package READMEs and the root README table.

The Chroma provider for Microsoft.Extensions.VectorData proposed in CommunityToolkit/AI#58 takes this ChromaClient from the container: builder.AddChromaClient("chroma"), then builder.Services.AddChromaVectorStore().

Tests: client 42, with the 2 configuration schema tests skipped as in the other integrations. Hosting 9 (unit, AppHost with a create/add/query round trip against Chroma 1.5.9, data persisted between runs on a volume and a bind mount, TypeScript AppHost). All pass locally, and a round trip through AddChromaClient on Chroma Cloud passed too.

PR Checklist

  • Created a feature/dev branch in your fork (vs. submitting directly from a commit on main)
  • Based off latest main branch of toolkit
  • PR doesn't include merge commits (always rebase on top of our main, if needed)
  • New integration
    • Docs are written
    • Added description of major feature to project description for NuGet package (4000 total character limit, so don't push entire description over that)
  • Tests for the changes have been added (for bug fixes / features) (if applicable)
  • Contains NO breaking changes
  • Every new API (including internal ones) has full XML docs
  • Code follows all style conventions

Other information

The docs page on aspire.dev follows once this is merged.

Co-authored-by: Ali 139616302+ali-Hamza817@users.noreply.github.com

Copilot AI balanced review requested due to automatic review settings October 4, 2026 14:47
Copilot AI reviewed Oct 4, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Persistence targets the wrong container directory, while client registration and health-check timeout handling have runtime gaps.

Review effort: Balanced
Findings: 1 High severity · 2 Medium severity

Open (3)
What changed in this PR

Adds ChromaDB hosting and client integrations, including Aspire resource modeling, dependency injection, persistence helpers, examples, and validation.

Changes:

  • Adds Chroma container and client packages.
  • Adds C# and TypeScript examples.
  • Adds unit, integration, and startup tests plus documentation.
File Description
tests/​CommunityToolkit.Aspire.Hosting.Chroma.Tests/​TypeScriptAppHostTests.cs Validates the TypeScript AppHost.
tests/​CommunityToolkit.Aspire.Hosting.Chroma.Tests/​CommunityToolkit.Aspire.Hosting.Chroma.Tests.csproj Configures hosting tests.
tests/​CommunityToolkit.Aspire.Hosting.Chroma.Tests/​AppHostTests.cs Tests health and collection operations.
tests/​CommunityToolkit.Aspire.Hosting.Chroma.Tests/​AddChromaTests.cs Tests resource annotations and mounts.
tests/​CommunityToolkit.Aspire.Chroma.Tests/​CommunityToolkit.Aspire.Chroma.Tests.csproj Configures client tests.
tests/​CommunityToolkit.Aspire.Chroma.Tests/​ChromaClientExtensionsTests.cs Tests client and health-check registration.
src/​CommunityToolkit.Aspire.Hosting.Chroma/​README.md Documents hosting usage and persistence.
src/​CommunityToolkit.Aspire.Hosting.Chroma/​CommunityToolkit.Aspire.Hosting.Chroma.csproj Defines the hosting package.
src/​CommunityToolkit.Aspire.Hosting.Chroma/​ChromaResource.cs Models the Chroma resource and connection properties.
src/​CommunityToolkit.Aspire.Hosting.Chroma/​ChromaContainerImageTags.cs Defines container image metadata.
src/​CommunityToolkit.Aspire.Hosting.Chroma/​ChromaBuilderExtensions.cs Adds hosting and persistence APIs.
src/​CommunityToolkit.Aspire.Chroma/​README.md Documents client registration and configuration.
src/​CommunityToolkit.Aspire.Chroma/​CommunityToolkit.Aspire.Chroma.csproj Defines the client package.
src/​CommunityToolkit.Aspire.Chroma/​ChromaHealthCheck.cs Implements heartbeat health checking.
src/​CommunityToolkit.Aspire.Chroma/​ChromaClientSettings.cs Defines and parses client settings.
src/​CommunityToolkit.Aspire.Chroma/​AspireChromaExtensions.cs Registers keyed and unkeyed clients.
README.md Lists both Chroma packages.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.ServiceDefaults/​Extensions.cs Adds shared Aspire service defaults.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.ServiceDefaults/​CommunityToolkit.Aspire.Hosting.Chroma.ServiceDefaults.csproj Configures service defaults.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost/​Program.cs Orchestrates Chroma and the API example.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost.csproj Configures the C# AppHost.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/​tsconfig.json Configures TypeScript compilation.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/​package.json Defines TypeScript tooling.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/​package-lock.json Locks TypeScript dependencies.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/​eslint.config.mjs Configures TypeScript linting.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/​aspire.config.json Maps the hosting package into Aspire.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/​apphost.mts Exercises exported hosting APIs.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.ApiService/​Properties/​launchSettings.json Defines local launch profiles.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.ApiService/​Program.cs Demonstrates create and query operations.
examples/​chromadb/​CommunityToolkit.Aspire.Hosting.Chroma.ApiService/​CommunityToolkit.Aspire.Hosting.Chroma.ApiService.csproj Configures the example API.
Directory.Packages.props Pins ChromaDotNet.Client.
CommunityToolkit.Aspire.slnx Adds source and test projects.
Files not reviewed (1)
  • examples/chromadb/CommunityToolkit.Aspire.Hosting.Chroma.AppHost.TypeScript/package-lock.json: Generated file

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread src/CommunityToolkit.Aspire.Chroma/AspireChromaExtensions.cs
Comment thread src/CommunityToolkit.Aspire.Chroma/ChromaHealthCheck.cs Outdated
Comment thread src/CommunityToolkit.Aspire.Hosting.Chroma/ChromaBuilderExtensions.cs Outdated
@Laurianti Laurianti mentioned this pull request Oct 4, 2026
Open
Laurianti added a commit to ChromaDotNet/ChromaDB.Aspire that referenced this pull request Oct 4, 2026
@Laurianti
Use ChromaDotNet.Client 2.6.0 and name the new configuration section
940a95c 
Directory.Packages.props and the README of ChromaDotNet.Aspire.Client are ours, so the sync does not change them: they follow CommunityToolkit/Aspire#2219.
This was referenced Oct 5, 2026
Merged
Merged
Merged
Merged
Merged
Open
Open
ali-Hamza817 and others added 8 commits October 7, 2026 02:02
@ali-Hamza817 @Laurianti
feat: add ChromaDB hosting and client integrations
1ebf0e9 
This contribution adds support for ChromaDB as a .NET Aspire resource, including:
- Hosting integration for containerized ChromaDB
- Client integration with health checks and keyed service support
- Persistence support via volumes and bind mounts
- Comprehensive unit tests and documentation
@ali-Hamza817 @Laurianti
Address ChromaDB integration feedback
fa806f7 
- Removed auto-generated api files.
- Refactored ChromaResource to use a primary constructor.
- Corrected style for null checks (is null).
- Added example app with CRUD operations in examples/chromadb.
- Added integration tests for health and CRUD verification.
- Updated tests.yml workflow to include new tests.
@ali-Hamza817 @Laurianti
Address Copilot feedback: fix grammar and rename test class
bbe8caf
@ali-Hamza817 @Laurianti
Fix CI test failures: use relative path for bind mount and add launch…
f8086d8 
…Settings.json for ApiService
@ali-Hamza817 @Laurianti
fix(chroma): resolve health check 404 and address review feedback
3296bf6
@ali-Hamza817 @Laurianti
fix(chroma): resolve health check 404 and address review feedback
d9d865e
@ali-Hamza817 @Laurianti
feat(chroma): fix health check and base URL construction for CI stabi…
69f7e5a 
…lity
@Laurianti @ali-Hamza817
Use ChromaDotNet.Client and the v2 API, and complete the integrations
c4eef24 
- ChromaDotNet.Client 2.10.2 in place of ChromaDB.Client 1.0.0, whose v1
  API Chroma 1.x removed: image chromadb/chroma:1.5.9, health check on
  /api/v2/heartbeat, connection string Endpoint=http://{host}:{port}.
- [AspireExport] on the hosting API, ChromaResource in
  Aspire.Hosting.ApplicationModel, TypeScript AppHost example and test.
- The example service gets its collection clients from the ChromaClient.
- WithDataVolume and WithDataBindMount mount /data, where Chroma 1.x
  persists.
- The client integration creates the ChromaClient with
  CreateChromaClient, cancels the health check at HealthCheckTimeout,
  reads its settings from Aspire:Chroma:Client and names the health
  checks Chroma and Chroma_{connectionName}.
- Traces and metrics of the client, with DisableTracing and
  DisableMetrics, and the conformance tests of the toolkit.
- AOT compatible, with the configuration binding generator.
- Chroma Cloud: Token, Tenant and Database in the connection string and
  in the settings.
- Package READMEs and the root README table.

Co-authored-by: Ali <139616302+ali-Hamza817@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add Chroma hosting and client integrations

3 participants

@Laurianti @ali-Hamza817