CtrlK
BlogDocsLog inGet started
Tessl Logo

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

Core runtime module for Quarkus LangChain4j integration with declarative AI services, guardrails, and observability

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

Quarkus LangChain4j Core

The Quarkus LangChain4j Core module provides declarative, CDI-based integration for building AI-powered applications with LangChain4j. It enables developers to create AI services using annotations, integrate tools with guardrails, manage conversation memory, observe AI service events, and augment responses - all within the Quarkus framework.

Package Information

  • Package Name: quarkus-langchain4j-core
  • Package Type: maven
  • Group ID: io.quarkiverse.quarkus
  • Artifact ID: quarkus-langchain4j-core
  • Language: Java
  • Installation: Add to your Maven pom.xml:
<dependency>
    <groupId>io.quarkiverse.quarkus</groupId>
    <artifactId>quarkus-langchain4j-core</artifactId>
    <version>${quarkus-langchain4j.version}</version>
</dependency>

Or to your Gradle build.gradle:

implementation 'io.quarkiverse.quarkus:quarkus-langchain4j-core:${quarkusLangchain4jVersion}'

Core Imports

// Core AI Service annotations
import io.quarkiverse.langchain4j.RegisterAiService;
import io.quarkiverse.langchain4j.ModelName;
import io.quarkiverse.langchain4j.ToolBox;
import io.quarkiverse.langchain4j.SeedMemory;
import io.quarkiverse.langchain4j.CreatedAware;

// Memory management
import io.quarkiverse.langchain4j.ChatMemoryRemover;

// Tool error handling
import io.quarkiverse.langchain4j.HandleToolArgumentError;
import io.quarkiverse.langchain4j.HandleToolExecutionError;

// Media content annotations
import io.quarkiverse.langchain4j.ImageUrl;
import io.quarkiverse.langchain4j.AudioUrl;
import io.quarkiverse.langchain4j.VideoUrl;
import io.quarkiverse.langchain4j.PdfUrl;

// Guardrails
import io.quarkiverse.langchain4j.guardrails.*;

// Authentication
import io.quarkiverse.langchain4j.auth.ModelAuthProvider;

// Cost estimation
import io.quarkiverse.langchain4j.cost.Cost;
import io.quarkiverse.langchain4j.cost.CostEstimator;

// Observability
import io.quarkiverse.langchain4j.observability.AiServiceSelector;
import io.quarkiverse.langchain4j.observability.AiServiceEvents;

// Response augmentation
import io.quarkiverse.langchain4j.response.ResponseAugmenter;
import io.quarkiverse.langchain4j.response.AiResponseAugmenter;

Basic Usage

import io.quarkiverse.langchain4j.RegisterAiService;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

// Define an AI service interface
@RegisterAiService
public interface AssistantService {
    @SystemMessage("You are a helpful assistant")
    String chat(String userMessage);
}

// Use the AI service
@ApplicationScoped
public class MyApplication {
    @Inject
    AssistantService assistant;
    
    public void processUserInput(String input) {
        String response = assistant.chat(input);
        System.out.println(response);
    }
}

Architecture Overview

The Quarkus LangChain4j Core module is organized into several key packages:

Core Package (io.quarkiverse.langchain4j)

Contains the primary annotations and utilities for declaring AI services:

  • @RegisterAiService: Declares CDI-managed AI services
  • @ModelName: Selects named model configurations
  • @ToolBox: Configures method-level tool access
  • @SeedMemory: Seeds chat memory with examples
  • ChatMemoryRemover: Utility for manual memory management

Authentication (io.quarkiverse.langchain4j.auth)

Provides authentication interfaces for model providers:

  • ModelAuthProvider: Interface for supplying authentication credentials

Cost Estimation (io.quarkiverse.langchain4j.cost)

Experimental APIs for estimating AI model costs:

  • CostEstimator: Interface for custom cost estimation strategies
  • Cost: Record type representing monetary cost
  • CostEstimatorService: Service for applying cost estimators

Guardrails (io.quarkiverse.langchain4j.guardrails)

Comprehensive framework for validating tool inputs and outputs:

  • @ToolInputGuardrails/@ToolOutputGuardrails: Annotations for applying guardrails
  • ToolInputGuardrail/ToolOutputGuardrail: Interfaces for implementing validation logic
  • ToolGuardrailRequest/Result: Request and result types for guardrail execution
  • ToolInvocationContext: Context information during tool invocation
  • ToolMetadata: Metadata about tools for validation

Observability (io.quarkiverse.langchain4j.observability)

Event-based monitoring for AI services:

  • @AiServiceSelector: Qualifies event observers for specific AI services
  • AiServiceEvents: Enum of observable events (STARTED, COMPLETED, ERROR, etc.)

Response Augmentation (io.quarkiverse.langchain4j.response)

Experimental APIs for modifying AI responses:

  • @ResponseAugmenter: Annotation for response augmentation
  • AiResponseAugmenter: Interface for implementing augmentation logic
  • ResponseAugmenterParams: Parameters passed to augmenters

Capabilities

AI Services

Create declarative AI services using the @RegisterAiService annotation with support for model selection, tool integration, memory management, and configuration.

@RegisterAiService
public interface MyAiService {
    @SystemMessage("You are a helpful assistant")
    String chat(String userMessage);
}

AI Services Documentation

Tools

Integrate external tools with your AI services and apply method-level tool configuration using @ToolBox.

@RegisterAiService(tools = { EmailTool.class, DatabaseTool.class })
public interface AssistantService {
    String help(String request);
    
    @ToolBox(WebSearchTool.class)
    String searchAndRespond(String query);
}

Tools Documentation

Memory Management

Seed chat memory with examples for few-shot prompting and manually remove memory entries.

@RegisterAiService
public interface SentimentAnalyzer {
    Sentiment analyze(String text);
    
    @SeedMemory
    static List<ChatMessage> seedExamples() {
        return List.of(
            UserMessage.from("I love it!"),
            AiMessage.from("POSITIVE")
        );
    }
}

Memory Documentation

Guardrails

Validate and transform tool inputs and outputs with a comprehensive guardrails framework.

@Tool("Send email")
@ToolInputGuardrails(EmailValidator.class)
public void sendEmail(String to, String subject, String body) {
    // Implementation
}

Guardrails Documentation

Observability

Observe AI service lifecycle events using CDI event observers qualified by service type.

@ApplicationScoped
public class AiServiceMonitor {
    void onStart(@Observes @AiServiceSelector(MyService.class) AiServiceStartedEvent event) {
        log.info("Service started");
    }
}

Observability Documentation

Authentication

Provide custom authentication for model providers on a per-model or global basis.

@ApplicationScoped
@ModelName("secure-model")
public class SecureModelAuth implements ModelAuthProvider {
    @Override
    public String getAuthorization(Input input) {
        return "Bearer " + getAccessToken();
    }
}

Authentication Documentation

Cost Estimation

Estimate AI model costs using custom strategies (experimental feature).

@ApplicationScoped
public class OpenAICostEstimator implements CostEstimator {
    @Override
    public boolean supports(SupportsContext context) {
        return context.model().startsWith("gpt-");
    }
    
    @Override
    public CostResult estimate(CostContext context) {
        // Calculate costs
    }
}

Cost Estimation Documentation

Response Augmentation

Transform AI responses before they reach the caller (experimental feature).

@ApplicationScoped
public class ResponseFormatter implements AiResponseAugmenter<String> {
    @Override
    public String augment(String response, ResponseAugmenterParams params) {
        return "**AI Response:**\n" + response;
    }
}

Response Augmentation Documentation

Media Content

Pass image, audio, video, and PDF URLs to AI models that support multimodal inputs.

@RegisterAiService
public interface VisionService {
    @UserMessage("Describe this image")
    String describe(@ImageUrl String url);
}

Media Content Documentation

docs

ai-services.md

authentication.md

cost-estimation.md

guardrails.md

index.md

media-content.md

memory.md

observability.md

response-augmentation.md

tools.md

tile.json