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

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

Overview

Eval results

Files

Quarkus LangChain4j Core

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

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

Install with Tessl CLI

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

docs

response-augmentation.md

tools.md

tile.json