Repository navigation
feat: add ChromaDB hosting and client integrations #1132
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closed
ali-Hamza817
wants to merge
7
commits into
CommunityToolkit:main
from
ali-Hamza817:feature/chromadb-integration
+964
−0
Closed
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
c9bac74
feat: add ChromaDB hosting and client integrations
ali-Hamza817 9800960
Address ChromaDB integration feedback
ali-Hamza817 12273b2
Address Copilot feedback: fix grammar and rename test class
ali-Hamza817 1470e00
Fix CI test failures: use relative path for bind mount and add launch…
ali-Hamza817 d596477
fix(chroma): resolve health check 404 and address review feedback
ali-Hamza817 0e284dd
fix(chroma): resolve health check 404 and address review feedback
ali-Hamza817 05a7cd2
feat(chroma): fix health check and base URL construction for CI stabi…
ali-Hamza817 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next
Next commit
feat: add ChromaDB hosting and client integrations
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
- Loading branch information
commit c9bac74d26716af8e4de6890667399043446fc21
There are no files selected for viewing
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
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
91 changes: 91 additions & 0 deletions
91
src/CommunityToolkit.Aspire.Chroma/AspireChromaExtensions.cs
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| using System.Net.Http; | ||
| using ChromaDB.Client; | ||
| using CommunityToolkit.Aspire.Chroma; | ||
| using Microsoft.Extensions.Configuration; | ||
| using Microsoft.Extensions.DependencyInjection; | ||
| using Microsoft.Extensions.Diagnostics.HealthChecks; | ||
|
|
||
| namespace Microsoft.Extensions.Hosting; | ||
|
|
||
| /// <summary> | ||
| /// Provides extension methods for registering ChromaDB-related services. | ||
| /// </summary> | ||
| public static class AspireChromaExtensions | ||
| { | ||
| private const string DefaultConfigSectionName = "Aspire:Chroma"; | ||
|
|
||
| /// <summary> | ||
| /// Registers <see cref="ChromaClient"/> as a singleton in the services collection. | ||
| /// </summary> | ||
| public static void AddChromaClient( | ||
| this IHostApplicationBuilder builder, | ||
| string connectionName, | ||
| Action<ChromaClientSettings>? configureSettings = null) | ||
| { | ||
| AddChromaClient(builder, serviceKey: null, connectionName, configureSettings); | ||
| } | ||
|
|
||
| /// <summary> | ||
| /// Registers <see cref="ChromaClient"/> as a keyed singleton in the services collection. | ||
| /// </summary> | ||
| public static void AddKeyedChromaClient( | ||
| this IHostApplicationBuilder builder, | ||
| string name, | ||
| Action<ChromaClientSettings>? configureSettings = null) | ||
| { | ||
| AddChromaClient(builder, serviceKey: name, connectionName: name, configureSettings); | ||
| } | ||
|
|
||
| private static void AddChromaClient( | ||
| IHostApplicationBuilder builder, | ||
| object? serviceKey, | ||
| string connectionName, | ||
| Action<ChromaClientSettings>? configureSettings = null) | ||
| { | ||
| ArgumentNullException.ThrowIfNull(builder); | ||
| ArgumentNullException.ThrowIfNull(connectionName); | ||
|
|
||
| var settings = new ChromaClientSettings(); | ||
| builder.Configuration.GetSection(DefaultConfigSectionName).Bind(settings); | ||
|
|
||
| if (builder.Configuration.GetConnectionString(connectionName) is string connectionString) | ||
| { | ||
| settings.ParseConnectionString(connectionString); | ||
| } | ||
|
|
||
| configureSettings?.Invoke(settings); | ||
|
|
||
| if (serviceKey is null) | ||
| { | ||
| builder.Services.AddSingleton<ChromaClient>(sp => CreateClient(sp, settings, connectionName)); | ||
| } | ||
| else | ||
| { | ||
| builder.Services.AddKeyedSingleton<ChromaClient>(serviceKey, (sp, key) => CreateClient(sp, settings, connectionName)); | ||
| } | ||
|
|
||
| if (!settings.DisableHealthChecks) | ||
| { | ||
| builder.Services.AddHealthChecks() | ||
| .Add(new HealthCheckRegistration( | ||
| serviceKey is null ? connectionName : $"{connectionName}_check", | ||
| sp => new ChromaHealthCheck(serviceKey is null | ||
| ? sp.GetRequiredService<ChromaClient>() | ||
| : sp.GetRequiredKeyedService<ChromaClient>(serviceKey)), | ||
| failureStatus: default, | ||
| tags: default, | ||
| timeout: settings.HealthCheckTimeout.HasValue ? TimeSpan.FromMilliseconds(settings.HealthCheckTimeout.Value) : default)); | ||
| } | ||
| } | ||
|
|
||
| private static ChromaClient CreateClient(IServiceProvider sp, ChromaClientSettings settings, string connectionName) | ||
| { | ||
| if (settings.Endpoint == null) | ||
| { | ||
| throw new InvalidOperationException($"ChromaDB endpoint is not configured for connection name '{connectionName}'."); | ||
| } | ||
|
|
||
| var httpClient = sp.GetRequiredService<IHttpClientFactory>().CreateClient(connectionName); | ||
| return new ChromaClient(new ChromaConfigurationOptions(settings.Endpoint.ToString()), httpClient); | ||
| } | ||
| } | ||
49 changes: 49 additions & 0 deletions
49
src/CommunityToolkit.Aspire.Chroma/ChromaClientSettings.cs
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
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,49 @@ | ||||||
| using System.Data.Common; | ||||||
|
|
||||||
| namespace CommunityToolkit.Aspire.Chroma; | ||||||
|
|
||||||
| /// <summary> | ||||||
| /// Provides the client configuration settings for connecting to a ChromaDB server using ChromaClient. | ||||||
| /// </summary> | ||||||
| public sealed class ChromaClientSettings | ||||||
| { | ||||||
| private const string ConnectionStringEndpoint = "Endpoint"; | ||||||
|
|
||||||
| /// <summary> | ||||||
| /// The endpoint URI string of the ChromaDB server to connect to. | ||||||
| /// </summary> | ||||||
| public Uri? Endpoint { get; set; } | ||||||
|
|
||||||
| /// <summary> | ||||||
| /// Gets or sets a boolean value that indicates whether the ChromaDB health check is disabled or not. | ||||||
| /// </summary> | ||||||
| /// <value> | ||||||
| /// The default value is <see langword="false"/>. | ||||||
| /// </value> | ||||||
| public bool DisableHealthChecks { get; set; } | ||||||
|
|
||||||
| /// <summary> | ||||||
| /// Gets or sets a integer value that indicates the ChromaDB health check timeout in milliseconds. | ||||||
|
||||||
| /// Gets or sets a integer value that indicates the ChromaDB health check timeout in milliseconds. | |
| /// Gets or sets an integer value that indicates the ChromaDB health check timeout in milliseconds. |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| using ChromaDB.Client; | ||
| using Microsoft.Extensions.Diagnostics.HealthChecks; | ||
|
|
||
| namespace CommunityToolkit.Aspire.Chroma; | ||
|
|
||
| internal sealed class ChromaHealthCheck(ChromaClient chromaClient) : IHealthCheck | ||
| { | ||
| /// <inheritdoc /> | ||
| public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context, CancellationToken cancellationToken = default) | ||
| { | ||
| try | ||
| { | ||
| await chromaClient.GetVersion().ConfigureAwait(false); | ||
|
|
||
| return HealthCheckResult.Healthy(); | ||
| } | ||
| catch (Exception ex) | ||
| { | ||
| return new HealthCheckResult(context.Registration.FailureStatus, exception: ex); | ||
| } | ||
| } | ||
| } |
21 changes: 21 additions & 0 deletions
21
src/CommunityToolkit.Aspire.Chroma/CommunityToolkit.Aspire.Chroma.csproj
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| <Project Sdk="Microsoft.NET.Sdk"> | ||
|
|
||
| <PropertyGroup> | ||
| <AdditionalPackageTags>ChromaDB client</AdditionalPackageTags> | ||
| <Description>A ChromaDB client that integrates with Aspire, including health checks, logging, and telemetry.</Description> | ||
| </PropertyGroup> | ||
|
|
||
| <ItemGroup> | ||
| <PackageReference Include="ChromaDB.Client" /> | ||
| <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" /> | ||
| <PackageReference Include="Microsoft.Extensions.Hosting.Abstractions" /> | ||
| <PackageReference Include="Microsoft.Extensions.Configuration.Binder" /> | ||
| <PackageReference Include="Microsoft.Extensions.Http" /> | ||
| <PackageReference Include="OpenTelemetry.Extensions.Hosting" /> | ||
| </ItemGroup> | ||
|
|
||
| <ItemGroup> | ||
| <Compile Include="$(SharedDir)\HealthChecksExtensions.cs" Link="Utils\HealthChecksExtensions.cs" /> | ||
| </ItemGroup> | ||
|
|
||
| </Project> |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # CommunityToolkit.Aspire.Chroma | ||
|
|
||
| Provides extension methods for registering a `ChromaClient` in a .NET application. | ||
|
|
||
| ## Installation | ||
|
|
||
| ```bash | ||
| dotnet add package CommunityToolkit.Aspire.Chroma | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| In your application project: | ||
|
|
||
| ```csharp | ||
| var builder = Host.CreateApplicationBuilder(args); | ||
|
|
||
| builder.AddChromaClient("chroma"); | ||
|
|
||
| // Or using keyed service | ||
| builder.AddKeyedChromaClient("chroma"); | ||
| ``` | ||
|
|
||
| Then resolve the client in your services: | ||
|
|
||
| ```csharp | ||
| public class MyService(ChromaClient chromaClient) | ||
| { | ||
| public async Task QueryAsync() | ||
| { | ||
| var version = await chromaClient.GetVersion(); | ||
| // ... | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Configuration | ||
|
|
||
| The client can be configured using connection strings or settings: | ||
|
|
||
| ```json | ||
| { | ||
| "ConnectionStrings": { | ||
| "chroma": "http://localhost:8000" | ||
| }, | ||
| "Aspire": { | ||
| "Chroma": { | ||
| "DisableHealthChecks": false, | ||
| "HealthCheckTimeout": 5000 | ||
| } | ||
| } | ||
| } | ||
| ``` |
21 changes: 21 additions & 0 deletions
21
src/CommunityToolkit.Aspire.Chroma/api/CommunityToolkit.Aspire.Chroma.cs
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This file is auto-generated on merging to main, so it should be removed. |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| namespace CommunityToolkit.Aspire.Chroma | ||
| { | ||
| public sealed partial class ChromaClientSettings | ||
| { | ||
| public bool DisableHealthChecks { get { throw null; } set { } } | ||
|
|
||
| public System.Uri? Endpoint { get { throw null; } set { } } | ||
|
|
||
| public int? HealthCheckTimeout { get { throw null; } set { } } | ||
| } | ||
| } | ||
|
|
||
| namespace Microsoft.Extensions.Hosting | ||
| { | ||
| public static partial class AspireChromaExtensions | ||
| { | ||
| public static void AddChromaClient(this IHostApplicationBuilder builder, string connectionName, System.Action<CommunityToolkit.Aspire.Chroma.ChromaClientSettings>? configureSettings = null) { } | ||
|
|
||
| public static void AddKeyedChromaClient(this IHostApplicationBuilder builder, string name, System.Action<CommunityToolkit.Aspire.Chroma.ChromaClientSettings>? configureSettings = null) { } | ||
| } | ||
| } |
63 changes: 63 additions & 0 deletions
63
src/CommunityToolkit.Aspire.Hosting.Chroma/ChromaBuilderExtensions.cs
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| using Aspire.Hosting.ApplicationModel; | ||
| using CommunityToolkit.Aspire.Hosting.Chroma; | ||
|
|
||
| namespace Aspire.Hosting; | ||
|
|
||
| /// <summary> | ||
| /// Provides extension methods for adding ChromaDB resources to the application model. | ||
| /// </summary> | ||
| public static class ChromaBuilderExtensions | ||
| { | ||
| private const int ChromaPort = 8000; | ||
|
|
||
| /// <summary> | ||
| /// Adds a ChromaDB container resource to the application model. | ||
| /// The default image is <inheritdoc cref="ChromaContainerImageTags.Image"/> and the tag is <inheritdoc cref="ChromaContainerImageTags.Tag"/>. | ||
| /// </summary> | ||
| /// <param name="builder">The <see cref="IDistributedApplicationBuilder"/>.</param> | ||
| /// <param name="name">The name of the resource. This name will be used as the connection string name when referenced in a dependency.</param> | ||
| /// <param name="port">The host port to bind the underlying container to.</param> | ||
| /// <returns>A reference to the <see cref="IResourceBuilder{T}"/>.</returns> | ||
| public static IResourceBuilder<ChromaResource> AddChroma( | ||
| this IDistributedApplicationBuilder builder, | ||
| string name, | ||
| int? port = null) | ||
| { | ||
| ArgumentNullException.ThrowIfNull(builder); | ||
| ArgumentNullException.ThrowIfNull(name); | ||
|
|
||
| var chroma = new ChromaResource(name); | ||
|
|
||
| return builder.AddResource(chroma) | ||
| .WithImage(ChromaContainerImageTags.Image, ChromaContainerImageTags.Tag) | ||
| .WithImageRegistry(ChromaContainerImageTags.Registry) | ||
| .WithHttpEndpoint(targetPort: ChromaPort, port: port, name: ChromaResource.PrimaryEndpointName); | ||
| } | ||
|
|
||
| /// <summary> | ||
| /// Adds a named volume for the data folder to a ChromaDB container resource. | ||
| /// </summary> | ||
| /// <param name="builder">The resource builder.</param> | ||
| /// <param name="name">The name of the volume. Defaults to an auto-generated name based on the application and resource names.</param> | ||
| /// <returns>The <see cref="IResourceBuilder{T}"/>.</returns> | ||
| public static IResourceBuilder<ChromaResource> WithDataVolume(this IResourceBuilder<ChromaResource> builder, string? name = null) | ||
| { | ||
| ArgumentNullException.ThrowIfNull(builder); | ||
|
|
||
| return builder.WithVolume(name ?? VolumeNameGenerator.Generate(builder, "data"), "/chroma/chroma"); | ||
| } | ||
|
|
||
| /// <summary> | ||
| /// Adds a bind mount for the data folder to a ChromaDB container resource. | ||
| /// </summary> | ||
| /// <param name="builder">The resource builder.</param> | ||
| /// <param name="source">The source directory on the host to mount into the container.</param> | ||
| /// <returns>The <see cref="IResourceBuilder{T}"/>.</returns> | ||
| public static IResourceBuilder<ChromaResource> WithDataBindMount(this IResourceBuilder<ChromaResource> builder, string source) | ||
| { | ||
| ArgumentNullException.ThrowIfNull(builder); | ||
| ArgumentNullException.ThrowIfNull(source); | ||
|
|
||
| return builder.WithBindMount(source, "/chroma/chroma"); | ||
| } | ||
| } |
13 changes: 13 additions & 0 deletions
13
src/CommunityToolkit.Aspire.Hosting.Chroma/ChromaContainerImageTags.cs
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| namespace CommunityToolkit.Aspire.Hosting.Chroma; | ||
|
|
||
| internal static class ChromaContainerImageTags | ||
| { | ||
| /// <summary>docker.io</summary> | ||
| public const string Registry = "docker.io"; | ||
|
|
||
| /// <summary>chromadb/chroma</summary> | ||
| public const string Image = "chromadb/chroma"; | ||
|
|
||
| /// <summary>0.5.0</summary> | ||
| public const string Tag = "0.5.0"; | ||
| } |
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.