Chat Models

public class WatsonxChatModel implements dev.langchain4j.model.chat.ChatModel {
    public static Builder builder();
    public ChatResponse doChat(ChatRequest chatRequest);
    public List<ChatModelListener> listeners();
    public ChatRequestParameters defaultRequestParameters();
    public Set<Capability> supportedCapabilities();
    public WatsonxRestApi getClient();
    public String getModelId();
    public String getProjectId();
    public String getSpaceId();
    public String getVersion();
}

import io.quarkiverse.langchain4j.watsonx.WatsonxChatModel;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.model.chat.response.ChatResponse;
import java.net.URL;

// Build model
WatsonxChatModel model = WatsonxChatModel.builder()
    .modelId("meta-llama/llama-4-maverick-17b-128e-instruct-fp8")
    .url(new URL("https://us-south.ml.cloud.ibm.com"))
    .projectId("your-project-id")
    .tokenGenerator(tokenGenerator)
    .temperature(0.7)
    .maxTokens(2048)
    .build();

// Single-turn conversation
ChatResponse response = model.chat(UserMessage.from("What is the capital of France?"));
String answer = response.aiMessage().text();

// Multi-turn conversation with system message
ChatResponse response2 = model.chat(
    SystemMessage.from("You are a helpful geography tutor"),
    UserMessage.from("What is the capital of France?")
);

import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.data.message.ChatMessage;
import java.util.ArrayList;
import java.util.List;

List<ChatMessage> messages = new ArrayList<>();
messages.add(SystemMessage.from("You are a helpful assistant"));
messages.add(UserMessage.from("What is 2+2?"));

ChatResponse response1 = model.chat(messages);
messages.add(response1.aiMessage());

// Continue conversation
messages.add(UserMessage.from("What about 3+3?"));
ChatResponse response2 = model.chat(messages);

public class WatsonxStreamingChatModel implements dev.langchain4j.model.chat.StreamingChatModel {
    public static Builder builder();
    public void doChat(ChatRequest chatRequest, StreamingChatResponseHandler handler);
    public List<ChatModelListener> listeners();
    public ChatRequestParameters defaultRequestParameters();
    public Set<Capability> supportedCapabilities();
    public WatsonxRestApi getClient();
    public String getModelId();
    public String getProjectId();
    public String getSpaceId();
    public String getVersion();
}

import io.quarkiverse.langchain4j.watsonx.WatsonxStreamingChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.output.StreamingResponseHandler;
import dev.langchain4j.model.chat.response.StreamingChatResponseHandler;

WatsonxStreamingChatModel streamingModel = WatsonxStreamingChatModel.builder()
    .modelId("meta-llama/llama-4-maverick-17b-128e-instruct-fp8")
    .url(new URL("https://us-south.ml.cloud.ibm.com"))
    .projectId("your-project-id")
    .tokenGenerator(tokenGenerator)
    .temperature(0.7)
    .maxTokens(2048)
    .build();

streamingModel.chat(
    ChatRequest.builder()
        .messages(List.of(UserMessage.from("Write a short story about a robot")))
        .build(),
    new StreamingChatResponseHandler() {
        private final StringBuilder fullResponse = new StringBuilder();

        @Override
        public void onPartialResponse(String partialResponse) {
            fullResponse.append(partialResponse);
            System.out.print(partialResponse);
        }

        @Override
        public void onComplete(ChatResponse response) {
            System.out.println("\nTokens used: " + response.tokenUsage().totalTokens());
        }

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

public static class Builder extends Watsonx.Builder<WatsonxChatModel, Builder> {
    // Inherited base parameters
    public Builder modelId(String modelId);
    public Builder version(String version);
    public Builder spaceId(String spaceId);
    public Builder projectId(String projectId);
    public Builder url(URL url);
    public Builder timeout(Duration timeout);
    public Builder tokenGenerator(TokenGenerator tokenGenerator);
    public Builder logRequests(boolean logRequests);
    public Builder logResponses(boolean logResponses);
    public Builder logCurl(boolean logCurl);
    public Builder listeners(List<ChatModelListener> listeners);

    // Chat-specific parameters
    public Builder toolChoice(ToolChoice toolChoice);
    public Builder toolChoiceName(String toolChoiceName);
    public Builder frequencyPenalty(Double frequencyPenalty);
    public Builder logprobs(Boolean logprobs);
    public Builder topLogprobs(Integer topLogprobs);
    public Builder maxTokens(Integer maxTokens);
    public Builder n(Integer n);
    public Builder presencePenalty(Double presencePenalty);
    public Builder seed(Integer seed);
    public Builder stop(List<String> stop);
    public Builder temperature(Double temperature);
    public Builder topP(Double topP);
    public Builder responseFormat(ResponseFormat responseFormat);
    public Builder responseFormatText(String responseFormatText);

    public WatsonxChatModel build();
}

WatsonxChatModel model = WatsonxChatModel.builder()
    .modelId("meta-llama/llama-4-maverick-17b-128e-instruct-fp8")
    .url(new URL("https://us-south.ml.cloud.ibm.com"))
    .projectId("abc123")
    .tokenGenerator(tokenGenerator)
    .temperature(0.8)
    .maxTokens(2048)
    .frequencyPenalty(0.5)
    .presencePenalty(0.3)
    .stop(List.of("\n\n", "END"))
    .seed(42)
    .toolChoice(ToolChoice.AUTO)
    .logRequests(true)
    .logResponses(true)
    .build();

import dev.langchain4j.agent.tool.Tool;

public class WeatherTools {
    @Tool("Get current weather for a city")
    public String getCurrentWeather(
        @P("City name") String city,
        @P("Country code") String country
    ) {
        // Implementation
        return "Temperature: 22°C, Condition: Sunny";
    }

    @Tool("Get weather forecast for next 5 days")
    public String getForecast(
        @P("City name") String city
    ) {
        // Implementation
        return "5-day forecast data...";
    }
}

import dev.langchain4j.service.AiServices;

interface WeatherAssistant {
    String chat(String userMessage);
}

WeatherAssistant assistant = AiServices.builder(WeatherAssistant.class)
    .chatModel(chatModel)
    .tools(new WeatherTools())
    .build();

String response = assistant.chat("What's the weather in Paris?");
// Model will automatically call getCurrentWeather("Paris", "FR") and use result

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

ToolSpecification weatherTool = ToolSpecification.builder()
    .name("get_weather")
    .description("Get current weather for a city")
    .addParameter("city", "string", "City name")
    .addParameter("country", "string", "Country code")
    .build();

ChatRequest request = ChatRequest.builder()
    .messages(List.of(UserMessage.from("What's the weather in Paris?")))
    .toolSpecifications(List.of(weatherTool))
    .build();

ChatResponse response = chatModel.chat(request);

// Check if model wants to call tool
if (response.aiMessage().hasToolExecutionRequests()) {
    for (ToolExecutionRequest toolRequest : response.aiMessage().toolExecutionRequests()) {
        // Execute tool
        String result = executeWeatherTool(
            toolRequest.arguments().get("city"),
            toolRequest.arguments().get("country")
        );

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

        ChatResponse finalResponse = chatModel.chat(messages);
    }
}

import dev.langchain4j.model.chat.request.ResponseFormat;
import dev.langchain4j.model.chat.request.json.JsonSchema;

// Define JSON schema
String schemaJson = """
{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"},
    "email": {"type": "string", "format": "email"}
  },
  "required": ["name", "age"],
  "additionalProperties": false
}
""";

JsonSchema schema = JsonSchema.builder()
    .name("user_profile")
    .schema(schemaJson)
    .build();

// Use schema with model
WatsonxChatModel model = WatsonxChatModel.builder()
    .modelId("meta-llama/llama-4-maverick-17b-128e-instruct-fp8")
    .url(url)
    .projectId(projectId)
    .tokenGenerator(tokenGenerator)
    .responseFormat(ResponseFormat.jsonSchema(schema))
    .build();

ChatResponse response = model.chat(
    UserMessage.from("Extract profile: John Doe is 30 years old, email john@example.com")
);

String jsonOutput = response.aiMessage().text();
// Output: {"name": "John Doe", "age": 30, "email": "john@example.com"}

WatsonxChatModel model = WatsonxChatModel.builder()
    .responseFormat(ResponseFormat.JSON)
    .build();

ChatResponse response = model.chat(
    UserMessage.from("Return a JSON object with fields: title, author, year")
);
// Output will be valid JSON object

import dev.langchain4j.model.chat.listener.ChatModelListener;
import dev.langchain4j.model.chat.listener.ChatModelRequest;
import dev.langchain4j.model.chat.listener.ChatModelResponse;

public class LoggingChatListener implements ChatModelListener {
    @Override
    public void onRequest(ChatModelRequest request) {
        System.out.println("Request: " + request.messages().size() + " messages");
        System.out.println("Model: " + request.model());
    }

    @Override
    public void onResponse(ChatModelResponse response) {
        System.out.println("Response: " + response.aiMessage().text());
        System.out.println("Tokens: " + response.tokenUsage());
        System.out.println("Finish reason: " + response.finishReason());
    }

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

// Add listener to model
WatsonxChatModel model = WatsonxChatModel.builder()
    .listeners(List.of(new LoggingChatListener()))
    .build();

quarkus.langchain4j.watsonx.base-url=https://us-south.ml.cloud.ibm.com
quarkus.langchain4j.watsonx.api-key=your-api-key
quarkus.langchain4j.watsonx.project-id=your-project-id

# Chat model configuration
quarkus.langchain4j.watsonx.chat-model.model-name=meta-llama/llama-4-maverick-17b-128e-instruct-fp8
quarkus.langchain4j.watsonx.chat-model.temperature=0.7
quarkus.langchain4j.watsonx.chat-model.max-tokens=2048
quarkus.langchain4j.watsonx.chat-model.tool-choice=auto
quarkus.langchain4j.watsonx.chat-model.frequency-penalty=0.5
quarkus.langchain4j.watsonx.chat-model.presence-penalty=0.3

import jakarta.inject.Inject;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.StreamingChatModel;

@ApplicationScoped
public class ChatService {
    @Inject
    ChatModel chatModel;

    @Inject
    StreamingChatModel streamingChatModel;

    public String askQuestion(String question) {
        return chatModel.chat(UserMessage.from(question))
            .aiMessage()
            .text();
    }
}

public abstract class Watsonx {
    public WatsonxRestApi getClient();
    public String getModelId();
    public String getProjectId();
    public String getSpaceId();
    public String getVersion();

    public static abstract class Builder<M extends Watsonx, B extends Builder<M, B>> {
        public B modelId(String modelId);
        public B version(String version);
        public B spaceId(String spaceId);
        public B projectId(String projectId);
        public B url(URL url);
        public B timeout(Duration timeout);
        public B tokenGenerator(TokenGenerator tokenGenerator);
        public B logRequests(boolean logRequests);
        public B logResponses(boolean logResponses);
        public B logCurl(boolean logCurl);
        public abstract M build();
    }
}

public class TokenGenerator {
    public TokenGenerator(URL iamUrl, Duration timeout, String grantType, String apiKey);
    public Uni<String> generate();
}

import io.quarkiverse.langchain4j.watsonx.runtime.TokenGenerator;
import java.net.URL;
import java.time.Duration;

TokenGenerator tokenGen = new TokenGenerator(
    new URL("https://iam.cloud.ibm.com"),
    Duration.ofSeconds(30),
    "urn:ibm:params:oauth:grant-type:apikey",
    "your-ibm-cloud-api-key"
);

// Token is generated and cached automatically
WatsonxChatModel model = WatsonxChatModel.builder()
    .tokenGenerator(tokenGen)
    .build();

// Request
public class ChatRequest {
    List<ChatMessage> messages();
    List<ToolSpecification> toolSpecifications();
    ChatRequestParameters parameters();
}

// Response
public class ChatResponse {
    AiMessage aiMessage();
    TokenUsage tokenUsage();
    FinishReason finishReason();
    ChatResponseMetadata metadata();
}

// Token usage
public class TokenUsage {
    Integer inputTokenCount();
    Integer outputTokenCount();
    Integer totalTokenCount();
}

// Finish reason
public enum FinishReason {
    STOP,           // Natural completion
    LENGTH,         // Max tokens reached
    TOOL_EXECUTION, // Tool call requested
    CONTENT_FILTER, // Content filtered
    OTHER
}

public interface ChatMessage {
    MessageType type();
}

public class SystemMessage implements ChatMessage {
    public static SystemMessage from(String text);
    public String text();
}

public class UserMessage implements ChatMessage {
    public static UserMessage from(String text);
    public static UserMessage from(String text, List<Content> contents);
    public String text();
    public List<Content> contents();
}

public class AiMessage implements ChatMessage {
    public static AiMessage from(String text);
    public String text();
    public boolean hasToolExecutionRequests();
    public List<ToolExecutionRequest> toolExecutionRequests();
}

public class ToolExecutionResultMessage implements ChatMessage {
    public static ToolExecutionResultMessage from(ToolExecutionRequest request, String result);
    public String id();
    public String toolName();
    public String text();
}

public interface Content {
    ContentType type();
}

public class TextContent implements Content {
    public static TextContent from(String text);
    public String text();
}

public class ImageContent implements Content {
    public static ImageContent from(String url);
    public static ImageContent from(String url, ImageContentDetail detail);
    public String url();
    public ImageContentDetail detail();
}

public enum ImageContentDetail {
    AUTO, LOW, HIGH
}

public class ToolSpecification {
    String name();
    String description();
    Map<String, Object> parameters();

    public static Builder builder() {
        return new Builder();
    }

    public static class Builder {
        public Builder name(String name);
        public Builder description(String description);
        public Builder addParameter(String name, String type, String description);
        public Builder parameters(Map<String, Object> parameters);
        public ToolSpecification build();
    }
}

public class ToolExecutionRequest {
    String id();
    String name();
    Map<String, Object> arguments();
}

public enum ToolChoice {
    AUTO,     // Model decides whether to use tools
    REQUIRED  // Model must use at least one tool
}

public enum Capability {
    JSON_SCHEMA_RESPONSE_FORMAT  // Supports JSON schema validation
}