CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-core-deployment

Quarkus deployment extension for LangChain4j integration providing build-time processing, BuildItem APIs, and configuration for integrating Large Language Models into Quarkus applications

Overview
Eval results
Files

build-items.mddocs/

BuildItems API Reference

BuildItems are data carriers used in Quarkus build step chains. They are the primary API mechanism for communication between extensions during the build process.

BuildItem Types

MultiBuildItem vs SimpleBuildItem

  • MultiBuildItem: Multiple instances can be produced during the build. Used when multiple extensions may contribute the same type of information (e.g., multiple model providers).

  • SimpleBuildItem: Only one instance exists during the build. Used for consolidated metadata or singleton configuration.

How to Use BuildItems

Producing BuildItems

Use BuildProducer<T> in a @BuildStep method:

@BuildStep
void produceBuildItem(BuildProducer<MyBuildItem> producer) {
    producer.produce(new MyBuildItem(...));
}

Consuming BuildItems

Accept BuildItem as a method parameter:

// Consume a SimpleBuildItem
@BuildStep
void consumeSingle(MySimpleBuildItem item) {
    // Use the single item
}

// Consume all instances of a MultiBuildItem
@BuildStep
void consumeMultiple(List<MyMultiBuildItem> items) {
    for (MyMultiBuildItem item : items) {
        // Process each item
    }
}

MultiBuildItem Classes

Model Provider Registration

These BuildItems allow extensions to register themselves as model providers.

ChatModelProviderCandidateBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Registers an extension as a candidate chat model provider.

public final class ChatModelProviderCandidateBuildItem
        extends MultiBuildItem
        implements ProviderHolder {

    public ChatModelProviderCandidateBuildItem(String provider);

    public String getProvider();
}

Usage:

@BuildStep
void registerChatProvider(BuildProducer<ChatModelProviderCandidateBuildItem> producer) {
    producer.produce(new ChatModelProviderCandidateBuildItem("openai"));
}

EmbeddingModelProviderCandidateBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Registers an extension as a candidate embedding model provider.

public final class EmbeddingModelProviderCandidateBuildItem
        extends MultiBuildItem
        implements ProviderHolder {

    public EmbeddingModelProviderCandidateBuildItem(String provider);

    public String getProvider();
}

Usage:

@BuildStep
void registerEmbeddingProvider(
        BuildProducer<EmbeddingModelProviderCandidateBuildItem> producer) {
    producer.produce(new EmbeddingModelProviderCandidateBuildItem("openai"));
}

ImageModelProviderCandidateBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Registers an extension as a candidate image model provider.

public final class ImageModelProviderCandidateBuildItem
        extends MultiBuildItem
        implements ProviderHolder {

    public ImageModelProviderCandidateBuildItem(String provider);

    public String getProvider();
}

ModerationModelProviderCandidateBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Registers an extension as a candidate moderation model provider.

public final class ModerationModelProviderCandidateBuildItem
        extends MultiBuildItem
        implements ProviderHolder {

    public ModerationModelProviderCandidateBuildItem(String provider);

    public String getProvider();
}

ScoringModelProviderCandidateBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Registers an extension as a candidate scoring/rerank model provider.

public final class ScoringModelProviderCandidateBuildItem
        extends MultiBuildItem
        implements ProviderHolder {

    public ScoringModelProviderCandidateBuildItem(String provider);

    public String getProvider();
}

Model Provider Selection

These BuildItems indicate which providers were selected after configuration resolution.

SelectedChatModelProviderBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Indicates a chat model provider was selected for a specific configuration.

public final class SelectedChatModelProviderBuildItem extends MultiBuildItem {

    public SelectedChatModelProviderBuildItem(String provider, String configName);

    public String getProvider();
    public String getConfigName();
}

Usage:

@BuildStep
void reactToSelection(List<SelectedChatModelProviderBuildItem> selected) {
    for (SelectedChatModelProviderBuildItem item : selected) {
        if ("my-provider".equals(item.getProvider())) {
            String configName = item.getConfigName();
            // Create beans for this configuration
        }
    }
}

SelectedEmbeddingModelCandidateBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Indicates an embedding model provider was selected.

public final class SelectedEmbeddingModelCandidateBuildItem extends MultiBuildItem {

    public SelectedEmbeddingModelCandidateBuildItem(String provider, String configName);

    public String getProvider();
    public String getConfigName();
}

SelectedImageModelProviderBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Indicates an image model provider was selected.

public final class SelectedImageModelProviderBuildItem extends MultiBuildItem {

    public SelectedImageModelProviderBuildItem(String provider, String configName);

    public String getProvider();
    public String getConfigName();
}

SelectedModerationModelProviderBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Indicates a moderation model provider was selected.

public final class SelectedModerationModelProviderBuildItem extends MultiBuildItem {

    public SelectedModerationModelProviderBuildItem(String provider, String configName);

    public String getProvider();
    public String getConfigName();
}

SelectedScoringModelProviderBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Indicates a scoring model provider was selected.

public final class SelectedScoringModelProviderBuildItem extends MultiBuildItem {

    public SelectedScoringModelProviderBuildItem(String provider, String configName);

    public String getProvider();
    public String getConfigName();
}

AI Service Configuration

DeclarativeAiServiceBuildItem

Package: io.quarkiverse.langchain4j.deployment

Comprehensive metadata from @RegisterAiService annotation usages. This BuildItem contains all configuration for a declarative AI service.

public final class DeclarativeAiServiceBuildItem extends MultiBuildItem {

    public DeclarativeAiServiceBuildItem(
        ClassInfo serviceClassInfo,
        DotName chatLanguageModelSupplierClassDotName,
        DotName streamingChatLanguageModelSupplierClassDotName,
        List<ClassInfo> toolClassInfos,
        DotName chatMemoryProviderSupplierClassDotName,
        DotName retrievalAugmentorSupplierClassDotName,
        boolean customRetrievalAugmentorSupplierClassIsABean,
        DotName moderationModelSupplierDotName,
        DotName imageModelSupplierDotName,
        DotName chatMemorySeederClassDotName,
        DotName systemMessageProviderClassDotName,
        DotName cdiScope,
        String chatModelName,
        String moderationModelName,
        String imageModelName,
        DotName toolProviderClassDotName,
        Optional<String> beanName,
        DotName toolHallucinationStrategyClassDotName,
        DeclarativeAiServiceInputGuardrails inputGuardrails,
        DeclarativeAiServiceOutputGuardrails outputGuardrails,
        DotName toolArgumentsErrorHandlerDotName,
        DotName toolExecutionErrorHandlerDotName,
        Integer maxSequentialToolInvocations,
        boolean allowContinuousForcedToolCalling,
        boolean makeDefaultBean);

    // Service information
    public ClassInfo getServiceClassInfo();
    public Optional<String> getBeanName();
    public DotName getCdiScope();
    public boolean isMakeDefaultBean();

    // Model configuration
    public DotName getChatLanguageModelSupplierClassDotName();
    public DotName getStreamingChatLanguageModelSupplierClassDotName();
    public String getChatModelName();
    public DotName getModerationModelSupplierDotName();
    public String getModerationModelName();
    public DotName getImageModelSupplierDotName();
    public String getImageModelName();

    // Tools configuration
    public List<ClassInfo> getToolClassInfos();
    public DotName getToolProviderClassDotName();
    public DotName getToolHallucinationStrategyClassDotName();
    public DotName getToolArgumentsErrorHandlerDotName();
    public DotName getToolExecutionErrorHandlerDotName();
    public Integer getMaxSequentialToolInvocations();
    public boolean isAllowContinuousForcedToolCalling();

    // Memory configuration
    public DotName getChatMemoryProviderSupplierClassDotName();
    public DotName getChatMemorySeederClassDotName();

    // RAG configuration
    public DotName getRetrievalAugmentorSupplierClassDotName();
    public boolean isCustomRetrievalAugmentorSupplierClassIsABean();

    // System message
    public DotName getSystemMessageProviderClassDotName();

    // Guardrails
    public DeclarativeAiServiceInputGuardrails getInputGuardrails();
    public DeclarativeAiServiceOutputGuardrails getOutputGuardrails();

    // Nested records
    public record DeclarativeAiServiceInputGuardrails(
            List<ClassInfo> inputGuardrailClassInfos) {
        public List<String> asClassNames();
    }

    public record DeclarativeAiServiceOutputGuardrails(
            List<ClassInfo> outputGuardrailClassInfos,
            int maxRetries,
            int actualMaxRetries) {
        public DeclarativeAiServiceOutputGuardrails(
                List<ClassInfo> outputGuardrailClassInfos,
                int maxRetries);
        public List<String> asClassNames();
    }
}

Usage:

@BuildStep
void processAiServices(List<DeclarativeAiServiceBuildItem> aiServices) {
    for (DeclarativeAiServiceBuildItem service : aiServices) {
        String serviceName = service.getServiceClassInfo().name().toString();
        String chatModel = service.getChatModelName();
        List<ClassInfo> tools = service.getToolClassInfos();

        // Process AI service configuration
    }
}

AiServicesMethodBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Represents a method from an AI service interface with full metadata including guardrails and response augmentation.

public final class AiServicesMethodBuildItem extends MultiBuildItem {

    public AiServicesMethodBuildItem(
        MethodInfo methodInfo,
        InputGuardrailsLiteral inputGuardrails,
        OutputGuardrailsLiteral outputGuardrails,
        String responseAugmenter,
        AiServiceMethodCreateInfo methodCreateInfo);

    public MethodInfo getMethodInfo();
    public Optional<InputGuardrailsLiteral> getInputGuardrails();
    public Optional<OutputGuardrailsLiteral> getOutputGuardrails();
    public boolean hasInputGuardrails();
    public boolean hasOutputGuardrails();
    public AiServiceMethodCreateInfo getMethodCreateInfo();
    public String getResponseAugmenter();

    // Static utility methods
    public static List<String> gatherGuardrails(
        MethodInfo methodInfo,
        DotName annotation);

    public static String gatherAccumulator(MethodInfo methodInfo);

    public static String gatherResponseAugmenter(MethodInfo methodInfo);
}

Tool Discovery and Metadata

ToolMethodBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Represents a method annotated with @Tool.

public final class ToolMethodBuildItem extends MultiBuildItem {

    public ToolMethodBuildItem(
        MethodInfo toolsMethodInfo,
        ToolMethodCreateInfo toolMethodCreateInfo);

    public MethodInfo getToolsMethodInfo();
    public String getDeclaringClassName();
    public ToolMethodCreateInfo getToolMethodCreateInfo();
    public boolean requiresSwitchToWorkerThread();
}

Usage:

@BuildStep
void processTools(List<ToolMethodBuildItem> tools) {
    for (ToolMethodBuildItem tool : tools) {
        MethodInfo method = tool.getToolsMethodInfo();
        String className = tool.getDeclaringClassName();
        boolean needsWorkerThread = tool.requiresSwitchToWorkerThread();

        // Process tool configuration
    }
}

Model Bean Requests

These BuildItems allow extensions to request bean creation even without injection points.

RequestChatModelBeanBuildItem

Package: io.quarkiverse.langchain4j.deployment

Requests creation of a ChatLanguageModel bean even if no injection point exists.

public final class RequestChatModelBeanBuildItem extends MultiBuildItem {

    public RequestChatModelBeanBuildItem(String configName);

    public String getConfigName();
}

Usage:

@BuildStep
void requestChatModel(BuildProducer<RequestChatModelBeanBuildItem> producer) {
    // Request default chat model bean
    producer.produce(new RequestChatModelBeanBuildItem("default"));

    // Request named chat model bean
    producer.produce(new RequestChatModelBeanBuildItem("my-model"));
}

RequestImageModelBeanBuildItem

Package: io.quarkiverse.langchain4j.deployment

Requests creation of an ImageModel bean even if no injection point exists.

public final class RequestImageModelBeanBuildItem extends MultiBuildItem {

    public RequestImageModelBeanBuildItem(String configName);

    public String getConfigName();
}

RequestModerationModelBeanBuildItem

Package: io.quarkiverse.langchain4j.deployment

Requests creation of a ModerationModel bean even if no injection point exists.

public final class RequestModerationModelBeanBuildItem extends MultiBuildItem {

    public RequestModerationModelBeanBuildItem(String configName);

    public String getConfigName();
}

Behavior Customization

AnnotationsImpliesAiServiceBuildItem

Package: io.quarkiverse.langchain4j.deployment

Makes interfaces automatically become AI services when annotated with specific annotations.

public final class AnnotationsImpliesAiServiceBuildItem extends MultiBuildItem {

    public AnnotationsImpliesAiServiceBuildItem(List<DotName> annotationNames);

    public List<DotName> getAnnotationNames();
}

Usage:

@BuildStep
void customAiServiceAnnotation(
        BuildProducer<AnnotationsImpliesAiServiceBuildItem> producer) {

    List<DotName> annotations = List.of(
        DotName.createSimple("com.example.MyAiService")
    );
    producer.produce(new AnnotationsImpliesAiServiceBuildItem(annotations));
}

SkipOutputFormatInstructionsBuildItem

Package: io.quarkiverse.langchain4j.deployment

Indicates when AI service methods should not have output format instructions added.

public final class SkipOutputFormatInstructionsBuildItem extends MultiBuildItem {

    public SkipOutputFormatInstructionsBuildItem(Predicate<MethodInfo> predicate);

    public Predicate<MethodInfo> getPredicate();
}

Usage:

@BuildStep
void skipFormatting(BuildProducer<SkipOutputFormatInstructionsBuildItem> producer) {
    producer.produce(new SkipOutputFormatInstructionsBuildItem(
        method -> method.hasAnnotation(DotName.createSimple("com.example.NoFormat"))
    ));
}

FallbackToDummyUserMessageBuildItem

Package: io.quarkiverse.langchain4j.deployment

Indicates a dummy user message should be created if processing would otherwise fail.

public final class FallbackToDummyUserMessageBuildItem extends MultiBuildItem {

    public FallbackToDummyUserMessageBuildItem(Predicate<MethodInfo> predicate);

    public Predicate<MethodInfo> getPredicate();
}

PreventToolValidationErrorBuildItem

Package: io.quarkiverse.langchain4j.deployment

Prevents default validation exception for invalid AI service methods.

public final class PreventToolValidationErrorBuildItem extends MultiBuildItem {

    public PreventToolValidationErrorBuildItem(Predicate<MethodInfo> predicate);

    public Predicate<MethodInfo> getPredicate();
}

Method Parameter Handling

MethodParameterAllowedAnnotationsBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Forces AI service method parameters to be part of the prompt template.

public final class MethodParameterAllowedAnnotationsBuildItem extends MultiBuildItem {

    public MethodParameterAllowedAnnotationsBuildItem(
        Predicate<AnnotationInstance> predicate);

    public Predicate<AnnotationInstance> getPredicate();
}

Usage:

@BuildStep
void allowCustomAnnotations(
        BuildProducer<MethodParameterAllowedAnnotationsBuildItem> producer) {

    DotName myAnnotation = DotName.createSimple("com.example.TemplateVar");
    producer.produce(new MethodParameterAllowedAnnotationsBuildItem(
        annotation -> annotation.name().equals(myAnnotation)
    ));
}

MethodParameterIgnoredAnnotationsBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Ignores parameters when determining template variable inclusion.

public final class MethodParameterIgnoredAnnotationsBuildItem extends MultiBuildItem {

    public MethodParameterIgnoredAnnotationsBuildItem(
        Predicate<AnnotationInstance> predicate);

    public Predicate<AnnotationInstance> getPredicate();
}

Embedding Store

EmbeddingStoreBuildItem

Package: io.quarkiverse.langchain4j.deployment

Marker that an embedding store was registered in CDI.

public final class EmbeddingStoreBuildItem extends MultiBuildItem {

    public EmbeddingStoreBuildItem();
}

Usage:

@BuildStep
void registerEmbeddingStore(BuildProducer<EmbeddingStoreBuildItem> producer) {
    // Signal that an embedding store is available
    producer.produce(new EmbeddingStoreBuildItem());
}

In-Process Embedding Models

InProcessEmbeddingBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Information about in-process (local) embedding models.

public final class InProcessEmbeddingBuildItem
        extends MultiBuildItem
        implements ProviderHolder {

    public InProcessEmbeddingBuildItem(
        String modelName,
        String className,
        String onnxModelPath,
        String vocabularyPath);

    public String getProvider(); // Returns className
    public String modelName();
    public String className();
    public String onnxModelPath();
    public String vocabularyPath();
    public boolean requireOnnxRuntime();
    public void setRequireOnnxRuntime(boolean requireOnnxRuntime);
}

ImplicitlyUserConfiguredChatProviderBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Provider configured based on user configuration (runtime-fixed).

public final class ImplicitlyUserConfiguredChatProviderBuildItem
        extends MultiBuildItem {

    public ImplicitlyUserConfiguredChatProviderBuildItem(
        String configName,
        String provider);

    public String getConfigName();
    public String getProvider();
}

DevServices

DevServicesChatModelRequiredBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Indicates a provider could use a local inference server for chat models.

public final class DevServicesChatModelRequiredBuildItem
        extends MultiBuildItem
        implements DevServicesModelRequired {

    public DevServicesChatModelRequiredBuildItem(
        String provider,
        String modelName,
        String baseUrlProperty);

    public String getProvider();
    public String getModelName();
    public String getBaseUrlProperty();
}

Usage:

@BuildStep
void requestDevServices(
        BuildProducer<DevServicesChatModelRequiredBuildItem> producer) {

    producer.produce(new DevServicesChatModelRequiredBuildItem(
        "my-provider",
        "llama3.2",
        "quarkus.langchain4j.my-provider.base-url"
    ));
}

DevServicesEmbeddingModelRequiredBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Indicates a provider could use a local inference server for embedding models.

public final class DevServicesEmbeddingModelRequiredBuildItem
        extends MultiBuildItem
        implements DevServicesModelRequired {

    public DevServicesEmbeddingModelRequiredBuildItem(
        String provider,
        String modelName,
        String baseUrlProperty);

    public String getProvider();
    public String getModelName();
    public String getBaseUrlProperty();
}

Tool Qualifiers

ToolQualifierProvider.BuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Determines if a tool class should use a CDI qualifier.

public final class ToolQualifierProvider.BuildItem extends MultiBuildItem {

    public ToolQualifierProvider.BuildItem(ToolQualifierProvider provider);

    public ToolQualifierProvider getProvider();
}

The ToolQualifierProvider interface:

public interface ToolQualifierProvider {
    boolean supports(ClassInfo classInfo);
    AnnotationInstance qualifier(ClassInfo classInfo);
}

Dev UI

AdditionalDevUiCardBuildItem

Package: io.quarkiverse.langchain4j.deployment.devui

Adds custom cards to the Quarkus Dev UI.

public final class AdditionalDevUiCardBuildItem extends MultiBuildItem {

    public AdditionalDevUiCardBuildItem(
        String title,
        String icon,
        String componentLink,
        Map<String, Object> buildTimeData);

    public String getTitle();
    public String getIcon();
    public String getComponentLink();
    public Map<String, Object> getBuildTimeData();
}

SimpleBuildItem Classes

Tool Metadata

ToolsMetadataBuildItem

Package: io.quarkiverse.langchain4j.deployment

Consolidated tool metadata after ArC bean removal filtering.

public final class ToolsMetadataBuildItem extends SimpleBuildItem {

    public ToolsMetadataBuildItem(Map<String, List<ToolMethodCreateInfo>> metadata);

    public Map<String, List<ToolMethodCreateInfo>> getMetadata();
}

Usage:

@BuildStep
void processToolMetadata(ToolsMetadataBuildItem metadata) {
    Map<String, List<ToolMethodCreateInfo>> toolsByClass = metadata.getMetadata();

    for (Map.Entry<String, List<ToolMethodCreateInfo>> entry : toolsByClass.entrySet()) {
        String className = entry.getKey();
        List<ToolMethodCreateInfo> methods = entry.getValue();
        // Process tool methods for this class
    }
}

ToolsMetadataBeforeRemovalBuildItem

Package: io.quarkiverse.langchain4j.deployment

Tool metadata before ArC bean removal filtering.

public final class ToolsMetadataBeforeRemovalBuildItem extends SimpleBuildItem {

    public ToolsMetadataBeforeRemovalBuildItem(
        Map<String, List<ToolMethodCreateInfo>> metadata);

    public Map<String, List<ToolMethodCreateInfo>> getMetadata();
}

ToolProviderMetaBuildItem

Package: io.quarkiverse.langchain4j.deployment

Metadata about tool providers discovered at build time.

public final class ToolProviderMetaBuildItem extends SimpleBuildItem {

    public ToolProviderMetaBuildItem(List<ToolProviderInfo> metadata);

    public List<ToolProviderInfo> getMetadata();
}

Guardrails

UsedToolGuardrailClassesBuildItem

Package: io.quarkiverse.langchain4j.deployment

Collects tool guardrail classes used in the application.

public final class UsedToolGuardrailClassesBuildItem extends SimpleBuildItem {

    public UsedToolGuardrailClassesBuildItem(List<DotName> classes);

    public List<DotName> getClasses();
}

Native Image and OnnxRuntime

RequireOnnxRuntimeBuildItem

Package: io.quarkiverse.langchain4j.deployment

Signals that OnnxRuntime is required in the native image.

public final class RequireOnnxRuntimeBuildItem extends SimpleBuildItem {

    public RequireOnnxRuntimeBuildItem();
}

Usage:

@BuildStep
void requireOnnx(BuildProducer<RequireOnnxRuntimeBuildItem> producer) {
    // Signal that OnnxRuntime JNI libraries are needed
    producer.produce(new RequireOnnxRuntimeBuildItem());
}

Embedding Model Auto-Creation

AutoCreateEmbeddingModelBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Requests embedding model generation without injection points (for Easy RAG).

public final class AutoCreateEmbeddingModelBuildItem extends SimpleBuildItem {

    public AutoCreateEmbeddingModelBuildItem();
}

InMemoryEmbeddingStoreBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Marker that in-memory embedding store was registered (by Easy RAG).

public final class InMemoryEmbeddingStoreBuildItem extends SimpleBuildItem {

    public InMemoryEmbeddingStoreBuildItem();
}

DevServices Configuration

DevServicesOllamaConfigBuildItem

Package: io.quarkiverse.langchain4j.deployment.items

Carries DevServices runtime values to Dev UI.

public final class DevServicesOllamaConfigBuildItem extends SimpleBuildItem {

    public DevServicesOllamaConfigBuildItem(Map<String, String> config);

    public Map<String, String> getConfig();
}

BuildItem Interfaces

ProviderHolder

Package: io.quarkiverse.langchain4j.deployment.items

Marker interface for BuildItems that hold provider information.

public interface ProviderHolder {
    String getProvider();
}

Implemented by:

  • ChatModelProviderCandidateBuildItem
  • EmbeddingModelProviderCandidateBuildItem
  • ImageModelProviderCandidateBuildItem
  • ModerationModelProviderCandidateBuildItem
  • ScoringModelProviderCandidateBuildItem
  • InProcessEmbeddingBuildItem

DevServicesModelRequired

Package: io.quarkiverse.langchain4j.deployment.items

Marker interface for BuildItems that represent DevServices model requirements.

public interface DevServicesModelRequired {
    String getProvider();
    String getModelName();
    String getBaseUrlProperty();
}

Implemented by:

  • DevServicesChatModelRequiredBuildItem
  • DevServicesEmbeddingModelRequiredBuildItem

ToolQualifierProvider

Package: io.quarkiverse.langchain4j.deployment.items

Interface for determining if a class containing tools should use a CDI qualifier.

public interface ToolQualifierProvider {
    /**
     * Determines if this provider supports the given class.
     *
     * @param classInfo The class to check
     * @return true if this provider can supply a qualifier for this class
     */
    boolean supports(ClassInfo classInfo);

    /**
     * Returns the CDI qualifier to use for the given class.
     *
     * @param classInfo The class to get qualifier for
     * @return AnnotationLiteral representing the qualifier
     */
    AnnotationLiteral<?> qualifier(ClassInfo classInfo);
}

Usage:

// Implement a custom tool qualifier provider
public class MyToolQualifierProvider implements ToolQualifierProvider {
    @Override
    public boolean supports(ClassInfo classInfo) {
        // Check if this class should have a qualifier
        return classInfo.hasAnnotation(
            DotName.createSimple("com.example.CustomTool")
        );
    }

    @Override
    public AnnotationLiteral<?> qualifier(ClassInfo classInfo) {
        // Return the appropriate CDI qualifier
        return new NamedLiteral(classInfo.simpleName());
    }
}

// Register in a BuildStep
@BuildStep
void registerToolQualifierProvider(
        BuildProducer<ToolQualifierProvider.BuildItem> producer) {
    producer.produce(
        new ToolQualifierProvider.BuildItem(new MyToolQualifierProvider())
    );
}

Common Patterns

Pattern: Provider Registration and Selection

// Step 1: Register as a provider candidate
@BuildStep
void registerProvider(BuildProducer<ChatModelProviderCandidateBuildItem> producer) {
    producer.produce(new ChatModelProviderCandidateBuildItem("my-provider"));
}

// Step 2: React when selected
@BuildStep
void onProviderSelected(List<SelectedChatModelProviderBuildItem> selected) {
    for (SelectedChatModelProviderBuildItem item : selected) {
        if ("my-provider".equals(item.getProvider())) {
            // Create beans, configure runtime, etc.
        }
    }
}

Pattern: Conditional Bean Creation

@BuildStep
void conditionalBeans(
        List<DeclarativeAiServiceBuildItem> aiServices,
        BuildProducer<RequestChatModelBeanBuildItem> producer) {

    // Check if any AI service uses a specific model
    boolean needsModel = aiServices.stream()
        .anyMatch(s -> "my-model".equals(s.getChatModelName()));

    if (needsModel) {
        producer.produce(new RequestChatModelBeanBuildItem("my-model"));
    }
}

Pattern: Combining Multiple BuildItems

@BuildStep
void combineBuildItems(
        List<DeclarativeAiServiceBuildItem> services,
        List<ToolMethodBuildItem> tools,
        ToolsMetadataBuildItem metadata) {

    // Correlate services with their tools
    Map<String, List<ToolMethodCreateInfo>> toolsByClass = metadata.getMetadata();

    for (DeclarativeAiServiceBuildItem service : services) {
        List<ClassInfo> toolClasses = service.getToolClassInfos();
        for (ClassInfo toolClass : toolClasses) {
            List<ToolMethodCreateInfo> methods =
                toolsByClass.get(toolClass.name().toString());
            // Process service-tool relationship
        }
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-core-deployment

docs

build-items.md

configuration.md

index.md

processors.md

utilities.md

tile.json