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

Chat Models

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

Chat models provide OpenAI's conversational AI capabilities through the chat completion interface. This includes access to GPT-4o, GPT-4, GPT-3.5-Turbo, and reasoning models like o1 and o3. Both synchronous and streaming interfaces are available for flexible integration patterns.

Chat models maintain conversation context through message history, support system prompts for behavior customization, and enable advanced features like tool calling, structured outputs with JSON schema validation, and parallel function execution.

Capabilities

OpenAiChatModel

Synchronous chat model for OpenAI's conversational models. Returns complete responses after processing the full request.

public class OpenAiChatModel implements ChatModel {
    public static OpenAiChatModelBuilder builder();

    // Core chat methods
    public Response<AiMessage> generate(List<ChatMessage> messages);
    public ChatResponse doChat(ChatRequest chatRequest);

    // Configuration and metadata
    public OpenAiChatRequestParameters defaultRequestParameters();
    public Set<Capability> supportedCapabilities();
    public List<ChatModelListener> listeners();
    public ModelProvider provider();
}

OpenAiChatModelBuilder

Builder for configuring OpenAiChatModel instances with comprehensive options for authentication, model selection, generation parameters, and HTTP settings.

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

    // Generation parameters
    public OpenAiChatModelBuilder temperature(Double temperature);
    public OpenAiChatModelBuilder topP(Double topP);
    public OpenAiChatModelBuilder stop(List<String> stop);
    public OpenAiChatModelBuilder maxTokens(Integer maxTokens);
    public OpenAiChatModelBuilder maxCompletionTokens(Integer maxCompletionTokens);
    public OpenAiChatModelBuilder presencePenalty(Double presencePenalty);
    public OpenAiChatModelBuilder frequencyPenalty(Double frequencyPenalty);
    public OpenAiChatModelBuilder logitBias(Map<String, Integer> logitBias);
    public OpenAiChatModelBuilder seed(Integer seed);

    // Response format and output structure
    public OpenAiChatModelBuilder responseFormat(ResponseFormat responseFormat);
    public OpenAiChatModelBuilder responseFormat(String responseFormat);
    public OpenAiChatModelBuilder strictJsonSchema(Boolean strictJsonSchema);

    // Tool calling
    public OpenAiChatModelBuilder strictTools(Boolean strictTools);
    public OpenAiChatModelBuilder parallelToolCalls(Boolean parallelToolCalls);

    // Advanced features
    public OpenAiChatModelBuilder supportedCapabilities(Set<Capability> supportedCapabilities);
    public OpenAiChatModelBuilder supportedCapabilities(Capability... supportedCapabilities);
    public OpenAiChatModelBuilder store(Boolean store);
    public OpenAiChatModelBuilder metadata(Map<String, String> metadata);
    public OpenAiChatModelBuilder serviceTier(String serviceTier);
    public OpenAiChatModelBuilder reasoningEffort(String reasoningEffort);
    public OpenAiChatModelBuilder user(String user);

    // DeepSeek thinking/reasoning support
    public OpenAiChatModelBuilder returnThinking(Boolean returnThinking);
    public OpenAiChatModelBuilder sendThinking(Boolean sendThinking);
    public OpenAiChatModelBuilder sendThinking(Boolean sendThinking, String thinkingFieldName);

    // Default request parameters
    public OpenAiChatModelBuilder defaultRequestParameters(ChatRequestParameters defaultRequestParameters);

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

    // Logging and observability
    public OpenAiChatModelBuilder logRequests(Boolean logRequests);
    public OpenAiChatModelBuilder logResponses(Boolean logResponses);
    public OpenAiChatModelBuilder logger(Logger logger);
    public OpenAiChatModelBuilder listeners(List<ChatModelListener> listeners);

    // Build
    public OpenAiChatModel build();
}

Usage Example

import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.model.openai.OpenAiChatModelName;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.model.output.Response;
import java.time.Duration;
import java.util.List;

// Basic configuration
OpenAiChatModel model = OpenAiChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiChatModelName.GPT_4_O)
    .temperature(0.7)
    .maxCompletionTokens(1000)
    .build();

// Simple generation
String response = model.generate("What is the meaning of life?");
System.out.println(response);

// Multi-turn conversation with system message
List<ChatMessage> messages = List.of(
    SystemMessage.from("You are a helpful assistant specialized in physics."),
    UserMessage.from("What is quantum entanglement?")
);

Response<AiMessage> aiResponse = model.generate(messages);
System.out.println(aiResponse.content().text());
System.out.println("Tokens used: " + aiResponse.tokenUsage().totalTokenCount());

// Advanced configuration with reasoning model
OpenAiChatModel reasoningModel = OpenAiChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiChatModelName.O3_MINI)
    .reasoningEffort("high")
    .timeout(Duration.ofMinutes(5))
    .logRequests(true)
    .logResponses(true)
    .build();

String complexAnswer = reasoningModel.generate(
    "Solve this logic puzzle: Five houses, each a different color..."
);

Tool Calling Example

import dev.langchain4j.agent.tool.ToolSpecification;
import dev.langchain4j.agent.tool.ToolExecutionRequest;
import dev.langchain4j.data.message.ToolExecutionResultMessage;

// Define a tool
ToolSpecification weatherTool = ToolSpecification.builder()
    .name("get_weather")
    .description("Get current weather for a location")
    .addParameter("location", "string", "The city name")
    .addParameter("unit", "string", "Temperature unit (celsius/fahrenheit)")
    .build();

// Configure model with tools
OpenAiChatModel model = OpenAiChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiChatModelName.GPT_4_O)
    .parallelToolCalls(true)
    .strictTools(true)
    .build();

// Create request with tool specifications
ChatRequest request = ChatRequest.builder()
    .messages(UserMessage.from("What's the weather in Paris and London?"))
    .toolSpecifications(List.of(weatherTool))
    .build();

ChatResponse response = model.doChat(request);

// Check if tools were called
if (response.aiMessage().hasToolExecutionRequests()) {
    for (ToolExecutionRequest toolRequest : response.aiMessage().toolExecutionRequests()) {
        System.out.println("Tool: " + toolRequest.name());
        System.out.println("Arguments: " + toolRequest.arguments());

        // Execute tool and get result
        String result = executeWeatherTool(toolRequest.arguments());

        // Send result back to model
        messages.add(response.aiMessage());
        messages.add(ToolExecutionResultMessage.from(toolRequest, result));
    }
}

Structured Output Example

import dev.langchain4j.model.output.structured.Description;

// Define a schema using Java class
class Person {
    @Description("The person's full name")
    public String name;

    @Description("The person's age in years")
    public int age;

    @Description("The person's occupation")
    public String occupation;
}

// Configure model for structured output
OpenAiChatModel model = OpenAiChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiChatModelName.GPT_4_O)
    .responseFormat(ResponseFormat.JSON)
    .strictJsonSchema(true)
    .build();

// Generate structured response
String prompt = "Extract person information: John Doe is a 35 year old software engineer.";
String jsonResponse = model.generate(prompt);

// Parse JSON to object
Person person = new ObjectMapper().readValue(jsonResponse, Person.class);
System.out.println(person.name + " - " + person.occupation);

OpenAiStreamingChatModel

Streaming chat model that returns responses incrementally as tokens are generated. Ideal for real-time user interfaces and long-running generations.

public class OpenAiStreamingChatModel implements StreamingChatModel {
    public static OpenAiStreamingChatModelBuilder builder();

    // Core streaming method
    public void doChat(ChatRequest chatRequest, StreamingChatResponseHandler handler);

    // Configuration and metadata
    public OpenAiChatRequestParameters defaultRequestParameters();
    public List<ChatModelListener> listeners();
    public ModelProvider provider();
}

OpenAiStreamingChatModelBuilder

Builder for configuring OpenAiStreamingChatModel instances. Has similar options to OpenAiChatModelBuilder with additional streaming-specific settings.

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

    // Generation parameters
    public OpenAiStreamingChatModelBuilder temperature(Double temperature);
    public OpenAiStreamingChatModelBuilder topP(Double topP);
    public OpenAiStreamingChatModelBuilder stop(List<String> stop);
    public OpenAiStreamingChatModelBuilder maxTokens(Integer maxTokens);
    public OpenAiStreamingChatModelBuilder maxCompletionTokens(Integer maxCompletionTokens);
    public OpenAiStreamingChatModelBuilder presencePenalty(Double presencePenalty);
    public OpenAiStreamingChatModelBuilder frequencyPenalty(Double frequencyPenalty);
    public OpenAiStreamingChatModelBuilder logitBias(Map<String, Integer> logitBias);
    public OpenAiStreamingChatModelBuilder seed(Integer seed);

    // Response format and output structure
    public OpenAiStreamingChatModelBuilder responseFormat(ResponseFormat responseFormat);
    public OpenAiStreamingChatModelBuilder responseFormat(String responseFormat);
    public OpenAiStreamingChatModelBuilder strictJsonSchema(Boolean strictJsonSchema);

    // Tool calling
    public OpenAiStreamingChatModelBuilder strictTools(Boolean strictTools);
    public OpenAiStreamingChatModelBuilder parallelToolCalls(Boolean parallelToolCalls);

    // Advanced features
    public OpenAiStreamingChatModelBuilder supportedCapabilities(Set<Capability> supportedCapabilities);
    public OpenAiStreamingChatModelBuilder supportedCapabilities(Capability... supportedCapabilities);
    public OpenAiStreamingChatModelBuilder store(Boolean store);
    public OpenAiStreamingChatModelBuilder metadata(Map<String, String> metadata);
    public OpenAiStreamingChatModelBuilder serviceTier(String serviceTier);
    public OpenAiStreamingChatModelBuilder reasoningEffort(String reasoningEffort);
    public OpenAiStreamingChatModelBuilder user(String user);

    // DeepSeek thinking/reasoning support
    public OpenAiStreamingChatModelBuilder returnThinking(Boolean returnThinking);
    public OpenAiStreamingChatModelBuilder sendThinking(Boolean sendThinking);
    public OpenAiStreamingChatModelBuilder sendThinking(Boolean sendThinking, String thinkingFieldName);

    // Streaming-specific configuration
    public OpenAiStreamingChatModelBuilder accumulateToolCallId(Boolean accumulateToolCallId);

    // Default request parameters
    public OpenAiStreamingChatModelBuilder defaultRequestParameters(ChatRequestParameters defaultRequestParameters);

    // HTTP configuration
    public OpenAiStreamingChatModelBuilder httpClientBuilder(HttpClientBuilder httpClientBuilder);
    public OpenAiStreamingChatModelBuilder timeout(Duration timeout);
    public OpenAiStreamingChatModelBuilder customHeaders(Map<String, String> customHeaders);
    public OpenAiStreamingChatModelBuilder customHeaders(Supplier<Map<String, String>> customHeadersSupplier);
    public OpenAiStreamingChatModelBuilder customQueryParams(Map<String, String> customQueryParams);
    public OpenAiStreamingChatModelBuilder customParameters(Map<String, Object> customParameters);

    // Logging and observability
    public OpenAiStreamingChatModelBuilder logRequests(Boolean logRequests);
    public OpenAiStreamingChatModelBuilder logResponses(Boolean logResponses);
    public OpenAiStreamingChatModelBuilder logger(Logger logger);
    public OpenAiStreamingChatModelBuilder listeners(List<ChatModelListener> listeners);

    // Build
    public OpenAiStreamingChatModel build();
}

Usage Example

import dev.langchain4j.model.openai.OpenAiStreamingChatModel;
import dev.langchain4j.model.openai.OpenAiChatModelName;
import dev.langchain4j.model.StreamingChatResponseHandler;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.data.message.UserMessage;
import java.util.concurrent.CompletableFuture;

// Create streaming model
OpenAiStreamingChatModel model = OpenAiStreamingChatModel.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .modelName(OpenAiChatModelName.GPT_4_O)
    .temperature(0.7)
    .build();

// Simple streaming with handler
ChatRequest request = ChatRequest.builder()
    .messages(UserMessage.from("Tell me a short story"))
    .build();

model.doChat(request, new StreamingChatResponseHandler() {
    @Override
    public void onNext(String token) {
        System.out.print(token); // Print each token as it arrives
    }

    @Override
    public void onComplete(ChatResponse response) {
        System.out.println("\n\nComplete!");
        System.out.println("Total tokens: " + response.tokenUsage().totalTokenCount());
        System.out.println("Finish reason: " + response.metadata().finishReason());
    }

    @Override
    public void onError(Throwable error) {
        System.err.println("Error: " + error.getMessage());
    }
});

// Advanced streaming with accumulator
CompletableFuture<String> future = new CompletableFuture<>();
StringBuilder accumulated = new StringBuilder();

ChatRequest poemRequest = ChatRequest.builder()
    .messages(UserMessage.from("Write a poem about artificial intelligence"))
    .build();

model.doChat(poemRequest, new StreamingChatResponseHandler() {
        @Override
        public void onNext(String token) {
            accumulated.append(token);
            updateUI(token); // Update UI in real-time
        }

        @Override
        public void onComplete(ChatResponse response) {
            String fullText = accumulated.toString();
            future.complete(fullText);
        }

        @Override
        public void onError(Throwable error) {
            future.completeExceptionally(error);
        }
    }
);

// Wait for completion if needed
String poem = future.get();

Streaming with Tool Calls

import dev.langchain4j.model.StreamingChatResponseHandler;
import dev.langchain4j.model.chat.response.ChatResponse;

// Create handler for streaming tool calls
StreamingChatResponseHandler handler = new StreamingChatResponseHandler() {
    private StringBuilder currentText = new StringBuilder();

    @Override
    public void onNext(String token) {
        currentText.append(token);
        System.out.print(token);
    }

    @Override
    public void onPartialResponse(ChatResponse partialResponse) {
        // Called periodically with accumulated response
        if (partialResponse.aiMessage().hasToolExecutionRequests()) {
            System.out.println("\nTool calls detected in progress...");
        }
    }

    @Override
    public void onComplete(ChatResponse response) {
        System.out.println("\n\nStreaming complete!");

        // Process tool calls from final response
        if (response.aiMessage().hasToolExecutionRequests()) {
            for (ToolExecutionRequest request : response.aiMessage().toolExecutionRequests()) {
                System.out.println("Tool: " + request.name());
                System.out.println("Args: " + request.arguments());
            }
        }
    }

    @Override
    public void onError(Throwable error) {
        System.err.println("Error: " + error.getMessage());
    }
};

// Use handler with tool specifications
ChatRequest request = ChatRequest.builder()
    .messages(UserMessage.from("What's the weather in Tokyo?"))
    .toolSpecifications(List.of(weatherTool))
    .build();

model.doChat(request, handler);

Model Names

public enum OpenAiChatModelName {
    // GPT-3.5 models
    GPT_3_5_TURBO("gpt-3.5-turbo"),
    GPT_3_5_TURBO_1106("gpt-3.5-turbo-1106"),
    GPT_3_5_TURBO_0125("gpt-3.5-turbo-0125"),
    GPT_3_5_TURBO_16K("gpt-3.5-turbo-16k"),

    // GPT-4 models
    GPT_4("gpt-4"),
    GPT_4_0613("gpt-4-0613"),
    GPT_4_32K("gpt-4-32k"),
    GPT_4_32K_0613("gpt-4-32k-0613"),

    // GPT-4 Turbo models
    GPT_4_TURBO_PREVIEW("gpt-4-turbo-preview"),
    GPT_4_1106_PREVIEW("gpt-4-1106-preview"),
    GPT_4_0125_PREVIEW("gpt-4-0125-preview"),
    GPT_4_TURBO("gpt-4-turbo"),
    GPT_4_TURBO_2024_04_09("gpt-4-turbo-2024-04-09"),

    // GPT-4 Omni models
    GPT_4_O("gpt-4o"),
    GPT_4_O_2024_05_13("gpt-4o-2024-05-13"),
    GPT_4_O_2024_08_06("gpt-4o-2024-08-06"),
    GPT_4_O_2024_11_20("gpt-4o-2024-11-20"),
    GPT_4_O_MINI("gpt-4o-mini"),
    GPT_4_O_MINI_2024_07_18("gpt-4o-mini-2024-07-18"),

    // O-series reasoning models
    O1("o1"),
    O1_2024_12_17("o1-2024-12-17"),
    O3("o3"),
    O3_2025_04_16("o3-2025-04-16"),
    O3_MINI("o3-mini"),
    O3_MINI_2025_01_31("o3-mini-2025-01-31"),
    O4_MINI("o4-mini"),
    O4_MINI_2025_04_16("o4-mini-2025-04-16"),

    // GPT-4.1 models
    GPT_4_1("gpt-4.1"),
    GPT_4_1_2025_04_14("gpt-4.1-2025-04-14"),
    GPT_4_1_MINI("gpt-4.1-mini"),
    GPT_4_1_MINI_2025_04_14("gpt-4.1-mini-2025-04-14"),
    GPT_4_1_NANO("gpt-4.1-nano"),
    GPT_4_1_NANO_2025_04_14("gpt-4.1-nano-2025-04-14"),

    // GPT-5 models
    GPT_5("gpt-5"),
    GPT_5_MINI("gpt-5-mini"),
    GPT_5_NANO("gpt-5-nano"),
    GPT_5_1("gpt-5.1");

    public String toString();
}

Types

ChatRequest

public class ChatRequest {
    public static Builder builder();

    public List<ChatMessage> messages();
    public List<ToolSpecification> toolSpecifications();
    public ToolChoice toolChoice();
    public ChatRequestParameters parameters();
}

public static class Builder {
    public Builder messages(List<ChatMessage> messages);
    public Builder messages(ChatMessage... messages);
    public Builder toolSpecifications(List<ToolSpecification> toolSpecifications);
    public Builder toolChoice(ToolChoice toolChoice);
    public Builder parameters(ChatRequestParameters parameters);
    public ChatRequest build();
}

ChatResponse

public class ChatResponse {
    public AiMessage aiMessage();
    public ChatResponseMetadata metadata();
}

ResponseFormat

public class ResponseFormat {
    public static ResponseFormat TEXT;
    public static ResponseFormat JSON;
    public static ResponseFormat jsonSchema(String jsonSchema);
    public static ResponseFormat jsonSchema(Class<?> clazz);
}

ToolSpecification

public class ToolSpecification {
    public static Builder builder();

    public String name();
    public String description();
    public Map<String, Object> parameters();
}

ToolExecutionRequest

public class ToolExecutionRequest {
    public String id();
    public String name();
    public String arguments();
}

ChatModelListener

public interface ChatModelListener {
    void onRequest(ChatModelRequestContext requestContext);
    void onResponse(ChatModelResponseContext responseContext);
    void onError(ChatModelErrorContext errorContext);
}

Configuration Options

Temperature

Controls randomness in responses. Range: 0.0 to 2.0

0.0: Deterministic, focused responses
1.0: Default, balanced creativity
2.0: Maximum randomness and creativity

Top P (Nucleus Sampling)

Alternative to temperature. Range: 0.0 to 1.0

Controls diversity via nucleus sampling
Only use one of temperature or topP

Max Completion Tokens

Maximum tokens in the generated response

Limits response length
Does not include prompt tokens

Stop Sequences

List of strings that stop generation when encountered

Up to 4 sequences
Useful for structured output

Presence Penalty

Reduces repetition of topics. Range: -2.0 to 2.0

Positive values discourage repeated topics
Negative values encourage repetition

Frequency Penalty

Reduces repetition of exact words. Range: -2.0 to 2.0

Positive values discourage word repetition
Negative values encourage repetition

Logit Bias

Adjust likelihood of specific tokens

Map of token ID to bias value (-100 to 100)
Use for precise output control

Seed

Integer seed for deterministic sampling

Same seed + parameters = same output
Useful for testing and reproducibility

Reasoning Effort

For o1/o3 reasoning models

Values: "low", "medium", "high"
Controls depth of reasoning process
Higher effort = more tokens, better results

Service Tier

OpenAI service tier selection

"auto": Default automatic selection
"default": Standard service tier

Parallel Tool Calls

Enable parallel execution of multiple tool calls

true: Multiple tools can be called simultaneously
false: Tools are called sequentially

Strict Tools

Enable strict validation of tool schemas

true: Enforce strict JSON schema validation
false: Permissive validation

Store

Whether to store the conversation for training

true: Store for future model improvements
false: Do not store (default for API)

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

chat-models.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Chat Models

Capabilities

OpenAiChatModel

OpenAiChatModelBuilder

Usage Example

Tool Calling Example

Structured Output Example

OpenAiStreamingChatModel

OpenAiStreamingChatModelBuilder

Usage Example

Streaming with Tool Calls

Model Names

Types

ChatRequest

ChatResponse

ResponseFormat

ToolSpecification

ToolExecutionRequest

ChatModelListener

Configuration Options

Temperature

Top P (Nucleus Sampling)

Max Completion Tokens

Stop Sequences

Presence Penalty

Frequency Penalty

Logit Bias

Seed

Reasoning Effort

Service Tier

Parallel Tool Calls

Strict Tools

Store

chat-models.mddocs/