CtrlK
BlogDocsLog inGet started
Tessl Logo

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

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.quarkiverse.langchain4j/quarkus-langchain4j-chroma@1.7.x