refactor LLM services, namespaces, add documentation

add version 1.0 of Desktop LLM logic

Author: angelovstanton

Bellatrix.LLM/SemanticKernelService.cs

@@ -15,7 +15,7 @@
 // The architecture and agent logic are original contributions by Anton Angelov, forming the foundation for a PhD dissertation.
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
 using Bellatrix.KeyVault;
-using Bellatrix.LLM.settings;
+using Bellatrix.LLM.Settings;
 using Microsoft.KernelMemory;
 using Microsoft.SemanticKernel;
 using System.Collections.Concurrent;

Bellatrix.LLM/cache/LocatorCacheDbContext.cs

@@ -15,7 +15,6 @@
 // The architecture and agent logic are original contributions by Anton Angelov, forming the foundation for a PhD dissertation.
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
 
-using Bellatrix.LLM.cache;
 using Microsoft.EntityFrameworkCore;
 
 namespace Bellatrix.LLM.Cache;

Bellatrix.LLM/cache/SelfHealingLocatorEntry.cs

@@ -14,7 +14,7 @@
 // <note>This file is part of an academic research project exploring autonomous test agents using LLMs and Semantic Kernel.
 // The architecture and agent logic are original contributions by Anton Angelov, forming the foundation for a PhD dissertation.
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
-namespace Bellatrix.LLM.cache;
+namespace Bellatrix.LLM.Cache;
 public class SelfHealingLocatorEntry
 {
     public int Id { get; set; }

Bellatrix.LLM/cache/SmartTestExecutionEntry.cs

@@ -14,7 +14,7 @@
 // <note>This file is part of an academic research project exploring autonomous test agents using LLMs and Semantic Kernel.
 // The architecture and agent logic are original contributions by Anton Angelov, forming the foundation for a PhD dissertation.
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
-namespace Bellatrix.LLM.cache;
+namespace Bellatrix.LLM.Cache;
 public class SmartTestExecutionEntry
 {
     public int Id { get; set; }

…llm/plugins/SmartTestFailureException.cs …LLM/plugins/SmartTestFailureException.cssrc/Bellatrix.Web/llm/plugins/SmartTestFailureException.cs renamed to Bellatrix.LLM/plugins/SmartTestFailureException.cs src/Bellatrix.Web/llm/plugins/SmartTestFailureException.cs renamed to Bellatrix.LLM/plugins/SmartTestFailureException.cs

@@ -14,9 +14,7 @@
 // <note>This file is part of an academic research project exploring autonomous test agents using LLMs and Semantic Kernel.
 // The architecture and agent logic are original contributions by Anton Angelov, forming the foundation for a PhD dissertation.
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
-using System;
-
-namespace Bellatrix.Web.LLM.Plugins;
+namespace Bellatrix.LLM.Plugins;
 public class SmartTestFailureException : Exception
 {
     public SmartTestFailureException(string aiSummary, string fullAnalysis, Exception originalException)

….Web/llm/services/LocatorCacheService.cs …trix.LLM/services/LocatorCacheService.cssrc/Bellatrix.Web/llm/services/LocatorCacheService.cs renamed to Bellatrix.LLM/services/LocatorCacheService.cs src/Bellatrix.Web/llm/services/LocatorCacheService.cs renamed to Bellatrix.LLM/services/LocatorCacheService.cs

@@ -17,19 +17,23 @@
 
 using Bellatrix.KeyVault;
 using Bellatrix.LLM.Cache;
-using Bellatrix.LLM.settings;
-using OpenQA.Selenium;
-using System;
+using Bellatrix.LLM.Settings;
 using System.Collections.Concurrent;
-using System.Linq;
 
-namespace Bellatrix.Web.LLM.services;
+namespace Bellatrix.LLM;
+
+/// <summary>
+/// A shared locator cache service for AI-assisted test automation.
+/// It stores and retrieves XPath selectors for natural language instructions,
+/// scoped by application location (e.g., URL or screen ID).
+/// Useful for enabling cross-platform support (Web, Android, iOS, Desktop).
+/// </summary>
 public static class LocatorCacheService
 {
     private static readonly ConcurrentDictionary<string, string> _cache = new();
     private static readonly string _project;
     private static readonly LocatorCacheDbContext _db;
-    private static IWebDriver _driver => ServicesCollection.Current.Resolve<IWebDriver>();
+
     static LocatorCacheService()
     {
         var settings = ConfigurationService.GetSection<LargeLanguageModelsSettings>();
@@ -47,19 +51,30 @@ static LocatorCacheService()
         }
     }
 
-    public static By TryGetCached(string instruction)
+    /// <summary>
+    /// Attempts to retrieve a cached XPath for the given instruction and location.
+    /// </summary>
+    /// <param name="location">The app location (URL, screen ID, etc.)</param>
+    /// <param name="instruction">The natural language instruction used for element lookup.</param>
+    /// <returns>The XPath selector if cached, otherwise null.</returns>
+    public static string TryGetCached(string location, string instruction)
     {
-        var key = $"{_driver.Url}|{instruction}";
-        return _cache.TryGetValue(key, out var xpath) ? By.XPath(xpath) : null;
+        var key = $"{location}|{instruction}";
+        return _cache.TryGetValue(key, out var xpath) ? xpath : null;
     }
 
-    public static void Remove(string instruction)
+    /// <summary>
+    /// Removes the cached entry (if any) for the given instruction and location.
+    /// </summary>
+    /// <param name="location">The app location.</param>
+    /// <param name="instruction">The instruction key to remove.</param>
+    public static void Remove(string location, string instruction)
     {
-        var key = $"{_driver.Url}|{instruction}";
+        var key = $"{location}|{instruction}";
         _cache.TryRemove(key, out _);
 
         var dbEntry = _db.LocatorCache.FirstOrDefault(x =>
-            x.Project == _project && x.AppLocation == _driver.Url && x.Instruction == instruction);
+            x.Project == _project && x.AppLocation == location && x.Instruction == instruction);
 
         if (dbEntry != null)
         {
@@ -68,38 +83,47 @@ public static void Remove(string instruction)
         }
     }
 
-    public static void Update(string instruction, string xpath)
+    /// <summary>
+    /// Updates or inserts a new cached XPath selector for a given instruction and location.
+    /// </summary>
+    /// <param name="location">The app location.</param>
+    /// <param name="instruction">The natural language instruction used for lookup.</param>
+    /// <param name="xpath">The XPath selector to store.</param>
+    public static void Update(string location, string instruction, string xpath)
     {
-        var key = $"{_driver.Url}|{instruction}";
+        var key = $"{location}|{instruction}";
         _cache[key] = xpath;
 
         var existing = _db.LocatorCache.FirstOrDefault(x =>
-            x.Project == _project && x.AppLocation == _driver.Url && x.Instruction == instruction);
+            x.Project == _project && x.AppLocation == location && x.Instruction == instruction);
 
         if (existing != null)
         {
             existing.XPath = xpath;
             existing.LastValidated = DateTime.UtcNow;
-
-            _db.LocatorCache.Update(existing); // <== ensure it's attached + marked as modified
+            _db.LocatorCache.Update(existing);
         }
         else
         {
             var entry = new LocatorCacheEntry
             {
                 Project = _project,
-                AppLocation = _driver.Url,
+                AppLocation = location,
                 Instruction = instruction,
                 XPath = xpath
             };
-
             _db.LocatorCache.Add(entry);
         }
 
         _db.SaveChanges();
     }
+
+    /// <summary>
+    /// Disposes the database context when no longer needed.
+    /// </summary>
     public static void Dispose()
     {
         _db?.Dispose();
     }
 }
+

…lm/services/LocatorSelfHealingService.cs …LM/services/LocatorSelfHealingService.cssrc/Bellatrix.Web/llm/services/LocatorSelfHealingService.cs renamed to Bellatrix.LLM/services/LocatorSelfHealingService.cs src/Bellatrix.Web/llm/services/LocatorSelfHealingService.cs renamed to Bellatrix.LLM/services/LocatorSelfHealingService.cs

@@ -15,20 +15,24 @@
 // The architecture and agent logic are original contributions by Anton Angelov, forming the foundation for a PhD dissertation.
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
 using Bellatrix.KeyVault;
-using Bellatrix.LLM;
-using Bellatrix.LLM.cache;
 using Bellatrix.LLM.Cache;
-using Bellatrix.LLM.settings;
+using Bellatrix.LLM.Settings;
 using Microsoft.SemanticKernel;
-using OpenQA.Selenium;
-using System;
-using System.Linq;
 
-namespace Bellatrix.Web.LLM.services;
+namespace Bellatrix.LLM;
+/// <summary>
+/// Provides self-healing capabilities for UI locators by leveraging AI and a local cache of previously validated locators.
+/// This service enables autonomous test agents to recover from locator failures by suggesting new working locators
+/// based on historical data and semantic analysis of UI changes.
+/// </summary>
 public static class LocatorSelfHealingService
 {
     private static readonly LocatorCacheDbContext _db;
     private static readonly string _project;
+
+    /// <summary>
+    /// Static constructor initializes the local cache database context and project name from configuration and secrets.
+    /// </summary>
     static LocatorSelfHealingService()
     {
         var settings = ConfigurationService.GetSection<LargeLanguageModelsSettings>();
@@ -37,7 +41,20 @@ static LocatorSelfHealingService()
         _project = settings.LocalCacheProjectName;
     }
 
-    public static FindXpathStrategy TryHeal(string failingLocator, string newestVersionViewSummary, string appLocation = "")
+    /// <summary>
+    /// Attempts to heal a failing locator by leveraging AI and previously cached locator data.
+    /// The method queries the local cache for a known valid locator matching the failing one and, if found,
+    /// uses Semantic Kernel to generate a suggestion for a new working locator based on the differences between
+    /// the old and new view summaries. The returned string is an XPath expression representing the healed locator,
+    /// or null if no suggestion could be generated.
+    /// </summary>
+    /// <param name="failingLocator">The locator that is currently failing.</param>
+    /// <param name="newestVersionViewSummary">The latest view summary of the application.</param>
+    /// <param name="appLocation">Optional application location context.</param>
+    /// <returns>
+    /// The suggested healed XPath locator as a string, or null if healing is not possible.
+    /// </returns>
+    public static string TryHeal(string failingLocator, string newestVersionViewSummary, string appLocation = "")
     {
         var known = _db.SelfHealingLocators.FirstOrDefault(x =>
             x.Project == _project && x.AppLocation == appLocation &&
@@ -58,18 +75,26 @@ public static FindXpathStrategy TryHeal(string failingLocator, string newestVers
 
         var suggestion = SemanticKernelService.Kernel.InvokePromptAsync(prompt).Result.GetValue<string>()?.Trim();
 
-        Console.WriteLine("🧠 AI Healing Suggestion:");
-        Console.WriteLine($"❌ Failed: {failingLocator}");
-        Console.WriteLine($"✅ Suggest: {suggestion}");
+        Logger.LogWarning("🧠 AI Healing Suggestion:");
+        Logger.LogError($"❌ Failed: {failingLocator}");
+        Logger.LogWarning($"✅ Suggest: {suggestion}");
 
         if (!string.IsNullOrWhiteSpace(suggestion))
         {
-            return new FindXpathStrategy(suggestion);
+            return suggestion;
         }
 
         return null;
     }
 
+    /// <summary>
+    /// Saves or updates a working locator and its associated view summary in the local cache.
+    /// If the locator already exists for the given project and application location, its data is updated;
+    /// otherwise, a new entry is created.
+    /// </summary>
+    /// <param name="locator">The working locator to save.</param>
+    /// <param name="viewSummary">The view summary associated with the locator.</param>
+    /// <param name="appLocation">Optional application location context.</param>
     public static void SaveWorkingLocator(string locator, string viewSummary, string appLocation = "")
     {
         var currentSummary = viewSummary;
@@ -100,6 +125,10 @@ public static void SaveWorkingLocator(string locator, string viewSummary, string
         _db.SaveChanges();
     }
 
+    /// <summary>
+    /// Removes all self-healing locator entries for the current project from the local cache.
+    /// This is useful for cleanup or resetting the cache for a specific project.
+    /// </summary>
     public static void ClearProjectEntries()
     {
         var entriesToDelete = _db.SelfHealingLocators
@@ -110,14 +139,17 @@ public static void ClearProjectEntries()
         {
             _db.SelfHealingLocators.RemoveRange(entriesToDelete);
             _db.SaveChanges();
-            Console.WriteLine($"🗑️ Deleted {entriesToDelete.Count} self-healing locator entries for project: {_project}");
+            Logger.LogInformation($"🗑️ Deleted {entriesToDelete.Count} self-healing locator entries for project: {_project}");
         }
         else
         {
-            Console.WriteLine($"ℹ️ No entries found for project: {_project}");
+            Logger.LogInformation($"ℹ️ No entries found for project: {_project}");
         }
     }
 
+    /// <summary>
+    /// Disposes the local cache database context and releases any associated resources.
+    /// </summary>
     public static void Dispose()
     {
         _db?.Dispose();

…x.Web/llm/services/PageObjectsIndexer.cs …atrix.LLM/services/PageObjectsIndexer.cssrc/Bellatrix.Web/llm/services/PageObjectsIndexer.cs renamed to Bellatrix.LLM/services/PageObjectsIndexer.cs src/Bellatrix.Web/llm/services/PageObjectsIndexer.cs renamed to Bellatrix.LLM/services/PageObjectsIndexer.cs

@@ -14,13 +14,9 @@
 // <note>This file is part of an academic research project exploring autonomous test agents using LLMs and Semantic Kernel.
 // The architecture and agent logic are original contributions by Anton Angelov, forming the foundation for a PhD dissertation.
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
-using Bellatrix.LLM;
 using Microsoft.SemanticKernel;
-using System;
-using System.IO;
-using System.Linq;
 
-namespace Bellatrix.Web.LLM.services;
+namespace Bellatrix.LLM;
 
 public static class PageObjectsIndexer
 {

…Web/llm/services/SmartFailureAnalyzer.cs …rix.LLM/services/SmartFailureAnalyzer.cssrc/Bellatrix.Web/llm/services/SmartFailureAnalyzer.cs renamed to Bellatrix.LLM/services/SmartFailureAnalyzer.cs src/Bellatrix.Web/llm/services/SmartFailureAnalyzer.cs renamed to Bellatrix.LLM/services/SmartFailureAnalyzer.cs

@@ -15,17 +15,15 @@
 // The architecture and agent logic are original contributions by Anton Angelov, forming the foundation for a PhD dissertation.
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
 using Bellatrix.KeyVault;
-using Bellatrix.LLM;
-using Bellatrix.LLM.cache;
 using Bellatrix.LLM.Cache;
-using Bellatrix.LLM.settings;
+using Bellatrix.LLM.Settings;
 using Microsoft.SemanticKernel;
-using System;
-using System.Collections.Generic;
-using System.IO;
-using System.Linq;
 
-namespace Bellatrix.Web.LLM.services;
+namespace Bellatrix.LLM;
+/// <summary>
+/// Provides smart analysis and diagnosis of test failures using historical test execution data and LLM-powered reasoning.
+/// Responsible for saving successful test executions, diagnosing failures by comparing with previous passes, and extracting summaries from AI-generated reports.
+/// </summary>
 public static class SmartFailureAnalyzer
 {
     private static readonly LocatorCacheDbContext _db;
@@ -39,6 +37,12 @@ static SmartFailureAnalyzer()
         _project = settings.LocalCacheProjectName;
     }
 
+    /// <summary>
+    /// Saves a successful test execution to the local cache database, after filtering the log.
+    /// </summary>
+    /// <param name="testName">The full name of the test.</param>
+    /// <param name="fullLog">The complete log output from the test run.</param>
+    /// <param name="summaryJson">A JSON summary of the page state or test context.</param>
     public static void SaveTestPass(string testName, string fullLog, string summaryJson)
     {
         var cleaned = FilterLog(fullLog);
@@ -55,6 +59,16 @@ public static void SaveTestPass(string testName, string fullLog, string summaryJ
         _db.SaveChanges();
     }
 
+    /// <summary>
+    /// Diagnoses a test failure by comparing the current failing log and summary with the most recent passing execution.
+    /// Uses an LLM to generate a diagnosis and recommended actions.
+    /// </summary>
+    /// <param name="testName">The full name of the test.</param>
+    /// <param name="exceptionDetails">Details of the exception thrown during the test failure.</param>
+    /// <param name="currentLog">The log output from the failing test run.</param>
+    /// <param name="currentSummary">A summary of the current page or test state.</param>
+    /// <param name="screenshotFilePath">Optional file path to a screenshot of the failure.</param>
+    /// <returns>A string containing the AI-generated diagnosis and recommendations.</returns>
     public static string Diagnose(string testName, string exceptionDetails, string currentLog, string currentSummary, string screenshotFilePath)
     {
         var lastPass = _db.SmartTestExecutions
@@ -88,6 +102,14 @@ public static string Diagnose(string testName, string exceptionDetails, string c
         return suggestion;
     }
 
+    /// <summary>
+    /// Extracts a summary and the main body from an AI-generated report.
+    /// The summary is everything up to the "Recommended Actions" section; the body is the rest.
+    /// </summary>
+    /// <param name="fullText">The full AI-generated report text.</param>
+    /// <returns>
+    /// A tuple where the first item is the summary (string), and the second item is the body (string).
+    /// </returns>
     public static (string Summary, string Body) ExtractSummaryAndBody(string fullText)
     {
         if (string.IsNullOrWhiteSpace(fullText))
@@ -125,7 +147,11 @@ public static (string Summary, string Body) ExtractSummaryAndBody(string fullTex
         );
     }
 
-
+    /// <summary>
+    /// Filters out lines from the test log that start with specific emoji markers (warnings, AI, pass/fail indicators).
+    /// </summary>
+    /// <param name="fullLog">The complete log output from the test run.</param>
+    /// <returns>The filtered log as a string, with unwanted lines removed.</returns>
     public static string FilterLog(string fullLog) =>
         string.Join(Environment.NewLine, fullLog
             .Split(Environment.NewLine)

Bellatrix.LLM/settings/LargeLanguageModelsSettings.cs

@@ -16,7 +16,7 @@
 // Please cite or credit appropriately if reusing in academic or commercial work.</note>
 using SemanticKernelWebDriverPoC;
 
-namespace Bellatrix.LLM.settings;
+namespace Bellatrix.LLM.Settings;
 public class LargeLanguageModelsSettings
 {
     public List<ModelSettings> ModelSettings { get; set; }