refactor(InferenceParameters): immutable + wither/append pattern

Convert InferenceParameters from a mutable fluent builder into a fully
immutable value class with a functional wither API:

  InferenceParameters params = InferenceParameters.of("two plus two?")
          .withNPredict(8)
          .withSeed(1)
          .withTemperature(0.2f);

The parent JsonParameters base is reshaped to match: parameters map is
final and Collections.unmodifiableMap-wrapped, and the helpers
putScalar / putEnum / putOptionalJson are replaced by withScalar /
withEnum / withOptionalJson / withRaw, all of which allocate a new
subclass instance through the abstract withParameters(Map) factory
hook. ModelParameters extends a different parent (CliParameters) and
is unchanged — it is constructed once and consumed once, so the
immutability refactor brings no correctness payoff there but ~250 test
line changes; deliberately skipped to keep this commit focused.

Hidden mutation bug fixed: LlamaModel.complete /
completeWithStats / chatComplete and the cancellable complete-with-token
variant silently called parameters.setStream(true|false) on the
caller's instance. They now bind a local derivation via withStream so
the caller's parameters object is never touched. Same pattern applied
to LlamaIterator.

API breaks (intentional, alongside the parameter rename):
- Consumer<InferenceParameters> -> UnaryOperator<InferenceParameters>
  in Session and ChatRequest. The customiser must return its
  transformed result because the input is immutable; lambdas like
  `p -> p.withSeed(1).withNPredict(8)` keep working with the
  expression-form return.
- ChatRequest.applyCustomizer now returns InferenceParameters instead
  of being a void mutator; callers (only LlamaModel.chat) updated.

Tests:
- JsonParametersTest rewritten to cover the new wither helpers
  (withScalar / withEnum / withRaw / withOptionalJson) plus the
  unmodifiable-map invariant. The legacy CliParameters putScalar /
  putEnum tests are preserved unchanged because ModelParameters still
  uses them.
- Bulk-renamed setX -> withX across the entire test surface
  (InferenceParametersTest 71+, ChatAdvancedTest 84, LlamaModelTest 90,
  ChatScenarioTest 64, MemoryManagementTest 40, plus smaller files and
  all examples), preserving ModelParameters' fluent setX chains where
  the overlap methods (setSeed, setGrammar, setJsonSchema, setSamplers,
  setChatTemplate, setChatTemplateKwargs, setReasoningFormat) appear.
- A handful of tests that did `params.setX(...)` without capturing the
  return value were rewritten to `params = params.withX(...)`.

SpotBugs Max+Low: net unchanged at 6 findings. The one new
OCP_OVERLY_CONCRETE_PARAMETER on InferenceParameters.withReasoningFormat
is suppressed with the same design-intent rationale as the existing
ModelParameters OCP block (the narrow enum type is the API contract;
widening to CliArg would silently accept any enum and emit a nonsense
JSON value).

Author: claude

spotbugs-exclude.xml

@@ -88,6 +88,20 @@ SPDX-License-Identifier: MIT
         </Or>
     </Match>
 
+    <!--
+        Same design-intent rationale as the ModelParameters OCP block above:
+        InferenceParameters.withReasoningFormat(ReasoningFormat) intentionally
+        types its parameter to the specific ReasoningFormat enum rather than
+        the shared CliArg interface. The narrow type is the API contract;
+        widening it would silently accept any CliArg-implementing enum and
+        emit a nonsense JSON value the native code would reject.
+    -->
+    <Match>
+        <Class name="net.ladenthin.llama.InferenceParameters"/>
+        <Bug pattern="OCP_OVERLY_CONCRETE_PARAMETER"/>
+        <Method name="withReasoningFormat"/>
+    </Match>
+
     <!--
         InferenceParameters and ModelParameters are fluent builders whose
         parameters field is a Map<String, String> serving as the CLI / JSON

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

@@ -25,7 +25,7 @@
  * 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 InferenceParameters#setMessages(java.util.List)}) emits an array-form
+ * (see {@link InferenceParameters#withMessages(java.util.List)}) emits an array-form
  * {@code content} field that the compiled-in {@code mtmd} pipeline understands.
  * </p>
  *

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

@@ -12,7 +12,7 @@
 import java.util.Collections;
 import java.util.List;
 import java.util.Optional;
-import java.util.function.Consumer;
+import java.util.function.UnaryOperator;
 import lombok.EqualsAndHashCode;
 import lombok.ToString;
 import org.jspecify.annotations.Nullable;
@@ -25,8 +25,12 @@
  *
  * <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
+ * customiser applied to the underlying request just before invocation. Because
+ * {@link InferenceParameters} is itself immutable, the customiser is a
+ * {@link UnaryOperator} that takes a parameter set and returns the transformed
+ * one — callers chain {@code withX(...)} calls on the input and return the
+ * resulting instance. The type is consumed by
+ * {@link LlamaModel#chat(ChatRequest)} and
  * {@link LlamaModel#chatWithTools(ChatRequest, java.util.Map)}.
  *
  * <p>All instances are <b>immutable</b>: every field is {@code final} and the
@@ -47,7 +51,7 @@
  *         .appendMessage("system", "be terse")
  *         .appendMessage("user", "two plus two?")
  *         .withMaxToolRounds(2)
- *         .withInferenceCustomizer(p -> p.setNPredict(8).setSeed(1));
+ *         .withInferenceCustomizer(p -> p.withNPredict(8).withSeed(1));
  * }</pre>
  *
  * <p>Each call allocates a new {@code ChatRequest}. The cost is intentional:
@@ -58,7 +62,7 @@
  *
  * <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
+ * {@link UnaryOperator} 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
@@ -93,7 +97,7 @@ public final class ChatRequest {
     // equality is compiler-synthesised class identity, not value-shaped.
     @ToString.Exclude
     @EqualsAndHashCode.Exclude
-    private final @Nullable Consumer<InferenceParameters> paramsCustomizer;
+    private final @Nullable UnaryOperator<InferenceParameters> paramsCustomizer;
 
     /**
      * All-args constructor. Private because callers should enter via {@link #empty()}
@@ -105,7 +109,7 @@ private ChatRequest(
             List<ToolDefinition> tools,
             @Nullable String toolChoice,
             int maxToolRounds,
-            @Nullable Consumer<InferenceParameters> paramsCustomizer) {
+            @Nullable UnaryOperator<InferenceParameters> paramsCustomizer) {
         this.messages = messages;
         this.tools = tools;
         this.toolChoice = toolChoice;
@@ -212,7 +216,7 @@ public ChatRequest withMaxToolRounds(int newMaxToolRounds) {
      * @param newCustomizer the customiser; {@code null} clears any prior customiser
      * @return a new request with the customiser replaced; this request is unchanged
      */
-    public ChatRequest withInferenceCustomizer(@Nullable Consumer<InferenceParameters> newCustomizer) {
+    public ChatRequest withInferenceCustomizer(@Nullable UnaryOperator<InferenceParameters> newCustomizer) {
         return new ChatRequest(messages, tools, toolChoice, maxToolRounds, newCustomizer);
     }
 
@@ -319,14 +323,14 @@ public Optional<String> buildToolsJson() {
     }
 
     /**
-     * Apply the optional customiser to an {@link InferenceParameters} instance.
-     * Package-private; called by {@link LlamaModel}.
+     * Apply the optional customiser to an {@link InferenceParameters} instance and
+     * return the transformed result. Package-private; called by {@link LlamaModel}.
+     * When no customiser is set, returns {@code params} unchanged.
      *
-     * @param params the parameters to mutate
+     * @param params the parameters to transform
+     * @return the (possibly new) parameters produced by the customiser, or {@code params} when no customiser is set
      */
-    void applyCustomizer(InferenceParameters params) {
-        if (paramsCustomizer != null) {
-            paramsCustomizer.accept(params);
-        }
+    InferenceParameters applyCustomizer(InferenceParameters params) {
+        return paramsCustomizer == null ? params : paramsCustomizer.apply(params);
     }
 }

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

@@ -13,7 +13,7 @@
  * <p>
  * Bundles the generated text with parsed {@link Usage}, {@link Timings},
  * per-token {@link TokenLogprob} entries (populated only when
- * {@link InferenceParameters#setNProbs(int)} &gt; 0), and the {@link StopReason}.
+ * {@link InferenceParameters#withNProbs(int)} &gt; 0), and the {@link StopReason}.
  * The raw native JSON is exposed via {@link #getRawJson()} as an escape hatch.
  * </p>
  *