From 57adaafb427b311c07d8c878b0dfa8d6e611fa92 Mon Sep 17 00:00:00 2001
From: amithkoujalgi <koujalgi.amith@gmail.com>
Date: Tue, 21 Oct 2025 10:35:06 +0530
Subject: [PATCH] Refactor Javadoc comments in Agent class for consistency and
 clarity, consolidating multi-line comments into single-line format. Update
 interact method to return chat history instead of a string response,
 enhancing functionality and documentation.

---
 .../java/io/github/ollama4j/agent/Agent.java  | 79 ++++++-------------
 1 file changed, 25 insertions(+), 54 deletions(-)

diff --git a/src/main/java/io/github/ollama4j/agent/Agent.java b/src/main/java/io/github/ollama4j/agent/Agent.java
index 72bf2ed0..aefddc3b 100644
--- a/src/main/java/io/github/ollama4j/agent/Agent.java
+++ b/src/main/java/io/github/ollama4j/agent/Agent.java
@@ -38,44 +38,32 @@ import lombok.*;
  * </ul>
  */
 public class Agent {
-    /**
-     * The agent's display name
-     */
+    /** The agent's display name */
     private final String name;
 
-    /**
-     * List of supported tools for this agent
-     */
+    /** List of supported tools for this agent */
     private final List<Tools.Tool> tools;
 
-    /**
-     * Ollama client instance for communication with the API
-     */
+    /** Ollama client instance for communication with the API */
     private final Ollama ollamaClient;
 
-    /**
-     * The model name used for chat completions
-     */
+    /** The model name used for chat completions */
     private final String model;
 
-    /**
-     * Persists chat message history across rounds
-     */
+    /** Persists chat message history across rounds */
     private final List<OllamaChatMessage> chatHistory;
 
-    /**
-     * Optional custom system prompt for the agent
-     */
+    /** Optional custom system prompt for the agent */
     private final String customPrompt;
 
     /**
      * Constructs a new Agent.
      *
-     * @param name         The agent's given name.
+     * @param name The agent's given name.
      * @param ollamaClient The Ollama API client instance to use.
-     * @param model        The model name to use for chat completion.
+     * @param model The model name to use for chat completion.
      * @param customPrompt A custom prompt to prepend to all conversations (may be null).
-     * @param tools        List of available tools for function calling.
+     * @param tools List of available tools for function calling.
      */
     public Agent(
             String name,
@@ -161,21 +149,17 @@ public class Agent {
     }
 
     /**
-     * Facilitates a single round of chat for the agent:
+     * Conducts a conversational interaction with the agent.
      *
-     * <ul>
-     *   <li>Builds/promotes the system prompt on the first turn if necessary
-     *   <li>Adds the user's input to chat history
-     *   <li>Submits the chat turn to the Ollama model (with tool/function support)
-     *   <li>Updates internal chat history in accordance with the Ollama chat result
-     * </ul>
-     *
-     * @param userInput The user's message or question for the agent.
-     * @return The model's response as a string.
-     * @throws OllamaException If there is a problem with the Ollama API.
+     * @param userInput the user's question, instruction, or message for the agent.
+     * @param chatTokenHandler an optional handler for receiving streaming token updates from the model as it generates a reply.
+     *                         Can be {@code null} if streaming output is not needed.
+     * @return Updated chat history, as a list of {@link OllamaChatMessage} objects representing the complete conversation so far.
+     *         This includes system, user, assistant, and any tool/function calls/results.
+     * @throws OllamaException if an error occurs communicating with the Ollama API or running tools.
      */
-    public String interact(String userInput, OllamaChatStreamObserver chatTokenHandler)
-            throws OllamaException {
+    public List<OllamaChatMessage> interact(
+            String userInput, OllamaChatStreamObserver chatTokenHandler) throws OllamaException {
         // Build a concise and readable description of available tools
         String availableToolsDescription =
                 tools.isEmpty()
@@ -217,11 +201,10 @@ public class Agent {
                         .build();
         OllamaChatResult response = ollamaClient.chat(request, chatTokenHandler);
 
-        // Update chat history for continuity
         chatHistory.clear();
         chatHistory.addAll(response.getChatHistory());
 
-        return response.getResponseModel().getMessage().getResponse();
+        return response.getChatHistory();
     }
 
     /**
@@ -279,35 +262,23 @@ public class Agent {
     @Getter
     @EqualsAndHashCode(callSuper = false)
     private static class AgentToolSpec extends Tools.ToolSpec {
-        /**
-         * Fully qualified class name of the tool's {@link ToolFunction} implementation
-         */
+        /** Fully qualified class name of the tool's {@link ToolFunction} implementation */
         private String toolFunctionFQCN = null;
 
-        /**
-         * Instance of the {@link ToolFunction} to invoke
-         */
+        /** Instance of the {@link ToolFunction} to invoke */
         private ToolFunction toolFunctionInstance = null;
     }
 
-    /**
-     * Bean for describing a tool function parameter for use in agent YAML definitions.
-     */
+    /** Bean for describing a tool function parameter for use in agent YAML definitions. */
     @Data
     public class AgentToolParameter {
-        /**
-         * The parameter's type (e.g., string, number, etc.)
-         */
+        /** The parameter's type (e.g., string, number, etc.) */
         private String type;
 
-        /**
-         * Description of the parameter
-         */
+        /** Description of the parameter */
         private String description;
 
-        /**
-         * Whether this parameter is required
-         */
+        /** Whether this parameter is required */
         private boolean required;
 
         /**