CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-dev-langchain4j--langchain4j-easy-rag

Zero-configuration RAG package that bundles document parsing, embedding, and splitting for easy Retrieval-Augmented Generation in Java applications

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

api-types-chat.mddocs/

Chat Model Types API

Types for chat models and AI services used in RAG applications.

ChatModel

Interface for chat/completion models.

package dev.langchain4j.model.chat;

public interface ChatModel {
    // Main chat API
    default ChatResponse chat(ChatRequest chatRequest)

    // Convenience methods
    default String chat(String userMessage)
    default ChatResponse chat(ChatMessage... messages)
    default ChatResponse chat(List<ChatMessage> messages)

    // Configuration
    default ChatRequestParameters defaultRequestParameters()
    default Set<Capability> supportedCapabilities()
}

Main Method:

  • chat(chatRequest) - Send chat request, get full response

Convenience Methods:

  • chat(userMessage) - Quick string-in, string-out
  • chat(messages...) - Chat with message array
  • chat(messageList) - Chat with message list

Configuration:

  • defaultRequestParameters() - Get default parameters
  • supportedCapabilities() - Get model capabilities

Example:

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

ChatModel model = OpenAiChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName("gpt-4o-mini")
    .build();

// Simple usage
String response = model.chat("What is RAG?");

// With RAG - use via AiServices
Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(model)
    .contentRetriever(retriever)
    .build();

OpenAiChatModel

OpenAI implementation of ChatModel.

package dev.langchain4j.model.openai;

public class OpenAiChatModel implements ChatModel {
    // Static builder method
    public static OpenAiChatModelBuilder builder()

    // Builder class
    public static class OpenAiChatModelBuilder {
        // Essential configuration
        public OpenAiChatModelBuilder apiKey(String apiKey)
        public OpenAiChatModelBuilder modelName(String modelName)
        public OpenAiChatModelBuilder baseUrl(String baseUrl)
        public OpenAiChatModelBuilder organizationId(String organizationId)

        // Request parameters
        public OpenAiChatModelBuilder temperature(Double temperature)
        public OpenAiChatModelBuilder maxTokens(Integer maxTokens)
        public OpenAiChatModelBuilder topP(Double topP)
        public OpenAiChatModelBuilder timeout(Duration timeout)

        // Build
        public OpenAiChatModel build()
    }
}

Essential Configuration:

  • apiKey(key) - OpenAI API key (required)
  • modelName(name) - Model to use (e.g., "gpt-4o-mini")
  • baseUrl(url) - Custom API endpoint
  • organizationId(id) - OpenAI organization ID

Parameters:

  • temperature(temp) - Randomness 0.0-2.0 (default: 0.7)
  • maxTokens(tokens) - Max response tokens
  • topP(p) - Nucleus sampling parameter
  • timeout(duration) - Request timeout

Example:

import dev.langchain4j.model.openai.OpenAiChatModel;
import java.time.Duration;

ChatModel model = OpenAiChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName("gpt-4o-mini")
    .temperature(0.7)
    .maxTokens(500)
    .timeout(Duration.ofSeconds(30))
    .build();

EmbeddingModel

Interface for embedding models.

package dev.langchain4j.model.embedding;

public interface EmbeddingModel {
    // Embed single text
    default Response<Embedding> embed(String text)
    default Response<Embedding> embed(TextSegment textSegment)

    // Embed multiple (primary method)
    Response<List<Embedding>> embedAll(List<TextSegment> textSegments)

    // Model info
    default int dimension()
    default String modelName()
}

Single Embedding:

  • embed(text) - Embed string
  • embed(textSegment) - Embed text segment

Batch Embedding:

  • embedAll(textSegments) - Embed multiple segments (more efficient)

Model Info:

  • dimension() - Embedding vector dimension
  • modelName() - Model identifier

Note: When using easy-rag, BGE-small-en-v1.5 is automatically provided via SPI.

Example:

import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.model.output.Response;

// With easy-rag, model loaded automatically
// Or use explicit model
EmbeddingModel model = new BgeSmallEnV15QuantizedEmbeddingModel();

// Embed single text
Response<Embedding> response = model.embed("Some text");
Embedding embedding = response.content();

// Embed multiple
List<TextSegment> segments = Arrays.asList(
    TextSegment.from("Text 1"),
    TextSegment.from("Text 2")
);
Response<List<Embedding>> batchResponse = model.embedAll(segments);

Response

Generic response wrapper for model outputs.

package dev.langchain4j.model.output;

public class Response<T> {
    // Constructors
    public Response(T content)
    public Response(T content, TokenUsage tokenUsage, FinishReason finishReason)
    public Response(T content, TokenUsage tokenUsage, FinishReason finishReason, Map<String, Object> metadata)

    // Static factory methods
    public static <T> Response<T> from(T content)
    public static <T> Response<T> from(T content, TokenUsage tokenUsage)
    public static <T> Response<T> from(T content, TokenUsage tokenUsage, FinishReason finishReason)

    // Instance methods
    public T content()
    public TokenUsage tokenUsage()
    public FinishReason finishReason()
    public Map<String, Object> metadata()
}

Type Parameter:

  • T - Type of content (e.g., Embedding, List<Embedding>, String)

Constructors & Factories:

  • Create response with content and optional metadata

Accessors:

  • content() - Get the main content
  • tokenUsage() - Get token usage statistics
  • finishReason() - Get completion reason
  • metadata() - Get additional metadata

Example:

Response<Embedding> response = embeddingModel.embed("text");

Embedding embedding = response.content();
TokenUsage usage = response.tokenUsage();
System.out.println("Used " + usage.inputTokenCount() + " tokens");

ChatMessage

Base interface for chat messages.

package dev.langchain4j.data.message;

public interface ChatMessage {
    ChatMessageType type()
}

Method:

  • type() - Get message type

Implementations:

  • UserMessage - User input
  • AiMessage - AI response
  • SystemMessage - System instructions
  • ToolExecutionResultMessage - Tool results

ChatMessageType

Enum for message types.

package dev.langchain4j.data.message;

public enum ChatMessageType {
    SYSTEM,              // System instructions
    USER,                // User input
    AI,                  // AI response
    TOOL_EXECUTION_RESULT, // Tool execution result
    CUSTOM               // Custom type
}

Values:

  • SYSTEM - System/instruction messages
  • USER - User messages
  • AI - AI-generated responses
  • TOOL_EXECUTION_RESULT - Results from tool calls
  • CUSTOM - Custom message types

AiMessage

AI-generated message.

package dev.langchain4j.data.message;

public class AiMessage implements ChatMessage {
    // Constructor
    public AiMessage(String text)

    // Static factory methods
    public static AiMessage from(String text)
    public static AiMessage aiMessage(String text)

    // Methods
    public String text()
    public ChatMessageType type()
}

Constructor & Factories:

  • Create AI message from text

Methods:

  • text() - Get message text
  • type() - Returns ChatMessageType.AI

Example:

AiMessage message = AiMessage.from("This is the AI response");
String text = message.text();

ChatRequest

Request for chat completion.

package dev.langchain4j.model.chat.request;

public class ChatRequest {
    // Static builder
    public static Builder builder()

    // Accessors
    public List<ChatMessage> messages()
    public ChatRequestParameters parameters()
    public String modelName()
    public Double temperature()
    public Integer maxOutputTokens()

    // Builder
    public static class Builder {
        public Builder messages(List<ChatMessage> messages)
        public Builder messages(ChatMessage... messages)
        public Builder parameters(ChatRequestParameters parameters)
        public Builder modelName(String modelName)
        public Builder temperature(Double temperature)
        public Builder maxOutputTokens(Integer maxOutputTokens)
        public ChatRequest build()
    }
}

Builder:

  • messages(list) - Set conversation messages
  • messages(varargs) - Set messages as varargs
  • parameters(params) - Set request parameters
  • modelName(name) - Override model
  • temperature(temp) - Set temperature
  • maxOutputTokens(tokens) - Set max tokens

Accessors:

  • Get configured values

ChatResponse

Response from chat completion.

package dev.langchain4j.model.chat.response;

public class ChatResponse {
    // Static builder
    public static Builder builder()

    // Accessors
    public AiMessage aiMessage()
    public TokenUsage tokenUsage()
    public FinishReason finishReason()
    public String id()
    public String modelName()

    // Builder
    public static class Builder {
        public Builder aiMessage(AiMessage aiMessage)
        public Builder tokenUsage(TokenUsage tokenUsage)
        public Builder finishReason(FinishReason finishReason)
        public Builder id(String id)
        public Builder modelName(String modelName)
        public ChatResponse build()
    }
}

Accessors:

  • aiMessage() - Get AI's response message
  • tokenUsage() - Get token usage
  • finishReason() - Get why generation stopped
  • id() - Get response ID
  • modelName() - Get model used

Example:

ChatResponse response = chatModel.chat(messages);

String responseText = response.aiMessage().text();
TokenUsage usage = response.tokenUsage();
FinishReason reason = response.finishReason();

FinishReason

Enum for completion finish reasons.

package dev.langchain4j.model.output;

public enum FinishReason {
    STOP,            // Completed normally
    LENGTH,          // Hit token limit
    TOOL_EXECUTION,  // Needs tool execution
    CONTENT_FILTER,  // Content filtered
    OTHER            // Other reason
}

Values:

  • STOP - Model completed naturally
  • LENGTH - Reached max token limit
  • TOOL_EXECUTION - Tool call needed
  • CONTENT_FILTER - Content policy triggered
  • OTHER - Other/unknown reason

AiServices

Builder for creating AI service interfaces with RAG.

package dev.langchain4j.service;

public class AiServices {
    public static <T> AiServicesBuilder<T> builder(Class<T> aiServiceClass)
}

Usage:

interface Assistant {
    String chat(String userMessage);
}

Assistant assistant = AiServices.builder(Assistant.class)
    .chatModel(chatModel)
    .contentRetriever(retriever)  // Enable RAG
    .build();

String answer = assistant.chat("What are the requirements?");

Key Features:

  • Define interface with methods
  • Automatically integrates RAG via contentRetriever
  • Handles conversation management
  • Type-safe method definitions

Complete RAG Example

import dev.langchain4j.data.document.Document;
import dev.langchain4j.data.document.loader.FileSystemDocumentLoader;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.rag.content.retriever.EmbeddingStoreContentRetriever;
import dev.langchain4j.service.AiServices;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.EmbeddingStoreIngestor;
import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore;

import java.nio.file.Paths;

public class RagAssistant {

    interface Assistant {
        String chat(String message);
    }

    public static void main(String[] args) {
        // 1. Load and ingest documents
        Document doc = FileSystemDocumentLoader.loadDocument(
            Paths.get("knowledge-base.pdf")
        );
        EmbeddingStore<TextSegment> store = new InMemoryEmbeddingStore<>();
        EmbeddingStoreIngestor.ingest(doc, store);

        // 2. Configure chat model
        ChatModel chatModel = OpenAiChatModel.builder()
            .apiKey(System.getenv("OPENAI_API_KEY"))
            .modelName("gpt-4o-mini")
            .temperature(0.7)
            .build();

        // 3. Create RAG-enabled assistant
        Assistant assistant = AiServices.builder(Assistant.class)
            .chatModel(chatModel)
            .contentRetriever(EmbeddingStoreContentRetriever.from(store))
            .build();

        // 4. Use assistant
        String answer = assistant.chat("What is covered in the knowledge base?");
        System.out.println(answer);
    }
}

Related APIs

  • Document Ingestion API - Document ingestion
  • Content Retrieval API - Content retrieval
  • Core Types - Core data types
  • Quick Start - Quick start examples
  • Examples - Complete applications

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-easy-rag@1.11.0

docs

api-document-loading.md

api-ingestion.md

api-retrieval.md

api-types-chat.md

api-types-core.md

api-types-storage.md

architecture.md

configuration.md

examples.md

index.md

quickstart.md

reference.md

troubleshooting.md

tile.json