[#19] Reword XML Documentation Comments

Author: sgdevnet

src/MaIN.Core/Hub/Contexts/Interfaces/AgentContext/IAgentActions.cs

@@ -7,15 +7,15 @@ namespace MaIN.Core.Hub.Contexts.Interfaces.AgentContext;
 public interface IAgentActions
 {
     /// <summary>
-    /// Gets the unique identifier (GUID) of the current Agent.
+    /// Retrieves the unique identifier for the agent.
     /// </summary>
-    /// <returns>The Agent's ID as a string.</returns>
+    /// <returns>A string representing the agent's unique identifier.</returns>
     string GetAgentId();
 
     /// <summary>
-    /// Retrieves the full Agent entity with its current configuration and state.
+    /// Fetches the current agent instance.
     /// </summary>
-    /// <returns>An <see cref="Agent"/> object.</returns>
+    /// <returns>The <see cref="Agent"/> object containing all the properties and data for the current agent.</returns>
     Agent GetAgent();
 
     /// <summary>
@@ -25,21 +25,21 @@ public interface IAgentActions
     Knowledge? GetKnowledge();
 
     /// <summary>
-    /// Retrieves the current chat session associated with this Agent.
+    /// Retrieves the chat session associated with the current agent.
     /// </summary>
-    /// <returns>A task representing the asynchronous operation, containing the <see cref="Chat"/>.</returns>
+    /// <returns>A <see cref="Chat"/> object representing the chat session associated with the agent.</returns>
     Task<Chat> GetChat();
 
     /// <summary>
-    /// Clears the conversation history and restarts the chat session for this Agent.
+    /// Restarts the chat session associated with the current agent, typically resetting the conversation state.
     /// </summary>
-    /// <returns>A task representing the asynchronous operation, containing a new <see cref="Chat"/>.</returns>
+    /// <returns>A <see cref="Chat"/> object representing the restarted chat session.</returns>
     Task<Chat> RestartChat();
 
     /// <summary>
-    /// Lists all agents available in the system.
+    /// Fetches all agents managed by the underlying agent service.
     /// </summary>
-    /// <returns>A task containing a list of <see cref="Agent"/> objects.</returns>
+    /// <returns>A list of <see cref="Agent"/> objects representing all agents.</returns>
     Task<List<Agent>> GetAllAgents();
 
     /// <summary>
@@ -50,13 +50,13 @@ public interface IAgentActions
     Task<Agent?> GetAgentById(string id);
 
     /// <summary>
-    /// Permanently deletes the current Agent and all associated data.
+    /// Deletes the current agent from the system.
     /// </summary>
     Task Delete();
 
     /// <summary>
-    /// Checks if an agent with the current identifier exists in the system.
+    /// Checks if the current agent exists in the system.
     /// </summary>
-    /// <returns>True if the agent exists, otherwise false.</returns>
+    /// <returns>A boolean indicating whether the agent exists.</returns>
     Task<bool> Exists();
 }

src/MaIN.Core/Hub/Contexts/Interfaces/AgentContext/IAgentBuilderEntryPoint.cs

@@ -3,23 +3,25 @@
 public interface IAgentBuilderEntryPoint : IAgentActions
 {
     /// <summary>
-    /// Sets the LLM model to be used by the Agent.
+    /// Sets the AI model for the agent to use during its interactions.
     /// </summary>
-    /// <param name="model">The name or identifier of the model (e.g., "llama3.2").</param>
+    /// <param name="model">The name or identifier of the AI model to be used.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithModel(string model);
 
     /// <summary>
-    /// Configures a custom model from a specific local path.
+    /// Specifies a custom model along with its file path for use by the agent. This allows using locally stored models in addition to predefined ones.
     /// </summary>
-    /// <param name="model">A custom name for the model.</param>
-    /// <param name="path">The file system path to the model files.</param>
+    /// <param name="model">The name of the custom model.</param>
+    /// <param name="path">The path to the custom model’s file.</param>
     /// <param name="mmProject">Optional multi-modal project identifier.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithCustomModel(string model, string path, string? mmProject = null);
 
     /// <summary>
-    /// Loads an existing Agent from the database.
+    /// Fetches an existing agent by its ID, allowing you to create a new <see cref="AgentContext"/> from an already existing agent.
     /// </summary>
     /// <param name="agentId">The unique identifier of the Agent to load.</param>
-    /// <returns>An execution interface ready for processing messages.</returns>
+    /// <returns>The context instance implementing <see cref="IAgentContextExecutor"/> for method chaining.</returns>
     Task<IAgentContextExecutor> FromExisting(string agentId);
 }

src/MaIN.Core/Hub/Contexts/Interfaces/AgentContext/IAgentConfigurationBuilder.cs

@@ -10,119 +10,147 @@ namespace MaIN.Core.Hub.Contexts.Interfaces.AgentContext;
 public interface IAgentConfigurationBuilder : IAgentActions
 {
     /// <summary>
-    /// Sets the system-level instruction or persona for the Agent. This prompt defines how the Agent should behave and respond.
+    /// Sets the initial prompt for the agent. This prompt serves as an instruction or context that guides the agent's behavior during its execution.
     /// </summary>
-    /// <param name="prompt">The text content of the system instructions or Agent persona.</param>
+    /// <param name="prompt"> The initial prompt or instruction for the agent.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithInitialPrompt(string prompt);
 
     /// <summary>
-    /// Sets a custom unique identifier for the Agent.
+    /// Assigns a unique identifier to the agent.
     /// </summary>
-    /// <param name="id">The new Agent ID.</param>
+    /// <param name="id">he unique identifier for the agent.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithId(string id);
 
     /// <summary>
-    /// Sets the Agent's execution order (relevant in multi-agent flows).
+    /// Sets the order of the agent. This can be used in scenarios where agents need to be prioritized or sequenced.
     /// </summary>
-    /// <param name="order">The sequence number.</param>
+    /// <param name="order">The order value to assign to the agent.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithOrder(int order);
 
     /// <summary>
-    /// Disables the caching mechanism for this Agent's requests.
+    /// Each time we run inference, we need to load model into memory, this takes time and memory. This method allows us to save some
+    /// more of GPU/RAM resources at the cost of time, because model weights are no longer cached.
     /// </summary>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder DisableCache();
 
     /// <summary>
-    /// Defines the data source from which the Agent derives its identity or knowledge.
+    /// Sets the source of the agent’s context, including information related to the agent's source and its type.
     /// </summary>
-    /// <param name="source">The implementation of the agent source.</param>
-    /// <param name="type">The type of source (e.g., PDF, Web).</param>
+    /// <param name="source">The <see cref="IAgentSource"/> source instance providing the agent’s context.</param>
+    /// <param name="type">The <see cref="AgentSourceType"/> - type of source (e.g., API, SQL, Web).</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithSource(IAgentSource source, AgentSourceType type);
 
     /// <summary>
     /// Sets a friendly display name for the Agent.
     /// </summary>
     /// <param name="name">The name of the Agent.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithName(string name);
 
     /// <summary>
-    /// Selects a specific processing engine (Backend) for LLM requests.
+    /// Defines backend that will be used for model inference.
     /// </summary>
-    /// <param name="backendType">The backend type.</param>
+    /// <param name="backendType">The <see cref="BackendType"/> - an enum that defines which AI backend to use.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithBackend(BackendType backendType);
 
     /// <summary>
     /// Configures integration with the Model Context Protocol (MCP).
     /// </summary>
-    /// <param name="mcpConfig">The MCP configuration object.</param>
+    /// <param name="mcpConfig">The <see cref="Mcp"/> configuration object.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithMcpConfig(Mcp mcpConfig);
 
     /// <summary>
-    /// Sets inference parameters such as temperature, top-p, or max tokens.
+    /// Sets the inference parameters for the chat session, allowing you to customize how the AI processes and generates responses
+    /// based on specific parameters. Inference parameters can influence various aspects of the chat, such as response length,
+    /// temperature, and other model-specific settings.
     /// </summary>
-    /// <param name="inferenceParams">An object containing LLM technical settings.</param>
+    /// <param name="inferenceParams">An <see cref="InferenceParams"/> object that holds the parameters for inference, such as Temperature, MaxTokens,
+    /// TopP, etc. These parameters control the generation behavior of the agent.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithInferenceParams(InferenceParams inferenceParams);
 
     /// <summary>
-    /// Configures memory and context window settings for the Agent.
+    /// Sets the memory parameters for the chat session, allowing you to customize how the AI accesses and uses its memory
+    /// for generating responses. Memory parameters influence aspects such as context size, memory search depth,
+    /// and token allocation for responses.
     /// </summary>
-    /// <param name="memoryParams">Memory management settings.</param>
+    /// <param name="memoryParams">A <see cref="MemoryParams"/> object that holds the parameters for memory management, such as
+    /// ContextSize, MaxMatchesCount, AnswerTokens, etc. These parameters control how agent uses memory for response generation.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithMemoryParams(MemoryParams memoryParams);
 
     /// <summary>
-    /// Defines a sequence of steps (pipeline) that the Agent must execute for each request.
+    /// Configures the steps that the agent will follow during its interaction. Each step is a task or action that
+    /// the agent will execute sequentially.
     /// </summary>
-    /// <param name="steps">A list of step names.</param>
+    /// <param name="steps">A list of strings representing the steps the agent should follow.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithSteps(List<string>? steps);
 
     /// <summary>
     /// Assigns tools (functions) that the Agent can autonomously invoke.
     /// </summary>
-    /// <param name="toolsConfiguration">The configuration for available tools.</param>
+    /// <param name="toolsConfiguration">The <see cref="ToolsConfiguration"/> for available tools.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithTools(ToolsConfiguration toolsConfiguration);
 
     /// <summary>
     /// Configures the Agent's knowledge base using a configuration delegate.
     /// </summary>
     /// <param name="knowledgeConfig">A function to configure the knowledge builder.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithKnowledge(Func<KnowledgeBuilder, KnowledgeBuilder> knowledgeConfig);
 
     /// <summary>
     /// Initializes the knowledge base using a pre-configured builder.
     /// </summary>
-    /// <param name="knowledge">The knowledge builder instance.</param>
+    /// <param name="knowledge">The <see cref="KnowledgeBuilder"/> instance.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithKnowledge(KnowledgeBuilder knowledge);
 
     /// <summary>
     /// Assigns a pre-built knowledge base object to the Agent.
     /// </summary>
-    /// <param name="knowledge">The knowledge instance.</param>
+    /// <param name="knowledge">The <see cref="Knowledge"/> instance.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithKnowledge(Knowledge knowledge);
 
     /// <summary>
-    /// Creates a volatile knowledge base stored only in memory (not persisted to disk).
+    /// Creates a volatile knowledge base stored only in memory.
     /// </summary>
     /// <param name="knowledgeConfig">A function to configure the in-memory knowledge builder.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithInMemoryKnowledge(Func<KnowledgeBuilder, KnowledgeBuilder> knowledgeConfig);
 
     /// <summary>
-    /// Defines a specific personality or task (Behavior) under a unique name.
+    /// Defines a behavior for the agent, specifying an action or task the agent should perform based on the provided name and instruction.
     /// </summary>
     /// <param name="name">The name of the behavior.</param>
-    /// <param name="instruction">The system instructions for this behavior.</param>
+    /// <param name="instruction">The instruction associated with the behavior.</param>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
     IAgentConfigurationBuilder WithBehaviour(string name, string instruction);
 
     /// <summary>
-    /// Finalizes the build process and creates the Agent in the system synchronously.
+    /// Synchronously creates the agent in the system.
     /// </summary>
-    /// <param name="flow">Indicates if the Agent is part of a larger flow.</param>
-    /// <param name="interactiveResponse">Specifies if responses should be streamed.</param>
+    /// <param name="flow">A flag indicating whether the agent should be part of an agent flow.</param>
+    /// <param name="interactiveResponse">A flag indicating whether the agent should generate interactive responses.</param>
+    /// <returns>The context instance implementing <see cref="IAgentContextExecutor"/> for method chaining.</returns>
     IAgentContextExecutor Create(bool flow = false, bool interactiveResponse = false);
 
     /// <summary>
-    /// Finalizes the build process and creates the Agent in the system asynchronously.
+    /// Asynchronously creates the agent in the system. This method integrates the agent into the underlying agent service,
+    /// making it ready for use.
     /// </summary>
-    /// <param name="flow">Indicates if the Agent is part of a larger flow.</param>
-    /// <param name="interactiveResponse">Specifies if responses should be interactive.</param>
+    /// <param name="flow">A flag indicating whether the agent should be part of an agent flow.</param>
+    /// <param name="interactiveResponse">A flag indicating whether the agent should generate interactive responses.</param>
+    /// <returns>The context instance implementing <see cref="IAgentContextExecutor"/> for method chaining.</returns>
     Task<IAgentContextExecutor> CreateAsync(bool flow = false, bool interactiveResponse = false);
 }