tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-chroma

Quarkus extension for integrating Chroma vector database as an embedding store with LangChain4j

Overview

Eval results

Files

Runtime Configuration

Name: tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-chroma
Author: tessl

The Quarkus LangChain4j Chroma extension is configured through application.properties using the quarkus.langchain4j.chroma prefix. All configuration is declarative and applied at runtime when the ChromaEmbeddingStore bean is created.

Capabilities

ChromaConfig Interface

The configuration interface defines all available settings for the Chroma connection. This interface is not directly used in application code but defines the available configuration properties.

package io.quarkiverse.langchain4j.chroma.runtime;

import java.time.Duration;
import java.util.Optional;
import dev.langchain4j.store.embedding.chroma.ChromaApiVersion;

/**
 * Runtime configuration for Chroma embedding store.
 * Configured via application.properties with prefix: quarkus.langchain4j.chroma
 */
interface ChromaConfig {
    /**
     * URL where the Chroma database is listening for requests.
     * Required property with no default value.
     *
     * @return The Chroma server URL
     */
    String url();

    /**
     * The collection name to use in Chroma.
     * Collections are separate namespaces for embeddings.
     *
     * @return The collection name (default: "default")
     */
    String collectionName();

    /**
     * The timeout duration for the Chroma client HTTP requests.
     *
     * @return The timeout duration (default: 5 seconds if not specified)
     */
    Optional<Duration> timeout();

    /**
     * Whether HTTP requests to Chroma should be logged.
     * Inherits from quarkus.langchain4j.log-requests if not explicitly set.
     *
     * @return True to log requests, false otherwise (default: false)
     */
    Optional<Boolean> logRequests();

    /**
     * Whether HTTP responses from Chroma should be logged.
     * Inherits from quarkus.langchain4j.log-requests if not explicitly set.
     *
     * @return True to log responses, false otherwise (default: false)
     */
    Optional<Boolean> logResponses();

    /**
     * The Chroma API version to use.
     * V1 is deprecated (Chroma 0.x) and support will be removed in the future.
     * V2 is for Chroma 1.x and is the recommended version.
     *
     * @return The API version (default: V2)
     */
    ChromaApiVersion apiVersion();
}

Required Configuration

The only required configuration property is the Chroma database URL.

# Required: URL of the Chroma database
quarkus.langchain4j.chroma.url=http://localhost:8000

Examples:

# Local development
quarkus.langchain4j.chroma.url=http://localhost:8000

# Remote server
quarkus.langchain4j.chroma.url=http://chroma.example.com:8000

# Using environment variable
quarkus.langchain4j.chroma.url=${CHROMA_URL:http://localhost:8000}

Collection Name

Specify which collection to use for storing embeddings. Collections provide namespace isolation within a single Chroma instance.

# Collection name (default: "default")
quarkus.langchain4j.chroma.collection-name=my-collection

Usage Examples:

# Different collections for different purposes
quarkus.langchain4j.chroma.collection-name=product-embeddings
quarkus.langchain4j.chroma.collection-name=user-documents
quarkus.langchain4j.chroma.collection-name=support-tickets

# Environment-specific collections
quarkus.langchain4j.chroma.collection-name=embeddings-${quarkus.profile}

Default Value: "default"

Timeout Configuration

Set the timeout duration for HTTP requests to the Chroma database.

# Timeout duration (default: 5s)
quarkus.langchain4j.chroma.timeout=10s

Supported Duration Formats:

Seconds: 5s, 10s, 30s
Milliseconds: 5000ms, 10000ms
Minutes: 1m, 2m
Mixed: 1m30s

Usage Examples:

# Short timeout for fast networks
quarkus.langchain4j.chroma.timeout=3s

# Long timeout for slow networks or large operations
quarkus.langchain4j.chroma.timeout=30s

# Very precise timeout
quarkus.langchain4j.chroma.timeout=2500ms

Default Value: Duration.ofSeconds(5) (5 seconds)

Request/Response Logging

Enable logging of HTTP requests and responses for debugging purposes.

# Log HTTP requests to Chroma (default: false)
quarkus.langchain4j.chroma.log-requests=true

# Log HTTP responses from Chroma (default: false)
quarkus.langchain4j.chroma.log-responses=true

Behavior:

Both properties inherit from quarkus.langchain4j.log-requests if not explicitly set
Logs are written at debug level
Request logging includes: HTTP method, URL, headers, body
Response logging includes: status code, headers, body

Usage Examples:

# Enable all LangChain4j request logging
quarkus.langchain4j.log-requests=true

# Override to disable Chroma-specific logging
quarkus.langchain4j.chroma.log-requests=false
quarkus.langchain4j.chroma.log-responses=false

# Enable only for development profile
%dev.quarkus.langchain4j.chroma.log-requests=true
%dev.quarkus.langchain4j.chroma.log-responses=true

Default Value: false (inherits from quarkus.langchain4j.log-requests)

API Version Selection

Choose between Chroma V1 (deprecated) and V2 API versions.

# API version: V1 or V2 (default: V2)
quarkus.langchain4j.chroma.api-version=V2

API Version Details:

// From LangChain4j
enum ChromaApiVersion {
    V1,  // Deprecated - for Chroma 0.x versions
    V2   // Current - for Chroma 1.x versions
}

Usage Guidance:

V2 (default, recommended): For Chroma 1.x servers
V1 (deprecated): For legacy Chroma 0.x servers only
- Support will be removed in future versions
- Migrate to Chroma 1.x and V2 API

Usage Examples:

# Use V2 (recommended, default)
quarkus.langchain4j.chroma.api-version=V2

# Use V1 for legacy Chroma 0.x servers
quarkus.langchain4j.chroma.api-version=V1

Default Value: V2

Complete Configuration Example

A comprehensive example showing all available configuration options:

# Required: Chroma server URL
quarkus.langchain4j.chroma.url=http://localhost:8000

# Optional: Collection name
quarkus.langchain4j.chroma.collection-name=my-embeddings

# Optional: Request timeout
quarkus.langchain4j.chroma.timeout=10s

# Optional: Enable request/response logging
quarkus.langchain4j.chroma.log-requests=true
quarkus.langchain4j.chroma.log-responses=true

# Optional: API version (V1 or V2)
quarkus.langchain4j.chroma.api-version=V2

Profile-Specific Configuration

Use Quarkus profiles to configure different settings for different environments:

# Development profile - local Chroma with logging
%dev.quarkus.langchain4j.chroma.url=http://localhost:8000
%dev.quarkus.langchain4j.chroma.collection-name=dev-embeddings
%dev.quarkus.langchain4j.chroma.log-requests=true
%dev.quarkus.langchain4j.chroma.log-responses=true
%dev.quarkus.langchain4j.chroma.timeout=30s

# Test profile - test container or shared test instance
%test.quarkus.langchain4j.chroma.url=http://localhost:8000
%test.quarkus.langchain4j.chroma.collection-name=test-embeddings

# Production profile - remote Chroma with shorter timeout
%prod.quarkus.langchain4j.chroma.url=${CHROMA_URL}
%prod.quarkus.langchain4j.chroma.collection-name=prod-embeddings
%prod.quarkus.langchain4j.chroma.timeout=5s
%prod.quarkus.langchain4j.chroma.log-requests=false
%prod.quarkus.langchain4j.chroma.log-responses=false

Environment Variables

Configuration properties can be overridden using environment variables following Quarkus conventions:

# Property: quarkus.langchain4j.chroma.url
# Environment variable: QUARKUS_LANGCHAIN4J_CHROMA_URL
export QUARKUS_LANGCHAIN4J_CHROMA_URL=http://chroma.production.com:8000

# Property: quarkus.langchain4j.chroma.collection-name
# Environment variable: QUARKUS_LANGCHAIN4J_CHROMA_COLLECTION_NAME
export QUARKUS_LANGCHAIN4J_CHROMA_COLLECTION_NAME=production-embeddings

# Property: quarkus.langchain4j.chroma.timeout
# Environment variable: QUARKUS_LANGCHAIN4J_CHROMA_TIMEOUT
export QUARKUS_LANGCHAIN4J_CHROMA_TIMEOUT=15s

# Property: quarkus.langchain4j.chroma.api-version
# Environment variable: QUARKUS_LANGCHAIN4J_CHROMA_API_VERSION
export QUARKUS_LANGCHAIN4J_CHROMA_API_VERSION=V2

Configuration Priority

Configuration values are resolved in the following order (highest to lowest priority):

System properties: -Dquarkus.langchain4j.chroma.url=...
Environment variables: QUARKUS_LANGCHAIN4J_CHROMA_URL=...
Profile-specific properties in application.properties: %prod.quarkus.langchain4j.chroma.url=...
Default properties in application.properties: quarkus.langchain4j.chroma.url=...
Extension defaults (only for optional properties)

Configuration Validation

The extension validates configuration at startup:

Missing URL: Application fails to start if quarkus.langchain4j.chroma.url is not configured (unless DevServices is active)
Invalid Duration: Invalid timeout formats cause startup failure
Invalid API Version: Only V1 and V2 are accepted values
Connection Issues: The extension does not validate connectivity at startup; connection errors occur at runtime when first accessing the embedding store

Default Values Summary

Property	Default Value	Required
`url`	None	Yes (unless DevServices is active)
`collection-name`	`"default"`	No
`timeout`	`5s` (5 seconds)	No
`log-requests`	`false` (inherits from `quarkus.langchain4j.log-requests`)	No
`log-responses`	`false` (inherits from `quarkus.langchain4j.log-requests`)	No
`api-version`	`V2`	No

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-chroma

docs

tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-chroma

configuration.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Runtime Configuration

Capabilities

ChromaConfig Interface

Required Configuration

Collection Name

Timeout Configuration

Request/Response Logging

API Version Selection

Complete Configuration Example

Profile-Specific Configuration

Environment Variables

Configuration Priority

Configuration Validation

Default Values Summary

configuration.mddocs/