refactor(ChatRequest): immutable + wither/append pattern

Convert ChatRequest from a mutable fluent builder into a fully immutable
value class with a functional "wither / appender" API:

  ChatRequest.empty()
      .appendMessage("user", "hi")
      .withMaxToolRounds(2)
      .withInferenceCustomizer(p -> p.setSeed(1));

Each modification routes through a single private all-args constructor
with one field replaced, allocating a new ChatRequest. The original is
never touched, so a caller can safely hold an intermediate request and
derive variants without hidden state changes.

Notable side effect: this fixes a hidden mutation bug in
LlamaModel.chatWithTools(). The previous agent loop mutated the caller's
ChatRequest across rounds (adding the assistant turn + each tool result
to the same builder). The loop is now rebound to a local `current` that
is replaced on every append, preserving the caller's request.

Tests:
- New ChatRequestTest documents the immutability + value-equality
  contract in 18 cases across four @nested groups (immutability,
  equality, validation, JSON-build read-only).
- LlamaModelTest and ChatResponseTest call sites migrated from
  `new ChatRequest()...addMessage(...)` to
  `ChatRequest.empty()...appendMessage(...)`.

SpotBugs:
- IMC_NO_EQUALS goal cleared at source (the class is now a true value
  object with Lombok @EqualsAndHashCode by value).
- EI_EXPOSE_REP on getMessages()/getTools() suppressed with explicit
  rationale: the fields ARE Collections.unmodifiableList views; the
  test suite verifies that mutation attempts throw
  UnsupportedOperationException, so the finding is a false positive.

Author: claude

spotbugs-exclude.xml

@@ -233,4 +233,24 @@ SPDX-License-Identifier: MIT
         <Bug pattern="OPM_OVERLY_PERMISSIVE_METHOD"/>
     </Match>
 
+    <!--
+        ChatRequest is an immutable value class. Its messages/tools fields
+        are stored as Collections.unmodifiableList(...) views, so the
+        getters CANNOT actually leak the internal representation: any
+        attempt to mutate the returned list throws UnsupportedOperationException
+        (covered by ChatRequestTest.messagesAccessorIsUnmodifiable /
+        toolsAccessorIsUnmodifiable). SpotBugs flags every "return this.field"
+        from a non-array reference field as EI_EXPOSE_REP without tracking
+        whether the field was unmodifiable-wrapped at construction time;
+        the wrapping is verified by tests, so the finding is a false positive.
+    -->
+    <Match>
+        <Class name="net.ladenthin.llama.ChatRequest"/>
+        <Bug pattern="EI_EXPOSE_REP"/>
+        <Or>
+            <Method name="getMessages"/>
+            <Method name="getTools"/>
+        </Or>
+    </Match>
+
 </FindBugsFilter>

src/main/java/net/ladenthin/llama/ChatRequest.java

@@ -13,149 +13,253 @@
 import java.util.List;
 import java.util.Optional;
 import java.util.function.Consumer;
+import lombok.EqualsAndHashCode;
 import lombok.ToString;
 import org.jspecify.annotations.Nullable;
 
 /**
- * Builder for a typed chat completion call.
- * <p>
- * Bundles the conversation messages, optional tool definitions, an optional
- * {@code tool_choice} hint, and an {@link InferenceParameters} customizer that gets
- * applied to the underlying request just before invocation. Built with the fluent
- * setters; consumed by {@link LlamaModel#chat(ChatRequest)} and
+ * Immutable typed chat-completion request, populated through a functional
+ * "wither / appender" API.
+ *
+ * <h2>Design</h2>
+ *
+ * <p>The request carries the conversation messages, optional tool definitions,
+ * an optional {@code tool_choice} hint, and an {@link InferenceParameters}
+ * customiser applied to the underlying request just before invocation. The
+ * type is consumed by {@link LlamaModel#chat(ChatRequest)} and
  * {@link LlamaModel#chatWithTools(ChatRequest, java.util.Map)}.
- * </p>
  *
- * <p>{@code toString} is generated by Lombok over the request state fields. The
- * {@code paramsCustomizer} {@link Consumer} is excluded because lambda equality is
- * implementation-defined (compiler-synthesized class identity), not value-shaped,
- * and the rendered identity hash is noise in a request dump. {@code equals}/
- * {@code hashCode} are intentionally NOT generated: this is a mutable builder, not
- * a value object.
+ * <p>All instances are <b>immutable</b>: every field is {@code final} and the
+ * stored lists are wrapped with {@link Collections#unmodifiableList(List)}.
+ * Modification methods return a <b>new</b> {@code ChatRequest} instance with
+ * the requested change applied; the original is untouched. This makes
+ * {@code ChatRequest} safe to share across threads and gives it a meaningful
+ * value-equality semantics (two requests with the same content compare
+ * equal regardless of identity).
+ *
+ * <h2>Construction patterns</h2>
+ *
+ * <p>Use {@link #empty()} as the entry point, then chain {@code append*}
+ * (for list fields) and {@code with*} (for scalar fields):
+ *
+ * <pre>{@code
+ * ChatRequest req = ChatRequest.empty()
+ *         .appendMessage("system", "be terse")
+ *         .appendMessage("user", "two plus two?")
+ *         .withMaxToolRounds(2)
+ *         .withInferenceCustomizer(p -> p.setNPredict(8).setSeed(1));
+ * }</pre>
+ *
+ * <p>Each call allocates a new {@code ChatRequest}. The cost is intentional:
+ * the API is functional, so a caller can hold an intermediate request and
+ * derive variants without worrying about hidden state changes.
+ *
+ * <h2>Equality</h2>
+ *
+ * <p>{@code @EqualsAndHashCode} compares messages, tools, {@code toolChoice},
+ * and {@code maxToolRounds} by value. The {@code paramsCustomizer}
+ * {@link Consumer} is <b>excluded</b> from equality: lambdas have
+ * compiler-synthesised identity equality which is not value-shaped, so
+ * including it would mean two structurally-identical requests with the same
+ * customiser source code rarely compare equal — surprising for the typical
+ * snapshot-testing and caching use cases. The customiser is also excluded
+ * from {@link ToString} for the same reason (the rendered hash is noise).
  */
 @ToString
+@EqualsAndHashCode
 public final class ChatRequest {
 
     private static final ObjectMapper MAPPER = new ObjectMapper();
 
-    private final List<ChatMessage> messages = new ArrayList<ChatMessage>();
-    private final List<ToolDefinition> tools = new ArrayList<ToolDefinition>();
-    private @Nullable String toolChoice;
-    private int maxToolRounds = 8;
+    /**
+     * Default {@code maxToolRounds} when the caller does not override it via
+     * {@link #withMaxToolRounds(int)}. Mirrors the prior mutable builder's default.
+     */
+    public static final int DEFAULT_MAX_TOOL_ROUNDS = 8;
+
+    private static final ChatRequest EMPTY = new ChatRequest(
+            Collections.<ChatMessage>emptyList(),
+            Collections.<ToolDefinition>emptyList(),
+            null,
+            DEFAULT_MAX_TOOL_ROUNDS,
+            null);
+
+    private final List<ChatMessage> messages;
+    private final List<ToolDefinition> tools;
+    private final @Nullable String toolChoice;
+    private final int maxToolRounds;
 
     // Lambda Consumer — toString is the implementation hash, not useful in logs;
-    // equality is compiler-synthesized class identity, not value-shaped.
+    // equality is compiler-synthesised class identity, not value-shaped.
     @ToString.Exclude
-    private @Nullable Consumer<InferenceParameters> paramsCustomizer;
+    @EqualsAndHashCode.Exclude
+    private final @Nullable Consumer<InferenceParameters> paramsCustomizer;
+
+    /**
+     * All-args constructor. Private because callers should enter via {@link #empty()}
+     * and derive variants via the {@code append*} / {@code with*} methods. Each
+     * variant call routes through this same constructor with one field replaced.
+     */
+    private ChatRequest(
+            List<ChatMessage> messages,
+            List<ToolDefinition> tools,
+            @Nullable String toolChoice,
+            int maxToolRounds,
+            @Nullable Consumer<InferenceParameters> paramsCustomizer) {
+        this.messages = messages;
+        this.tools = tools;
+        this.toolChoice = toolChoice;
+        this.maxToolRounds = maxToolRounds;
+        this.paramsCustomizer = paramsCustomizer;
+    }
 
-    /** Construct an empty request; populate via the setters. */
-    public ChatRequest() {
-        // empty
+    /**
+     * Returns the empty request — no messages, no tools, {@code toolChoice}
+     * absent, {@code maxToolRounds} = {@value #DEFAULT_MAX_TOOL_ROUNDS}, no
+     * customiser. Acts as the starting point for chained derivations.
+     *
+     * @return the empty request
+     */
+    public static ChatRequest empty() {
+        return EMPTY;
     }
 
+    // -----------------------------------------------------------------------
+    // List appends — each returns a new request with one entry added.
+    // -----------------------------------------------------------------------
+
     /**
-     * Append a message to the conversation.
+     * Returns a new request with {@code message} appended to the conversation.
+     *
      * @param message the message to append
-     * @return this builder
+     * @return a new request with the appended message; this request is unchanged
      */
-    public ChatRequest addMessage(ChatMessage message) {
-        messages.add(message);
-        return this;
+    public ChatRequest appendMessage(ChatMessage message) {
+        List<ChatMessage> next = new ArrayList<ChatMessage>(messages.size() + 1);
+        next.addAll(messages);
+        next.add(message);
+        return new ChatRequest(
+                Collections.unmodifiableList(next),
+                tools,
+                toolChoice,
+                maxToolRounds,
+                paramsCustomizer);
     }
 
     /**
-     * Convenience for adding a system/user/assistant turn.
-     * @param role    the role
-     * @param content the content
-     * @return this builder
+     * Convenience for {@link #appendMessage(ChatMessage)} that wraps a role +
+     * content pair into a new {@link ChatMessage} and appends it.
+     *
+     * @param role    the role (e.g. {@code "system"}, {@code "user"}, {@code "assistant"})
+     * @param content the message content
+     * @return a new request with the appended message; this request is unchanged
      */
-    public ChatRequest addMessage(String role, String content) {
-        messages.add(new ChatMessage(role, content));
-        return this;
+    public ChatRequest appendMessage(String role, String content) {
+        return appendMessage(new ChatMessage(role, content));
     }
 
     /**
-     * Append a tool definition.
-     * @param tool the tool definition to expose to the model
-     * @return this builder
+     * Returns a new request with {@code tool} added to the tool registry.
+     *
+     * @param tool the tool to expose to the model
+     * @return a new request with the appended tool; this request is unchanged
      */
-    public ChatRequest addTool(ToolDefinition tool) {
-        tools.add(tool);
-        return this;
+    public ChatRequest appendTool(ToolDefinition tool) {
+        List<ToolDefinition> next = new ArrayList<ToolDefinition>(tools.size() + 1);
+        next.addAll(tools);
+        next.add(tool);
+        return new ChatRequest(
+                messages,
+                Collections.unmodifiableList(next),
+                toolChoice,
+                maxToolRounds,
+                paramsCustomizer);
     }
 
+    // -----------------------------------------------------------------------
+    // Scalar withers — each returns a new request with one field replaced.
+    // -----------------------------------------------------------------------
+
     /**
-     * Set the {@code tool_choice} hint: typically {@code "auto"}, {@code "none"}, or
-     * {@code "required"}. Defaults to absent (server default applies).
+     * Returns a new request with the {@code tool_choice} hint replaced.
      *
-     * @param toolChoice the hint string, or {@code null} to clear
-     * @return this builder
+     * @param newToolChoice the hint string (typically {@code "auto"}, {@code "none"}, or
+     *     {@code "required"}), or {@code null} to clear
+     * @return a new request with the hint replaced; this request is unchanged
      */
-    public ChatRequest setToolChoice(@Nullable String toolChoice) {
-        this.toolChoice = toolChoice;
-        return this;
+    public ChatRequest withToolChoice(@Nullable String newToolChoice) {
+        return new ChatRequest(messages, tools, newToolChoice, maxToolRounds, paramsCustomizer);
     }
 
     /**
-     * Set the maximum number of agent-loop rounds for
-     * {@link LlamaModel#chatWithTools(ChatRequest, java.util.Map)}. A round is one
-     * model call followed by zero or more tool invocations. Default {@code 8}.
+     * Returns a new request with the agent-loop round cap replaced.
      *
-     * @param maxToolRounds the round cap (must be positive)
-     * @return this builder
+     * @param newMaxToolRounds the new round cap (must be {@code > 0})
+     * @return a new request with the cap replaced; this request is unchanged
+     * @throws IllegalArgumentException if {@code newMaxToolRounds} is non-positive
      */
-    public ChatRequest setMaxToolRounds(int maxToolRounds) {
-        if (maxToolRounds <= 0) {
-            throw new IllegalArgumentException("maxToolRounds must be > 0 but was " + maxToolRounds);
+    public ChatRequest withMaxToolRounds(int newMaxToolRounds) {
+        if (newMaxToolRounds <= 0) {
+            throw new IllegalArgumentException(
+                    "maxToolRounds must be > 0 but was " + newMaxToolRounds);
         }
-        this.maxToolRounds = maxToolRounds;
-        return this;
+        return new ChatRequest(messages, tools, toolChoice, newMaxToolRounds, paramsCustomizer);
     }
 
     /**
-     * Register a callback that customizes the {@link InferenceParameters} (e.g.
-     * {@code setNPredict}, {@code setTemperature}) right before each request is sent.
+     * Returns a new request with the inference-parameter customiser replaced.
      *
-     * @param customizer the customizer; {@code null} clears any prior customizer
-     * @return this builder
+     * @param newCustomizer the customiser; {@code null} clears any prior customiser
+     * @return a new request with the customiser replaced; this request is unchanged
      */
-    public ChatRequest setInferenceCustomizer(@Nullable Consumer<InferenceParameters> customizer) {
-        this.paramsCustomizer = customizer;
-        return this;
+    public ChatRequest withInferenceCustomizer(@Nullable Consumer<InferenceParameters> newCustomizer) {
+        return new ChatRequest(messages, tools, toolChoice, maxToolRounds, newCustomizer);
     }
 
+    // -----------------------------------------------------------------------
+    // Accessors.
+    // -----------------------------------------------------------------------
+
     /**
      * Messages accessor.
-     * @return an unmodifiable view of the messages added so far
+     *
+     * @return an unmodifiable view of the messages accumulated so far
      */
     public List<ChatMessage> getMessages() {
-        return Collections.unmodifiableList(messages);
+        return messages;
     }
 
     /**
      * Tools accessor.
-     * @return an unmodifiable view of the tool definitions added so far
+     *
+     * @return an unmodifiable view of the tool definitions accumulated so far
      */
     public List<ToolDefinition> getTools() {
-        return Collections.unmodifiableList(tools);
+        return tools;
     }
 
     /**
-     * Tool choice accessor.
+     * Tool-choice hint accessor.
+     *
      * @return the {@code tool_choice} hint, or {@link Optional#empty()} when unset
      */
     public Optional<String> getToolChoice() {
         return Optional.ofNullable(toolChoice);
     }
 
     /**
-     * Max rounds accessor.
+     * Agent-loop round cap accessor.
+     *
      * @return the agent-loop round cap
      */
     public int getMaxToolRounds() {
         return maxToolRounds;
     }
 
+    // -----------------------------------------------------------------------
+    // JSON build helpers — read-only, do not mutate this request.
+    // -----------------------------------------------------------------------
+
     /**
      * Build the OAI-style {@code messages} array as a JSON string. Each entry carries
      * role and content; assistant tool-call turns add a {@code tool_calls} array; tool-
@@ -215,7 +319,7 @@ public Optional<String> buildToolsJson() {
     }
 
     /**
-     * Apply the optional customizer to an {@link InferenceParameters} instance.
+     * Apply the optional customiser to an {@link InferenceParameters} instance.
      * Package-private; called by {@link LlamaModel}.
      *
      * @param params the parameters to mutate

src/main/java/net/ladenthin/llama/LlamaModel.java

@@ -563,7 +563,8 @@ public ChatResponse chatWithTools(ChatRequest request, java.util.Map<String, Too
             throw new IllegalArgumentException("ChatRequest.maxToolRounds must be >= 1 (got " + maxRounds + "); "
                     + "chatWithTools always issues at least one chat call.");
         }
-        ChatResponse last = chat(request);
+        ChatRequest current = request;
+        ChatResponse last = chat(current);
         for (int round = 1; round < maxRounds; round++) {
             Optional<ChatMessage> assistantOpt = last.getFirstMessage();
             // NOTE: inline !isPresent() here (not compatibilityHelper.isEmpty) so NullAway's
@@ -572,7 +573,7 @@ public ChatResponse chatWithTools(ChatRequest request, java.util.Map<String, Too
                 return last;
             }
             ChatMessage assistant = assistantOpt.get();
-            request.addMessage(assistant);
+            current = current.appendMessage(assistant);
             for (ToolCall call : assistant.getToolCalls()) {
                 ToolHandler handler = handlers.get(call.getName());
                 String result;
@@ -588,9 +589,9 @@ public ChatResponse chatWithTools(ChatRequest request, java.util.Map<String, Too
                                 + "}";
                     }
                 }
-                request.addMessage(ChatMessage.toolResult(call.getId(), result));
+                current = current.appendMessage(ChatMessage.toolResult(call.getId(), result));
             }
-            last = chat(request);
+            last = chat(current);
         }
         return last;
     }