ChatMessage.java

// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
//
// SPDX-License-Identifier: MIT

package net.ladenthin.llama.value;

import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.Optional;
import lombok.EqualsAndHashCode;
import org.jspecify.annotations.Nullable;

/**
 * A single message in a chat conversation: a role ({@code "user"}, {@code "assistant"},
 * {@code "system"}, or {@code "tool"}) and its textual content. Used by {@link net.ladenthin.llama.Session}
 * to accumulate conversation turns and by {@link net.ladenthin.llama.parameters.ChatRequest} / {@link ChatResponse}
 * for the typed chat API.
 * <p>
 * Tool-call turns have role {@code "assistant"}, possibly empty content, and a non-empty
 * {@link #getToolCalls()} list. Tool-result turns have role {@code "tool"}, the tool's
 * output as content, and {@link #getToolCallId()} pointing back at the originating call.
 * </p>
 * <p>
 * Multimodal turns carry a non-null {@link #getParts()} list of {@link ContentPart}s
 * (text and image references). When parts are present they take precedence over
 * {@link #getContent()} during serialization; the upstream OAI chat path
 * (see {@link net.ladenthin.llama.parameters.InferenceParameters#withMessages(java.util.List)}) emits an array-form
 * {@code content} field that the compiled-in {@code mtmd} pipeline understands.
 * </p>
 *
 * <p>{@code equals}/{@code hashCode} are generated by Lombok over all fields.
 * {@code toString} is intentionally handwritten (not Lombok-generated) so that
 * conversation traces in logs render as "{@code role: content}" or
 * "{@code role (tool_calls=N): content}" instead of a verbose field dump.</p>
 */
@EqualsAndHashCode
public final class ChatMessage {

    private final String role;
    private final String content;
    private final @Nullable String toolCallId;
    private final List<ToolCall> toolCalls;
    private final @Nullable List<ContentPart> parts;

    /**
     * Plain user/assistant/system message.
     *
     * @param role    the message role
     * @param content the message text
     */
    public ChatMessage(String role, String content) {
        this(role, content, null, Collections.<ToolCall>emptyList(), null);
    }

    /**
     * Full constructor including tool-related fields.
     *
     * @param role       the message role
     * @param content    the message text (may be empty for assistant tool-call turns)
     * @param toolCallId for tool-result turns ({@code role="tool"}), the id of the originating call; {@code null} otherwise
     * @param toolCalls  for assistant tool-call turns, the list of calls; empty otherwise
     */
    public ChatMessage(String role, String content, @Nullable String toolCallId, List<ToolCall> toolCalls) {
        this(role, content, toolCallId, toolCalls, null);
    }

    /**
     * Multimodal constructor: build a message whose content is a list of
     * {@link ContentPart}s (text and/or image references). The {@link #getContent()}
     * accessor returns the concatenation of the text parts for legacy callers that
     * cannot consume the array form.
     *
     * @param role  the message role
     * @param parts ordered list of content parts (must not be {@code null} or empty)
     */
    public ChatMessage(String role, List<ContentPart> parts) {
        this(
                role,
                concatText(requireNonNull(parts)),
                null,
                Collections.<ToolCall>emptyList(),
                Collections.unmodifiableList(new java.util.ArrayList<ContentPart>(requireNonEmpty(parts))));
    }

    private static List<ContentPart> requireNonNull(List<ContentPart> parts) {
        if (parts == null) {
            throw new IllegalArgumentException("parts must not be null");
        }
        return parts;
    }

    private ChatMessage(
            String role,
            String content,
            @Nullable String toolCallId,
            List<ToolCall> toolCalls,
            @Nullable List<ContentPart> parts) {
        this.role = role;
        this.content = content;
        this.toolCallId = toolCallId;
        this.toolCalls = toolCalls == null
                ? Collections.<ToolCall>emptyList()
                : Collections.unmodifiableList(new java.util.ArrayList<ToolCall>(toolCalls));
        this.parts = parts;
    }

    private static List<ContentPart> requireNonEmpty(List<ContentPart> parts) {
        if (parts.isEmpty()) {
            throw new IllegalArgumentException("parts must not be empty (size=" + parts.size() + ")");
        }
        return parts;
    }

    private static String concatText(Iterable<ContentPart> parts) {
        if (parts == null) return "";
        StringBuilder sb = new StringBuilder();
        for (ContentPart p : parts) {
            if (p.getType() == ContentPart.Type.TEXT) {
                if (sb.length() > 0) sb.append('\n');
                sb.append(p.getText());
            }
        }
        return sb.toString();
    }

    /**
     * Factory for a tool-result turn.
     *
     * @param toolCallId the id of the originating tool call
     * @param content    the tool's output as a string
     * @return a {@link ChatMessage} with role {@code "tool"}
     */
    public static ChatMessage toolResult(String toolCallId, String content) {
        return new ChatMessage("tool", content, toolCallId, Collections.<ToolCall>emptyList());
    }

    /**
     * Factory for an assistant turn that issues tool calls.
     *
     * @param content   optional reasoning text accompanying the tool calls (may be empty)
     * @param toolCalls the tool calls to issue
     * @return a {@link ChatMessage} with role {@code "assistant"}
     */
    public static ChatMessage assistantToolCalls(String content, List<ToolCall> toolCalls) {
        return new ChatMessage("assistant", content == null ? "" : content, null, toolCalls);
    }

    /**
     * Convenience factory for a {@code "user"} turn mixing text and one or more
     * images. Equivalent to {@code new ChatMessage("user", parts)}.
     *
     * @param parts ordered text and image parts; at least one is required
     * @return a multimodal user message
     */
    public static ChatMessage userMultimodal(ContentPart... parts) {
        return new ChatMessage("user", Arrays.asList(parts));
    }

    /**
     * Message role accessor.
     * @return the message role string
     */
    public String getRole() {
        return role;
    }

    /**
     * Message content accessor.
     * @return the message text content
     */
    public String getContent() {
        return content;
    }

    /**
     * Tool-call id for tool-result turns.
     * @return the originating tool call id, or {@link Optional#empty()} for non-tool messages
     */
    public Optional<String> getToolCallId() {
        return Optional.ofNullable(toolCallId);
    }

    /**
     * Tool calls issued by an assistant turn.
     * @return the calls list, never {@code null}; empty when the message is not a tool-call turn
     */
    public List<ToolCall> getToolCalls() {
        // Return a fresh unmodifiable view (mirrors getParts) so the stored list is never
        // exposed directly — the caller cannot mutate this value type's internal state.
        return Collections.unmodifiableList(toolCalls);
    }

    /**
     * Multimodal content parts accessor.
     * @return an unmodifiable list of text and image parts, or {@link Optional#empty()}
     *         for legacy text-only messages built via {@link #ChatMessage(String, String)}
     */
    public Optional<List<ContentPart>> getParts() {
        return parts == null ? Optional.empty() : Optional.of(Collections.unmodifiableList(parts));
    }

    /**
     * Whether this message carries multimodal parts (i.e. was constructed via
     * {@link #ChatMessage(String, List)} or {@link #userMultimodal(ContentPart...)}).
     * @return {@code true} when {@link #getParts()} is non-empty
     */
    public boolean hasParts() {
        return parts != null;
    }

    @Override
    public String toString() {
        if (!toolCalls.isEmpty()) return role + " (tool_calls=" + toolCalls.size() + "): " + content;
        if (toolCallId != null) return role + " (tool_call_id=" + toolCallId + "): " + content;
        return role + ": " + content;
    }
}