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

Quarkus LangChain4j Chroma Extension

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

A Quarkus extension that provides seamless integration between Quarkus applications and the Chroma vector database through LangChain4j. This extension enables developers to build Retrieval-Augmented Generation (RAG) applications with persistent vector embeddings.

Package Information

Package Name: quarkus-langchain4j-chroma
Package Type: maven
Group ID: io.quarkiverse.langchain4j
Artifact ID: quarkus-langchain4j-chroma
Version: 1.7.4
Language: Java
Installation: Add the following dependency:

Maven:

<dependency>
    <groupId>io.quarkiverse.langchain4j</groupId>
    <artifactId>quarkus-langchain4j-chroma</artifactId>
    <version>1.7.4</version>
</dependency>

Gradle:

implementation 'io.quarkiverse.langchain4j:quarkus-langchain4j-chroma:1.7.4'

Core Imports

The extension automatically provides a configured CDI bean for injection:

import jakarta.inject.Inject;
import dev.langchain4j.store.embedding.chroma.ChromaEmbeddingStore;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.data.segment.TextSegment;

@ApplicationScoped
public class MyService {
    @Inject
    ChromaEmbeddingStore embeddingStore;

    // Or inject as the EmbeddingStore interface
    @Inject
    EmbeddingStore<TextSegment> embeddingStore;
}

Basic Usage

import jakarta.inject.Inject;
import jakarta.enterprise.context.ApplicationScoped;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.EmbeddingMatch;
import dev.langchain4j.store.embedding.EmbeddingSearchRequest;
import dev.langchain4j.store.embedding.EmbeddingSearchResult;
import java.util.List;

@ApplicationScoped
public class VectorSearchService {
    @Inject
    EmbeddingStore<TextSegment> embeddingStore;

    @Inject
    EmbeddingModel embeddingModel;

    public void addDocument(String text) {
        TextSegment segment = TextSegment.from(text);
        Embedding embedding = embeddingModel.embed(segment).content();
        embeddingStore.add(embedding, segment);
    }

    public List<EmbeddingMatch<TextSegment>> search(String query, int maxResults) {
        Embedding queryEmbedding = embeddingModel.embed(query).content();
        EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
            .queryEmbedding(queryEmbedding)
            .maxResults(maxResults)
            .build();
        EmbeddingSearchResult<TextSegment> result = embeddingStore.search(request);
        return result.matches();
    }
}

Configuration in application.properties:

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

# Optional configurations
quarkus.langchain4j.chroma.collection-name=my-collection
quarkus.langchain4j.chroma.timeout=10s
quarkus.langchain4j.chroma.api-version=V2

Architecture

The extension follows the standard Quarkus extension pattern with two modules:

Runtime Module: Contains the public API including ChromaConfig interface for configuration and ChromaRecorder for bean creation. The extension creates a synthetic CDI bean for ChromaEmbeddingStore that is automatically configured based on application properties.
Deployment Module: Handles build-time processing and DevServices support (automatic Chroma container management in dev/test mode). This module is not part of the runtime API and only executes during the build phase.

The extension wraps the LangChain4j ChromaEmbeddingStore class and integrates it with Quarkus features including:

Declarative configuration via SmallRye Config
CDI dependency injection with Arc
REST client integration with Jackson serialization
Native compilation support via GraalVM
Automatic dev services with TestContainers

Capabilities

ChromaEmbeddingStore Bean

The extension automatically creates and configures a CDI bean for interacting with the Chroma vector database. The bean is injectable as ChromaEmbeddingStore or as the EmbeddingStore<TextSegment> interface from LangChain4j.

@Inject
ChromaEmbeddingStore embeddingStore;

// Available bean types:
// - dev.langchain4j.store.embedding.chroma.ChromaEmbeddingStore
// - dev.langchain4j.store.embedding.EmbeddingStore
// - dev.langchain4j.store.embedding.EmbeddingStore<TextSegment>

Bean Scope: @ApplicationScoped

Key Methods (from LangChain4j EmbeddingStore<TextSegment> interface):

// Add a single embedding
String add(Embedding embedding);

// Add embedding with specific ID
void add(String id, Embedding embedding);

// Add embedding with associated text segment
String add(Embedding embedding, TextSegment textSegment);

// Add multiple embeddings
List<String> addAll(List<Embedding> embeddings);

// Add multiple embeddings with IDs
void addAll(List<String> ids, List<Embedding> embeddings);

// Add multiple embeddings with text segments
List<String> addAll(List<Embedding> embeddings, List<TextSegment> textSegments);

// Search for similar embeddings
EmbeddingSearchResult<TextSegment> search(EmbeddingSearchRequest request);

// Remove all embeddings
void removeAll();

// Remove embeddings by IDs
void removeAll(Collection<String> ids);

ChromaEmbeddingStore Details

Runtime Configuration

Configuration interface for connecting to and customizing the Chroma database connection. All properties are configured via application.properties using the quarkus.langchain4j.chroma prefix.

// Configuration interface (read-only, configured via application.properties)
interface ChromaConfig {
    String url();                        // Required: Chroma database URL
    String collectionName();             // Optional: Collection name (default: "default")
    Optional<Duration> timeout();        // Optional: Client timeout (default: 5 seconds)
    Optional<Boolean> logRequests();     // Optional: Log HTTP requests (default: false)
    Optional<Boolean> logResponses();    // Optional: Log HTTP responses (default: false)
    ChromaApiVersion apiVersion();       // Optional: API version (default: V2)
}

Configuration Details

DevServices

Automatic container management for development and testing. When DevServices is enabled (default), the extension automatically starts a Chroma container using TestContainers when running in dev or test mode and Docker is available.

# DevServices configuration properties
quarkus.langchain4j.chroma.devservices.enabled=true
quarkus.langchain4j.chroma.devservices.image-name=ghcr.io/chroma-core/chroma:1.3.0
quarkus.langchain4j.chroma.devservices.port=8000
quarkus.langchain4j.chroma.devservices.shared=true
quarkus.langchain4j.chroma.devservices.service-name=chroma
quarkus.langchain4j.chroma.devservices.container-env.KEY=VALUE

DevServices Details

Install with Tessl CLI

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

docs