Add typed ChatRequest/ChatResponse + tool calling + agent loop (§2.2)

New typed chat API on top of the existing handleChatCompletions JNI
path — no native changes.

Value types:
- ChatChoice, ChatResponse  — choices array, Usage, Timings, raw JSON
- ToolCall, ToolDefinition  — OAI-shaped tool wire types
- ChatMessage (extended)    — tool_call_id + tool_calls support, with
  toolResult() and assistantToolCalls() factory methods (backwards-
  compatible 2-arg constructor kept for Session and existing tests)
- ToolHandler               — functional interface for tool callbacks
- ChatRequest               — builder with messages, tools, tool_choice,
  maxToolRounds, and an InferenceParameters customizer

InferenceParameters: new setMessagesJson(String), setToolsJson(String),
setToolChoice(String) for verbatim JSON injection from ChatRequest.

LlamaModel:
- chat(ChatRequest) → ChatResponse
  Serializes the request (auto-enables use_jinja when tools present),
  calls chatComplete, parses the OAI JSON into ChatResponse via the
  extended ChatResponseParser.parseResponse.
- chatWithTools(ChatRequest, Map<String, ToolHandler>) → ChatResponse
  Agent loop: per round, calls chat(); if the assistant returned
  tool_calls, invokes each handler (capturing exceptions as
  {"error":...} tool results so the loop continues), appends the
  assistant turn and tool-result turns to the request, and loops up to
  ChatRequest.maxToolRounds (default 8). Unknown tool names produce a
  {"error":"unknown tool: <name>"} result.

ChatResponseParser: new parseResponse() and tool-call/choice parsers;
handles both string-shaped and object-shaped tool_calls.arguments
(some upstream variants emit each shape).

Tests:
- ChatResponseTest (7 new unit tests, model-free): plain reply, tool
  calls with string arguments, object-shaped arguments, malformed
  input, ChatRequest serialization round-trip.
- LlamaModelTest: testTypedChat and testChatWithToolsLoopShortCircuits
  (model-gated).

mvn javadoc:jar BUILD SUCCESS (0 errors, 60 warnings — same as before,
none from new files).

https://claude.ai/code/session_01R4ZrEy3ptJDLuUgUKuM4Gy

Author: claude

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

@@ -0,0 +1,53 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+package net.ladenthin.llama;
+
+/**
+ * One choice in a chat completion response: the assistant message and the finish reason.
+ * Mirrors the OpenAI {@code choices[i]} object.
+ */
+public final class ChatChoice {
+
+    private final int index;
+    private final ChatMessage message;
+    private final String finishReason;
+
+    /**
+     * Construct a chat choice.
+     *
+     * @param index        the index in the choices array
+     * @param message      the assistant's message for this choice
+     * @param finishReason the finish reason (e.g. {@code "stop"}, {@code "length"}, {@code "tool_calls"})
+     */
+    public ChatChoice(int index, ChatMessage message, String finishReason) {
+        this.index = index;
+        this.message = message;
+        this.finishReason = finishReason;
+    }
+
+    /**
+     * Choice index.
+     * @return the integer index in the choices array
+     */
+    public int getIndex() {
+        return index;
+    }
+
+    /**
+     * Assistant message accessor.
+     * @return the assistant's reply (may include tool_calls)
+     */
+    public ChatMessage getMessage() {
+        return message;
+    }
+
+    /**
+     * Finish reason accessor.
+     * @return the OAI finish reason string, or {@code ""} if absent
+     */
+    public String getFinishReason() {
+        return finishReason;
+    }
+}

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

@@ -4,25 +4,72 @@
 
 package net.ladenthin.llama;
 
+import java.util.Collections;
+import java.util.List;
+
 /**
  * A single message in a chat conversation: a role ({@code "user"}, {@code "assistant"},
- * or {@code "system"}) and its textual content. Used by {@link Session} to accumulate
- * conversation turns.
+ * {@code "system"}, or {@code "tool"}) and its textual content. Used by {@link Session}
+ * to accumulate conversation turns and by {@link 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>
  */
 public final class ChatMessage {
 
     private final String role;
     private final String content;
+    private final String toolCallId;
+    private final List<ToolCall> toolCalls;
 
     /**
-     * Construct a chat message.
+     * Plain user/assistant/system message.
      *
-     * @param role    the message role: {@code "user"}, {@code "assistant"}, or {@code "system"}
+     * @param role    the message role
      * @param content the message text
      */
     public ChatMessage(String role, String content) {
+        this(role, content, null, Collections.<ToolCall>emptyList());
+    }
+
+    /**
+     * 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, String toolCallId, List<ToolCall> toolCalls) {
         this.role = role;
         this.content = content;
+        this.toolCallId = toolCallId;
+        this.toolCalls = toolCalls == null ? Collections.<ToolCall>emptyList() : toolCalls;
+    }
+
+    /**
+     * 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);
     }
 
     /**
@@ -41,8 +88,26 @@ public String getContent() {
         return content;
     }
 
+    /**
+     * Tool-call id for tool-result turns.
+     * @return the originating tool call id, or {@code null} for non-tool messages
+     */
+    public String getToolCallId() {
+        return 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 toolCalls;
+    }
+
     @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;
     }
 }

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

@@ -0,0 +1,216 @@
+// SPDX-FileCopyrightText: 2026 Bernard Ladenthin <bernard.ladenthin@gmail.com>
+//
+// SPDX-License-Identifier: MIT
+
+package net.ladenthin.llama;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ArrayNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.function.Consumer;
+
+/**
+ * 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
+ * {@link LlamaModel#chatWithTools(ChatRequest, java.util.Map)}.
+ * </p>
+ */
+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 String toolChoice;
+    private int maxToolRounds = 8;
+    private Consumer<InferenceParameters> paramsCustomizer;
+
+    /** Construct an empty request; populate via the setters. */
+    public ChatRequest() {
+        // empty
+    }
+
+    /**
+     * Append a message to the conversation.
+     * @param message the message to append
+     * @return this builder
+     */
+    public ChatRequest addMessage(ChatMessage message) {
+        messages.add(message);
+        return this;
+    }
+
+    /**
+     * Convenience for adding a system/user/assistant turn.
+     * @param role    the role
+     * @param content the content
+     * @return this builder
+     */
+    public ChatRequest addMessage(String role, String content) {
+        messages.add(new ChatMessage(role, content));
+        return this;
+    }
+
+    /**
+     * Append a tool definition.
+     * @param tool the tool definition to expose to the model
+     * @return this builder
+     */
+    public ChatRequest addTool(ToolDefinition tool) {
+        tools.add(tool);
+        return this;
+    }
+
+    /**
+     * Set the {@code tool_choice} hint: typically {@code "auto"}, {@code "none"}, or
+     * {@code "required"}. Defaults to absent (server default applies).
+     *
+     * @param toolChoice the hint string, or {@code null} to clear
+     * @return this builder
+     */
+    public ChatRequest setToolChoice(String toolChoice) {
+        this.toolChoice = toolChoice;
+        return this;
+    }
+
+    /**
+     * 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}.
+     *
+     * @param maxToolRounds the round cap (must be positive)
+     * @return this builder
+     */
+    public ChatRequest setMaxToolRounds(int maxToolRounds) {
+        if (maxToolRounds <= 0) {
+            throw new IllegalArgumentException("maxToolRounds must be > 0");
+        }
+        this.maxToolRounds = maxToolRounds;
+        return this;
+    }
+
+    /**
+     * Register a callback that customizes the {@link InferenceParameters} (e.g.
+     * {@code setNPredict}, {@code setTemperature}) right before each request is sent.
+     *
+     * @param customizer the customizer; {@code null} clears any prior customizer
+     * @return this builder
+     */
+    public ChatRequest setInferenceCustomizer(Consumer<InferenceParameters> customizer) {
+        this.paramsCustomizer = customizer;
+        return this;
+    }
+
+    /**
+     * Messages accessor.
+     * @return an unmodifiable view of the messages added so far
+     */
+    public List<ChatMessage> getMessages() {
+        return Collections.unmodifiableList(messages);
+    }
+
+    /**
+     * Tools accessor.
+     * @return an unmodifiable view of the tool definitions added so far
+     */
+    public List<ToolDefinition> getTools() {
+        return Collections.unmodifiableList(tools);
+    }
+
+    /**
+     * Tool choice accessor.
+     * @return the {@code tool_choice} hint, or {@code null} when unset
+     */
+    public String getToolChoice() {
+        return toolChoice;
+    }
+
+    /**
+     * Max rounds accessor.
+     * @return the agent-loop round cap
+     */
+    public int getMaxToolRounds() {
+        return maxToolRounds;
+    }
+
+    /**
+     * 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-
+     * result turns add a {@code tool_call_id} field.
+     *
+     * @return the JSON array as a string
+     */
+    public String buildMessagesJson() {
+        ArrayNode arr = MAPPER.createArrayNode();
+        for (ChatMessage m : messages) {
+            ObjectNode obj = MAPPER.createObjectNode();
+            obj.put("role", m.getRole());
+            obj.put("content", m.getContent() == null ? "" : m.getContent());
+            if (m.getToolCallId() != null) {
+                obj.put("tool_call_id", m.getToolCallId());
+            }
+            if (!m.getToolCalls().isEmpty()) {
+                ArrayNode tc = MAPPER.createArrayNode();
+                for (ToolCall call : m.getToolCalls()) {
+                    ObjectNode entry = MAPPER.createObjectNode();
+                    entry.put("id", call.getId());
+                    entry.put("type", "function");
+                    ObjectNode fn = MAPPER.createObjectNode();
+                    fn.put("name", call.getName());
+                    fn.put("arguments", call.getArgumentsJson() == null ? "" : call.getArgumentsJson());
+                    entry.set("function", fn);
+                    tc.add(entry);
+                }
+                obj.set("tool_calls", tc);
+            }
+            arr.add(obj);
+        }
+        return arr.toString();
+    }
+
+    /**
+     * Build the OAI-style {@code tools} array as a JSON string. Returns {@code null}
+     * when no tools were added.
+     *
+     * @return the JSON array as a string, or {@code null} when there are no tools
+     */
+    public String buildToolsJson() {
+        if (tools.isEmpty()) return null;
+        ArrayNode arr = MAPPER.createArrayNode();
+        for (ToolDefinition t : tools) {
+            ObjectNode entry = MAPPER.createObjectNode();
+            entry.put("type", "function");
+            ObjectNode fn = MAPPER.createObjectNode();
+            fn.put("name", t.getName());
+            if (t.getDescription() != null) fn.put("description", t.getDescription());
+            try {
+                fn.set("parameters", MAPPER.readTree(t.getParametersSchemaJson()));
+            } catch (Exception e) {
+                fn.put("parameters", t.getParametersSchemaJson());
+            }
+            entry.set("function", fn);
+            arr.add(entry);
+        }
+        return arr.toString();
+    }
+
+    /**
+     * Apply the optional customizer to an {@link InferenceParameters} instance.
+     * Package-private; called by {@link LlamaModel}.
+     *
+     * @param params the parameters to mutate
+     */
+    void applyCustomizer(InferenceParameters params) {
+        if (paramsCustomizer != null) {
+            paramsCustomizer.accept(params);
+        }
+    }
+}