tessl/maven-dev-langchain4j--langchain4j-open-ai

LangChain4j OpenAI Integration providing Java access to OpenAI APIs including chat models, embeddings, image generation, audio transcription, and moderation.

Overview

Eval results

Files

Moderation Models

Name: tessl/maven-dev-langchain4j--langchain4j-open-ai
Author: tessl

Moderation models analyze text and chat message content for policy violations. These models help ensure safe user-generated content and compliance with content policies.

The LangChain4j moderation API returns a simple flagged/not-flagged status. While OpenAI's moderation endpoint provides detailed category information internally, the LangChain4j Moderation interface exposes only a binary flagged status and optionally the flagged text.

Capabilities

OpenAiModerationModel

Synchronous moderation model that analyzes content for policy violations. Supports both text strings and chat message lists.

public class OpenAiModerationModel implements ModerationModel {
    public static OpenAiModerationModelBuilder builder();

    // Core moderation methods
    public Response<Moderation> moderate(String text);
    public Response<Moderation> moderate(List<ChatMessage> messages);

    // Model information
    public String modelName();
}

OpenAiModerationModelBuilder

Builder for configuring OpenAiModerationModel instances.

public static class OpenAiModerationModelBuilder {
    // Core configuration
    public OpenAiModerationModelBuilder modelName(String modelName);
    public OpenAiModerationModelBuilder modelName(OpenAiModerationModelName modelName);
    public OpenAiModerationModelBuilder baseUrl(String baseUrl);
    public OpenAiModerationModelBuilder apiKey(String apiKey);
    public OpenAiModerationModelBuilder organizationId(String organizationId);
    public OpenAiModerationModelBuilder projectId(String projectId);

    // HTTP configuration
    public OpenAiModerationModelBuilder httpClientBuilder(HttpClientBuilder httpClientBuilder);
    public OpenAiModerationModelBuilder timeout(Duration timeout);
    public OpenAiModerationModelBuilder maxRetries(Integer maxRetries);
    public OpenAiModerationModelBuilder customHeaders(Map<String, String> customHeaders);
    public OpenAiModerationModelBuilder customHeaders(Supplier<Map<String, String>> customHeadersSupplier);
    public OpenAiModerationModelBuilder customQueryParams(Map<String, String> customQueryParams);

    // Logging
    public OpenAiModerationModelBuilder logRequests(Boolean logRequests);
    public OpenAiModerationModelBuilder logResponses(Boolean logResponses);
    public OpenAiModerationModelBuilder logger(Logger logger);

    // Build
    public OpenAiModerationModel build();
}

Basic Usage Example

import dev.langchain4j.model.openai.OpenAiModerationModel;
import dev.langchain4j.model.openai.OpenAiModerationModelName;
import dev.langchain4j.model.moderation.Moderation;
import dev.langchain4j.model.output.Response;

// Create moderation model
OpenAiModerationModel model = OpenAiModerationModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiModerationModelName.TEXT_MODERATION_LATEST)
    .build();

// Moderate text
String userInput = "This is a sample text to moderate";
Response<Moderation> response = model.moderate(userInput);

Moderation moderation = response.content();
if (moderation.flagged()) {
    System.out.println("Content flagged!");
    String flaggedText = moderation.flaggedText();
    if (flaggedText != null) {
        System.out.println("Flagged text: " + flaggedText);
    }
} else {
    System.out.println("Content is safe");
}

Chat Message Moderation Example

import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.data.message.ChatMessage;
import java.util.List;

// Moderate conversation messages
List<ChatMessage> conversation = List.of(
    SystemMessage.from("You are a helpful assistant"),
    UserMessage.from("Hello, how are you?"),
    UserMessage.from("Can you help me with something?")
);

Response<Moderation> response = model.moderate(conversation);
Moderation moderation = response.content();

if (moderation.flagged()) {
    System.out.println("Conversation contains policy violations");
    // Take appropriate action
}

Content Filtering Pipeline Example

import java.time.Duration;

public class ContentFilteringService {
    private final OpenAiModerationModel moderationModel;

    public ContentFilteringService(String apiKey) {
        this.moderationModel = OpenAiModerationModel.builder()
            .apiKey(apiKey)
            .modelName(OpenAiModerationModelName.TEXT_MODERATION_LATEST)
            .timeout(Duration.ofSeconds(10))
            .build();
    }

    public FilterResult filterContent(String content) {
        Response<Moderation> response = moderationModel.moderate(content);
        Moderation moderation = response.content();

        if (moderation.flagged()) {
            return FilterResult.blocked("Content violates policy", moderation.flaggedText());
        }

        return FilterResult.allowed();
    }

    public static class FilterResult {
        private final Status status;
        private final String reason;
        private final String flaggedText;

        public enum Status {
            ALLOWED, BLOCKED
        }

        public static FilterResult allowed() {
            return new FilterResult(Status.ALLOWED, null, null);
        }

        public static FilterResult blocked(String reason, String flaggedText) {
            return new FilterResult(Status.BLOCKED, reason, flaggedText);
        }

        private FilterResult(Status status, String reason, String flaggedText) {
            this.status = status;
            this.reason = reason;
            this.flaggedText = flaggedText;
        }

        public boolean isAllowed() { return status == Status.ALLOWED; }
        public boolean isBlocked() { return status == Status.BLOCKED; }
        public String getReason() { return reason; }
        public String getFlaggedText() { return flaggedText; }
    }
}

// Usage
ContentFilteringService filter = new ContentFilteringService(apiKey);
ContentFilteringService.FilterResult result = filter.filterContent(userInput);

if (result.isAllowed()) {
    processContent(userInput);
} else if (result.isBlocked()) {
    rejectContent(result.getReason());
}

Batch Moderation Example

import java.util.concurrent.CompletableFuture;
import java.util.stream.Collectors;

public List<Moderation> moderateBatch(List<String> texts, OpenAiModerationModel model) {
    return texts.stream()
        .map(text -> {
            Response<Moderation> response = model.moderate(text);
            return response.content();
        })
        .collect(Collectors.toList());
}

// Parallel processing for large batches
public CompletableFuture<List<Moderation>> moderateBatchAsync(List<String> texts, OpenAiModerationModel model) {
    return CompletableFuture.supplyAsync(() -> {
        return texts.parallelStream()
            .map(text -> model.moderate(text).content())
            .collect(Collectors.toList());
    });
}

Model Names

public enum OpenAiModerationModelName {
    TEXT_MODERATION_STABLE("text-moderation-stable"),
    TEXT_MODERATION_LATEST("text-moderation-latest"),
    OMNI_MODERATION_LATEST("omni-moderation-latest"),
    OMNI_MODERATION_2024_09_26("omni-moderation-2024-09-26");

    public String toString();
}

Model Comparison

Model	Type	Accuracy	Stability
text-moderation-stable	Text only	Good	Frozen, consistent
text-moderation-latest	Text only	Best	Updates over time
omni-moderation-latest	Text + Images	Best	Updates over time
omni-moderation-2024-09-26	Text + Images	Excellent	Frozen at date

Types

Moderation

The Moderation class provides a simple binary flagged status.

public class Moderation {
    // Check if content was flagged
    public boolean flagged();

    // Get the flagged text (null if not flagged)
    public String flaggedText();

    // Factory methods
    public static Moderation flagged(String flaggedText);
    public static Moderation notFlagged();
}

ModerationModel Interface

public interface ModerationModel {
    Response<Moderation> moderate(String text);
    Response<Moderation> moderate(List<ChatMessage> messages);
}

Content Categories

While the LangChain4j API only exposes a binary flagged status, OpenAI's moderation models check for the following policy violations internally:

Hate

Content that expresses, incites, or promotes hate based on race, gender, ethnicity, religion, nationality, sexual orientation, disability, or caste. Includes hate/threatening content.

Harassment

Content that expresses, incites, or promotes harassing language towards any target. Includes harassment/threatening content.

Self-Harm

Content that promotes, encourages, or depicts acts of self-harm (suicide, cutting, eating disorders), including intent and instructions.

Sexual

Content meant to arouse sexual excitement, including descriptions of sexual activity and promotion of sexual services. Includes sexual/minors content.

Violence

Content that depicts death, violence, or physical injury, including graphic depictions.

Best Practices

Simple Binary Filtering

public boolean isContentSafe(String content, OpenAiModerationModel model) {
    Response<Moderation> response = model.moderate(content);
    return !response.content().flagged();
}

// Usage
if (isContentSafe(userInput, model)) {
    processContent(userInput);
} else {
    rejectContent(userInput);
}

Handling Flagged Content

public void handleModeration(Moderation moderation, String content) {
    if (!moderation.flagged()) {
        approveContent(content);
        return;
    }

    // Content is flagged - take action
    blockContent(content, "Content violates policy");
    logViolation(content, moderation.flaggedText());
}

User Feedback Integration

public class ModerationWithContext {
    private final OpenAiModerationModel model;
    private final UserHistoryStore userHistory;

    public ModerationResult moderateWithContext(String content, String userId) {
        Response<Moderation> response = model.moderate(content);
        Moderation moderation = response.content();

        // Check user history
        UserHistory history = userHistory.getUserHistory(userId);

        // Adjust decision based on user reputation
        if (history.hasGoodReputation() && !moderation.flagged()) {
            return ModerationResult.approved();
        }

        if (history.hasViolations() && moderation.flagged()) {
            return ModerationResult.blocked();
        }

        // Default logic
        return moderation.flagged() ?
            ModerationResult.blocked() :
            ModerationResult.approved();
    }
}

Caching for Performance

import java.util.concurrent.ConcurrentHashMap;
import java.security.MessageDigest;

public class CachedModeration {
    private final OpenAiModerationModel model;
    private final ConcurrentHashMap<String, Moderation> cache;

    public CachedModeration(OpenAiModerationModel model) {
        this.model = model;
        this.cache = new ConcurrentHashMap<>();
    }

    public Moderation moderate(String content) {
        String hash = hashContent(content);

        return cache.computeIfAbsent(hash, k -> {
            Response<Moderation> response = model.moderate(content);
            return response.content();
        });
    }

    private String hashContent(String content) {
        try {
            MessageDigest md = MessageDigest.getInstance("SHA-256");
            byte[] hash = md.digest(content.getBytes());
            return bytesToHex(hash);
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    private String bytesToHex(byte[] bytes) {
        StringBuilder sb = new StringBuilder();
        for (byte b : bytes) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    }
}

Common Use Cases

User-Generated Content

Filter comments, posts, and messages on social platforms.

Chat Applications

Moderate messages in real-time chat systems.

Content Publishing

Screen articles, reviews, and submissions before publication.

Customer Support

Flag inappropriate messages in support tickets.

Community Forums

Maintain community standards and safety.

Gaming

Monitor in-game chat and user profiles.

Marketplace Listings

Screen product descriptions and seller communications.

Integration Patterns

Pre-Submission Check

// Check content before allowing submission
public boolean allowSubmission(String content, OpenAiModerationModel model) {
    Response<Moderation> response = model.moderate(content);
    return !response.content().flagged();
}

Post-Submission Moderation

import java.util.concurrent.CompletableFuture;

// Allow submission, moderate asynchronously
public void submitContent(String content, String userId, OpenAiModerationModel model, ContentStore contentStore) {
    // Save content immediately
    contentStore.save(content, userId);

    // Moderate asynchronously
    CompletableFuture.runAsync(() -> {
        Response<Moderation> response = model.moderate(content);
        if (response.content().flagged()) {
            contentStore.hide(content);
            notifyModerators(content, response.content());
        }
    });
}

Progressive Enhancement

// Start with simple rules, escalate to API
public ModerationResult progressiveModerate(String content, OpenAiModerationModel model) {
    // Fast local checks first
    if (containsBlacklistedWords(content)) {
        return ModerationResult.blocked("Blacklisted word");
    }

    // If passes basic checks, use API
    Response<Moderation> response = model.moderate(content);
    if (response.content().flagged()) {
        return ModerationResult.blocked("API flagged content");
    }

    return ModerationResult.approved();
}

Performance Considerations

Response Time

Typical: 100-500ms
Network latency is primary factor
Consider async moderation for better UX

Cost

Free tier available
Very low cost per request
Much cheaper than chat models
Check current OpenAI pricing

Rate Limits

Generous limits for moderation
Varies by account tier
Rarely a bottleneck

Accuracy

High accuracy for clear violations
May have false positives/negatives
Combine with human review for edge cases

Install with Tessl CLI

npx tessl i tessl/maven-dev-langchain4j--langchain4j-open-ai

docs

advanced-features.md

audio-transcription-models.md

tessl/maven-dev-langchain4j--langchain4j-open-ai