feat: Add EnsureDownloaded fluent method

Fixes #115

- add EnsureDownloaded method

Author: srebrek

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

@@ -4,12 +4,14 @@
 using MaIN.Domain.Entities.Agents;
 using MaIN.Domain.Entities.Agents.AgentSource;
 using MaIN.Domain.Models;
+using MaIN.Domain.Models.Abstract;
 using MaIN.Services.Services.Abstract;
 using MaIN.Services.Services.Models;
 using MaIN.Core.Hub.Utils;
 using MaIN.Domain.Entities.Agents.Knowledge;
 using MaIN.Domain.Entities.Tools;
 using MaIN.Domain.Exceptions.Agents;
+using MaIN.Domain.Exceptions.Models;
 using MaIN.Services.Constants;
 
 namespace MaIN.Core.Hub.Contexts;
@@ -20,6 +22,7 @@ public sealed class AgentContext : IAgentBuilderEntryPoint, IAgentConfigurationB
     private InferenceParams? _inferenceParams;
     private MemoryParams? _memoryParams;
     private bool _disableCache;
+    private bool _ensureModelDownloaded;
     private readonly Agent _agent;
     internal Knowledge? _knowledge;
 
@@ -112,6 +115,12 @@ public IAgentConfigurationBuilder DisableCache()
         return this;
     }
 
+    public IAgentConfigurationBuilder EnsureModelDownloaded()
+    {
+        _ensureModelDownloaded = true;
+        return this;
+    }
+
     public IAgentConfigurationBuilder WithSource(IAgentSource source, AgentSourceType type)
     {
         _agent.Context.Source = new AgentSource()
@@ -200,11 +209,20 @@ public IAgentConfigurationBuilder WithBehaviour(string name, string instruction)
 
     public async Task<IAgentContextExecutor> CreateAsync(bool flow = false, bool interactiveResponse = false)
     {
+        if (_ensureModelDownloaded && !string.IsNullOrWhiteSpace(_agent.Model))
+        {
+            var model = ModelRegistry.GetById(_agent.Model);
+            if (model is LocalModel)
+            {
+                await AIHub.Model().EnsureDownloadedAsync(_agent.Model);
+            }
+        }
+
         await _agentService.CreateAgent(_agent, flow, interactiveResponse, _inferenceParams, _memoryParams, _disableCache);
         return this;
     }
-    
-    public IAgentContextExecutor Create(bool flow = false, bool interactiveResponse = false)
+
+    public IAgentContextExecutor Create(bool flow = false, bool interactiveResponse = false) // I think it should be removed as there is a deadlock risk.
     {
         _ = _agentService.CreateAgent(_agent, flow, interactiveResponse, _inferenceParams, _memoryParams, _disableCache).Result;
         return this;

src/MaIN.Core/Hub/Contexts/ChatContext.cs

@@ -1,4 +1,5 @@
 using MaIN.Core.Hub.Contexts.Interfaces.ChatContext;
+using MaIN.Core.Hub.Contexts.Interfaces.ModelContext;
 using MaIN.Domain.Configuration;
 using MaIN.Domain.Entities;
 using MaIN.Domain.Entities.Tools;
@@ -10,6 +11,7 @@
 using MaIN.Services.Constants;
 using MaIN.Services.Services.Abstract;
 using MaIN.Services.Services.Models;
+using MaIN.Core.Hub;
 using FileInfo = MaIN.Domain.Entities.FileInfo;
 
 namespace MaIN.Core.Hub.Contexts;
@@ -18,6 +20,7 @@ public sealed class ChatContext : IChatBuilderEntryPoint, IChatMessageBuilder, I
 {
     private readonly IChatService _chatService;
     private bool _preProcess;
+    private bool _ensureModelDownloaded;
     private readonly Chat _chat;
     private List<FileInfo> _files = [];
 
@@ -88,7 +91,13 @@ public IChatMessageBuilder EnableVisual()
         _chat.Visual = true;
         return this;
     }
-    
+
+    public IChatMessageBuilder EnsureModelDownloaded()
+    {
+        _ensureModelDownloaded = true;
+        return this;
+    }
+
     public IChatConfigurationBuilder WithInferenceParams(InferenceParams inferenceParams)
     {
         _chat.InterferenceParams = inferenceParams;
@@ -208,7 +217,12 @@ public async Task<ChatResult> CompleteAsync(
         {
             throw new EmptyChatException(_chat.Id);
         }
-        
+
+        if (_ensureModelDownloaded && _chat.ModelInstance is LocalModel)
+        {
+            await AIHub.Model().EnsureDownloadedAsync(_chat.ModelId);
+        }
+
         _chat.Messages.Last().Files = _files;
         if(_preProcess)
         {
@@ -244,10 +258,7 @@ private async Task<bool> ChatExists(string id)
             return false;
         }
     }
-    
-    IChatMessageBuilder IChatMessageBuilder.EnableVisual() => EnableVisual();
-
- 
+     
     public string GetChatId() => _chat.Id;
 
     public async Task<Chat> GetCurrentChat()

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

@@ -9,6 +9,14 @@ namespace MaIN.Core.Hub.Contexts.Interfaces.AgentContext;
 
 public interface IAgentConfigurationBuilder : IAgentActions
 {
+    /// <summary>
+    /// Flags the agent to automatically ensure the selected local model is downloaded before creation.
+    /// If the model is already present the download is skipped; cloud models are silently ignored.
+    /// The actual download is deferred until <see cref="CreateAsync"/> is called.
+    /// </summary>
+    /// <returns>The context instance implementing <see cref="IAgentConfigurationBuilder"/> for method chaining.</returns>
+    IAgentConfigurationBuilder EnsureModelDownloaded();
+
     /// <summary>
     /// 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>

src/MaIN.Core/Hub/Contexts/Interfaces/ChatContext/IChatMessageBuilder.cs

@@ -10,6 +10,14 @@ public interface IChatMessageBuilder : IChatActions
     /// </summary>
     /// <returns>The context instance implementing <see cref="IChatMessageBuilder"/> for method chaining.</returns>
     IChatMessageBuilder EnableVisual();
+
+    /// <summary>
+    /// Flags the chat to automatically ensure the selected local model is downloaded before completing.
+    /// If the model is already present the download is skipped; cloud models are silently ignored.
+    /// The actual download is deferred until <see cref="IChatConfigurationBuilder.CompleteAsync"/> is called.
+    /// </summary>
+    /// <returns>The context instance implementing <see cref="IChatMessageBuilder"/> for method chaining.</returns>
+    IChatMessageBuilder EnsureModelDownloaded();
 
     /// <summary>
     /// Adds a user message to the chat. This method captures the message content and assigns the "User" role to it.

src/MaIN.Core/Hub/Contexts/Interfaces/ModelContext/IModelContext.cs

@@ -39,7 +39,7 @@ public interface IModelContext
     /// </summary>
     /// <param name="modelId">The id of the model to check for existence.</param>
     /// <returns>A boolean value indicating whether the model file exists locally.</returns>
-    bool Exists(string modelId);
+    bool IsDownloaded(string modelId);
 
     /// <summary>
     /// Asynchronously downloads a known model from its configured download URL. This method handles the complete download process
@@ -52,33 +52,27 @@ public interface IModelContext
     Task<IModelContext> DownloadAsync(string modelId, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Asynchronously downloads a custom model from a specified URL. This method allows downloading models that are not part
-    /// of the known models collection, adding them to the system after download.
+    /// Ensures a known local model is downloaded before use. If the model is already present on disk the call
+    /// returns immediately; if not, the model is downloaded. Cloud models are silently skipped.
+    /// Thread-safe: concurrent calls for the same model will not trigger duplicate downloads.
     /// </summary>
-    /// <param name="model">The name to assign to the downloaded model.</param>
-    /// <param name="url">The URL from which to download the model.</param>
-    /// <returns>A task that represents the asynchronous download operation that completes when the download finishes,
-    /// returning the context instance implementing <see cref="IModelContext"/> for method chaining.</returns>
-    Task<IModelContext> DownloadAsync(string model, string url, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Synchronously downloads a known model from its configured download URL. This is the blocking version of the download operation
-    /// with progress tracking.
-    /// </summary>
-    /// <param name="modelName">The name of the model to download.</param>
-    /// <returns>The context instance implementing <see cref="IModelContext"/> for method chaining.</returns>
-    [Obsolete("Use DownloadAsync instead")]
-    IModelContext Download(string modelName);
+    /// <param name="modelId">The id of the model to ensure is downloaded.</param>
+    /// <param name="cancellationToken">Optional cancellation token to abort the download operation.</param>
+    /// <returns>A task that represents the asynchronous operation, returning the context instance implementing
+    /// <see cref="IModelContext"/> for method chaining.</returns>
+    Task<IModelContext> EnsureDownloadedAsync(string modelId, CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Synchronously downloads a custom model from a specified URL. This method provides blocking download functionality
-    /// for custom models not in the known models collection.
+    /// Ensures a known local model is downloaded before use using a strongly-typed model reference.
+    /// If the model is already present on disk the call returns immediately; if not, the model is downloaded.
+    /// Cloud models are silently skipped.
+    /// Thread-safe: concurrent calls for the same model will not trigger duplicate downloads.
     /// </summary>
-    /// <param name="model">The name to assign to the downloaded model.</param>
-    /// <param name="url">The URL from which to download the model.</param>
-    /// <returns>The context instance implementing <see cref="IModelContext"/> for method chaining.</returns>
-    [Obsolete("Use DownloadAsync instead")]
-    IModelContext Download(string model, string url);
+    /// <typeparam name="TModel">A <see cref="LocalModel"/> type with a parameterless constructor.</typeparam>
+    /// <param name="cancellationToken">Optional cancellation token to abort the download operation.</param>
+    /// <returns>A task that represents the asynchronous operation, returning the context instance implementing
+    /// <see cref="IModelContext"/> for method chaining.</returns>
+    Task<IModelContext> EnsureDownloadedAsync<TModel>(CancellationToken cancellationToken = default) where TModel : LocalModel, new();
 
     /// <summary>
     /// Loads a model into the memory cache for faster access during inference operations. This method preloads the model to avoid loading