@memberjunction/aiengine 3.4.0 → 4.1.0

package/dist/AIEngine.js

@@ -1,56 +1,50 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LoadAIEngine = exports.AIEngine = exports.EntityAIActionParams = exports.AIActionParams = void 0;
-const ai_1 = require("@memberjunction/ai");
-const core_1 = require("@memberjunction/core");
-const global_1 = require("@memberjunction/global");
-const ai_engine_base_1 = require("@memberjunction/ai-engine-base");
-const ai_vectors_memory_1 = require("@memberjunction/ai-vectors-memory");
-const AgentEmbeddingService_1 = require("./services/AgentEmbeddingService");
-const ActionEmbeddingService_1 = require("./services/ActionEmbeddingService");
-const actions_base_1 = require("@memberjunction/actions-base");
-class AIActionParams {
+import { BaseLLM, BaseModel, ChatParams, ChatMessageRole, GetAIAPIKey, BaseEmbeddings } from "@memberjunction/ai";
+import { LogError, Metadata } from "@memberjunction/core";
+import { BaseSingleton, MJGlobal } from "@memberjunction/global";
+import { AIEngineBase } from "@memberjunction/ai-engine-base";
+import { SimpleVectorService } from "@memberjunction/ai-vectors-memory";
+import { AgentEmbeddingService } from "./services/AgentEmbeddingService.js";
+import { ActionEmbeddingService } from "./services/ActionEmbeddingService.js";
+import { ActionEngineBase } from "@memberjunction/actions-base";
+/**
+ * @deprecated AI Actions are deprecated. Use AIPromptRunner with the new AI Prompt system instead.
+ */
+export class AIActionParams {
 }
-exports.AIActionParams = AIActionParams;
-class EntityAIActionParams extends AIActionParams {
+/**
+ * @deprecated Entity AI Actions are deprecated. Use AIPromptRunner with the new AI Prompt system instead.
+ */
+export class EntityAIActionParams extends AIActionParams {
 }
-exports.EntityAIActionParams = EntityAIActionParams;
-class AIEngine extends global_1.BaseSingleton {
+/**
+ * Server-side AI Engine that wraps AIEngineBase and adds server-only capabilities.
+ *
+ * This class uses composition (containment) rather than inheritance to avoid duplicate
+ * data loading. It delegates all base functionality to AIEngineBase.Instance while
+ * adding server-specific features like embeddings, vector search, and LLM execution.
+ *
+ * @description ONLY USE ON SERVER-SIDE. For metadata only, use the AIEngineBase class which can be used anywhere.
+ */
+export class AIEngine extends BaseSingleton {
     constructor() {
         super(...arguments);
         this.EmbeddingModelTypeName = 'Embeddings';
         this.LocalEmbeddingModelVendorName = 'LocalEmbeddings';
+        // Vector service for agent embeddings - initialized during Config
         this._agentVectorService = null;
+        // Vector service for action embeddings - initialized during Config
         this._actionVectorService = null;
+        // Vector service for note embeddings - initialized during Config
         this._noteVectorService = null;
+        // Vector service for example embeddings - initialized during Config
         this._exampleVectorService = null;
+        // Actions loaded from database
         this._actions = [];
+        // Embedding caches to track which items have embeddings generated
         this._agentEmbeddingsCache = new Map();
         this._actionEmbeddingsCache = new Map();
         this._embeddingsGenerated = false;
+        // Loading state management
         this._loaded = false;
         this._loading = false;
         this._loadingPromise = null;
@@ -58,12 +52,19 @@ class AIEngine extends global_1.BaseSingleton {
     static get Instance() {
         return super.getInstance();
     }
+    // ========================================================================
+    // Delegated Properties from AIEngineBase
+    // All base metadata is accessed through AIEngineBase.Instance
+    // ========================================================================
+    /** Access to the underlying AIEngineBase instance */
     get Base() {
-        return ai_engine_base_1.AIEngineBase.Instance;
+        return AIEngineBase.Instance;
     }
+    /** Returns true if both the base engine and server capabilities are loaded */
     get Loaded() {
         return this._loaded && this.Base.Loaded;
     }
+    // Delegate all AIEngineBase public getters
     get Agents() { return this.Base.Agents; }
     get AgentRelationships() { return this.Base.AgentRelationships; }
     get AgentTypes() { return this.Base.AgentTypes; }
@@ -102,11 +103,15 @@ class AIEngine extends global_1.BaseSingleton {
     get AgentSteps() { return this.Base.AgentSteps; }
     get AgentStepPaths() { return this.Base.AgentStepPaths; }
     get ModelActions() { return this.Base.ModelActions; }
+    /** @deprecated Use the new Action system instead */
     get Actions() { return this.Base.Actions; }
+    /** @deprecated Use the new Action system instead */
     get EntityAIActions() { return this.Base.EntityAIActions; }
+    // Modality getters - delegated from AIEngineBase
     get Modalities() { return this.Base.Modalities; }
     get AgentModalities() { return this.Base.AgentModalities; }
     get ModelModalities() { return this.Base.ModelModalities; }
+    // Modality helper methods - delegated from AIEngineBase
     GetModalityByName(name) {
         return this.Base.GetModalityByName(name);
     }
@@ -128,6 +133,7 @@ class AIEngine extends global_1.BaseSingleton {
     GetAgentSupportedInputModalities(agentId) {
         return this.Base.GetAgentSupportedInputModalities(agentId);
     }
+    // Delegate AIEngineBase public methods
     async GetHighestPowerModel(vendorName, modelType, contextUser) {
         return this.Base.GetHighestPowerModel(vendorName, modelType, contextUser);
     }
@@ -161,9 +167,26 @@ class AIEngine extends global_1.BaseSingleton {
     GetConfigurationParam(configurationId, paramName) {
         return this.Base.GetConfigurationParam(configurationId, paramName);
     }
+    /**
+     * Returns the inheritance chain for a configuration, starting with the specified
+     * configuration and walking up through parent configurations to the root.
+     * Delegates to AIEngineBase.GetConfigurationChain.
+     *
+     * @param configurationId - The ID of the configuration to get the chain for
+     * @returns Array of AIConfigurationEntity objects representing the inheritance chain
+     * @throws Error if a circular reference is detected in the configuration hierarchy
+     */
     GetConfigurationChain(configurationId) {
         return this.Base.GetConfigurationChain(configurationId);
     }
+    /**
+     * Returns all configuration parameters for a configuration, including inherited
+     * parameters from parent configurations. Child parameters override parent parameters.
+     * Delegates to AIEngineBase.GetConfigurationParamsWithInheritance.
+     *
+     * @param configurationId - The ID of the configuration to get parameters for
+     * @returns Array of AIConfigurationParamEntity objects, with child overrides applied
+     */
     GetConfigurationParamsWithInheritance(configurationId) {
         return this.Base.GetConfigurationParamsWithInheritance(configurationId);
     }
@@ -206,22 +229,56 @@ class AIEngine extends global_1.BaseSingleton {
     async RefreshAgentPermissionsCache(agentId, user) {
         return this.Base.RefreshAgentPermissionsCache(agentId, user);
     }
+    // ========================================================================
+    // Server-Only Properties
+    // ========================================================================
+    /**
+     * Get the agent vector service for semantic search.
+     * Initialized during Config - will be null before AIEngine.Config() completes.
+     */
     get AgentVectorService() {
         return this._agentVectorService;
     }
+    /**
+     * Get the action vector service for semantic search.
+     * Initialized during Config - will be null before AIEngine.Config() completes.
+     */
     get ActionVectorService() {
         return this._actionVectorService;
     }
+    /**
+     * Get all available actions loaded from the database.
+     * Loaded during Config() - will be empty before AIEngine.Config() completes.
+     * NOTE: This returns ActionEntity (MJ Action system), not the deprecated AIActionEntity.
+     * For deprecated AI Actions, see the inherited Actions property.
+     */
     get SystemActions() {
         return this._actions;
     }
+    // ========================================================================
+    // Config - Main Entry Point
+    // ========================================================================
+    /**
+     * Configures the AIEngine by first ensuring AIEngineBase is configured,
+     * then loading server-specific capabilities (embeddings, actions, etc.).
+     *
+     * This method is safe to call from multiple places concurrently - it will
+     * return the same promise to all callers during loading.
+     *
+     * @param forceRefresh - If true, forces a full reload even if already loaded
+     * @param contextUser - User context for server-side operations (required)
+     * @param provider - Optional metadata provider override
+     */
     async Config(forceRefresh, contextUser, provider) {
+        // If already loaded and not forcing refresh, return immediately
         if (this._loaded && !forceRefresh) {
             return;
         }
+        // If currently loading, return the existing promise so all callers wait together
         if (this._loading && this._loadingPromise) {
             return this._loadingPromise;
         }
+        // Start loading
         this._loading = true;
         this._loadingPromise = this.innerLoad(forceRefresh, contextUser, provider);
         try {
@@ -232,110 +289,187 @@ class AIEngine extends global_1.BaseSingleton {
             this._loadingPromise = null;
         }
     }
+    /**
+     * Internal loading logic - separated for clean promise management
+     */
     async innerLoad(forceRefresh, contextUser, provider) {
         try {
             this._contextUser = contextUser;
-            await ai_engine_base_1.AIEngineBase.Instance.Config(forceRefresh ?? false, contextUser, provider);
-            await this.loadServerCapabilities(contextUser);
+            // First, ensure AIEngineBase is configured
+            // This is where all the metadata loading happens - we share that data
+            await AIEngineBase.Instance.Config(forceRefresh ?? false, contextUser, provider);
+            // Now load server-specific capabilities
+            await this.RefreshServerSpecificMetadata(contextUser);
             this._loaded = true;
         }
         catch (error) {
-            (0, core_1.LogError)(error);
+            LogError(error);
             throw error;
         }
     }
-    async loadServerCapabilities(contextUser) {
-        await this.loadActions(contextUser);
+    /**
+     * Refreshes the server metadata including active actions.
+     * Refreshes the embeddings in the engine's vector service for
+     *  - Agents (dynamic recalc of embeddings)
+     *  - Actions (dynamic recalc of embeddings)
+     *  - Notes (parsed from DB)
+     *  - Examples (parsed from DB)
+     *
+     * If you only need to refresh specific elements noted above, call the individual methods:
+     *  - RefreshActions (refreshes just the server side action metadata - e.g. 'Active' Actions)
+     *  - RefreshActionEmbeddings (dynamic recalc of embedings from stored data)
+     *  - RefreshAgentEmbeddings (dynamic recalc of embeddings from stored data)
+     *  - RefreshNoteEmbeddings
+     *  - RefreshExampleEmbeddings
+     */
+    async RefreshServerSpecificMetadata(contextUser) {
+        // Load actions from the Action system
+        await this.RefreshActions(contextUser);
+        // Load all embeddings in parallel since they are independent
         await Promise.all([
-            this.loadAgentEmbeddings(),
-            this.loadActionEmbeddings(),
-            this.loadNoteEmbeddings(contextUser),
-            this.loadExampleEmbeddings(contextUser)
+            this.RefreshAgentEmbeddings(),
+            this.RefreshActionEmbeddings(),
+            this.RefreshNoteEmbeddings(contextUser),
+            this.RefreshExampleEmbeddings(contextUser)
         ]);
         this._embeddingsGenerated = true;
     }
+    // ========================================================================
+    // Embedding Generation Methods
+    // ========================================================================
+    /**
+     * Force regeneration of all embeddings for agents and actions.
+     *
+     * Use this method when:
+     * - Switching to a different embedding model
+     * - Agent or Action descriptions have been significantly updated
+     * - You want to ensure embeddings are up-to-date after bulk changes
+     * - Troubleshooting embedding-related issues
+     *
+     * Note: This is an expensive operation and should not be called frequently.
+     * Normal auto-refresh operations will NOT regenerate embeddings to avoid performance issues.
+     *
+     * @param contextUser - User context for database operations (required on server-side)
+     */
     async RegenerateEmbeddings(contextUser) {
         try {
+            // Clear the caches
             this._agentEmbeddingsCache.clear();
             this._actionEmbeddingsCache.clear();
             this._embeddingsGenerated = false;
+            // Clear the vector services
             this._agentVectorService = null;
             this._actionVectorService = null;
-            await this.loadActions(contextUser);
-            await this.loadAgentEmbeddings();
-            await this.loadActionEmbeddings();
+            // Reload actions and regenerate embeddings
+            await this.RefreshActions(contextUser);
+            await this.RefreshAgentEmbeddings();
+            await this.RefreshActionEmbeddings();
             this._embeddingsGenerated = true;
         }
         catch (error) {
-            (0, core_1.LogError)('AIEngine: Failed to regenerate embeddings', undefined, error instanceof Error ? error : undefined);
+            LogError('AIEngine: Failed to regenerate embeddings', undefined, error instanceof Error ? error : undefined);
             throw error;
         }
     }
-    async loadAgentEmbeddings() {
+    /**
+     * Refreshes Agent embeddings - agents are pre-loaded at this point, but we need
+     * to generate, dynamically, embeddings from the text stored in the agent. This is not a
+     * cheap operation, use it sparingly.
+     */
+    async RefreshAgentEmbeddings() {
         try {
-            const agents = this.Agents;
+            // Use agents already loaded by base class
+            const agents = this.Agents; // Delegates to AIEngineBase
             if (!agents || agents.length === 0) {
                 return;
             }
+            // Filter out restricted agents - they should not be discoverable
             const nonRestrictedAgents = agents.filter(agent => !agent.IsRestricted);
+            // Filter to only agents that don't have embeddings yet
             const agentsNeedingEmbeddings = nonRestrictedAgents.filter(agent => !this._agentEmbeddingsCache.has(agent.ID));
             if (agentsNeedingEmbeddings.length === 0) {
                 return;
             }
-            const entries = await AgentEmbeddingService_1.AgentEmbeddingService.GenerateAgentEmbeddings(agentsNeedingEmbeddings, (text) => this.EmbedTextLocal(text));
+            // Generate embeddings using static utility method
+            const entries = await AgentEmbeddingService.GenerateAgentEmbeddings(agentsNeedingEmbeddings, (text) => this.EmbedTextLocal(text));
+            // Mark these agents as having embeddings
             for (const agent of agentsNeedingEmbeddings) {
                 this._agentEmbeddingsCache.set(agent.ID, true);
             }
+            // Load into vector service (create if needed, or add to existing)
             if (!this._agentVectorService) {
-                this._agentVectorService = new ai_vectors_memory_1.SimpleVectorService();
+                this._agentVectorService = new SimpleVectorService();
             }
             this._agentVectorService.LoadVectors(entries);
         }
         catch (error) {
-            (0, core_1.LogError)(`AIEngine: Failed to load agent embeddings: ${error instanceof Error ? error.message : String(error)}`);
+            LogError(`AIEngine: Failed to load agent embeddings: ${error instanceof Error ? error.message : String(error)}`);
+            // Don't throw - allow AIEngine to continue loading even if embeddings fail
         }
     }
-    async loadActions(contextUser) {
+    /**
+     * Loads Active actions from the base engine (contained within this class). Does **not** refresh from the database, simply
+     * pulls the latest `Active` actions from the base class into its server side only array.
+     */
+    async RefreshActions(contextUser) {
         try {
-            await actions_base_1.ActionEngineBase.Instance.Config(false, contextUser);
-            const actions = actions_base_1.ActionEngineBase.Instance.Actions.filter(a => a.Status === 'Active');
+            await ActionEngineBase.Instance.Config(false, contextUser);
+            const actions = ActionEngineBase.Instance.Actions.filter(a => a.Status === 'Active');
             if (actions && actions.length > 0) {
                 this._actions = actions;
             }
             else {
-                (0, core_1.LogError)('AIEngine: No active actions found during load');
+                LogError('AIEngine: No active actions found during load');
                 this._actions = [];
             }
         }
         catch (error) {
-            (0, core_1.LogError)(`AIEngine: Error loading actions: ${error instanceof Error ? error.message : String(error)}`);
+            LogError(`AIEngine: Error loading actions: ${error instanceof Error ? error.message : String(error)}`);
             this._actions = [];
         }
     }
-    async loadActionEmbeddings() {
+    /**
+     * Dynamically calculation of embeddings for all `Active` actions. Assumes that the internal Actions array is up to date, call
+     * @see RefreshActions first if you do not think they are already.
+     *
+     * This operation dynamically calculates embeddings from the text in the Action metadata and is an expensive operation, use it
+     * sparingly.
+     */
+    async RefreshActionEmbeddings() {
         try {
             const actions = this._actions;
             if (!actions || actions.length === 0) {
                 return;
             }
+            // Filter to only actions that don't have embeddings yet
             const actionsNeedingEmbeddings = actions.filter(action => !this._actionEmbeddingsCache.has(action.ID));
             if (actionsNeedingEmbeddings.length === 0) {
                 return;
             }
-            const entries = await ActionEmbeddingService_1.ActionEmbeddingService.GenerateActionEmbeddings(actionsNeedingEmbeddings, (text) => this.EmbedTextLocal(text));
+            // Generate embeddings using static utility method
+            const entries = await ActionEmbeddingService.GenerateActionEmbeddings(actionsNeedingEmbeddings, (text) => this.EmbedTextLocal(text));
+            // Mark these actions as having embeddings
             for (const action of actionsNeedingEmbeddings) {
                 this._actionEmbeddingsCache.set(action.ID, true);
             }
+            // Load into vector service (create if needed, or add to existing)
             if (!this._actionVectorService) {
-                this._actionVectorService = new ai_vectors_memory_1.SimpleVectorService();
+                this._actionVectorService = new SimpleVectorService();
             }
             this._actionVectorService.LoadVectors(entries);
         }
         catch (error) {
-            (0, core_1.LogError)(`AIEngine: Failed to load action embeddings: ${error instanceof Error ? error.message : String(error)}`);
+            LogError(`AIEngine: Failed to load action embeddings: ${error instanceof Error ? error.message : String(error)}`);
+            // Don't throw - allow AIEngine to continue loading even if embeddings fail
         }
     }
-    async loadNoteEmbeddings(contextUser) {
+    /**
+     * Refresh the vector service with the latest persisted vectors that are stored in the Agent Notes
+     * table. This does **not** calculate embeddings, that is done by the AI Agent Note sub-class upon save
+     * as needed. This method simply uses the stored vectors and parses them from their JSON serialized format into
+     * vectors that are used by the vector service.
+     */
+    async RefreshNoteEmbeddings(contextUser) {
         try {
             const notes = this.AgentNotes.filter(n => n.Status === 'Active' && n.EmbeddingVector);
             if (notes.length === 0) {
@@ -344,24 +478,78 @@ class AIEngine extends global_1.BaseSingleton {
             const entries = notes.map(note => ({
                 key: note.ID,
                 vector: JSON.parse(note.EmbeddingVector),
-                metadata: {
-                    id: note.ID,
-                    agentId: note.AgentID,
-                    userId: note.UserID,
-                    companyId: note.CompanyID,
-                    type: note.Type,
-                    noteText: note.Note,
-                    noteEntity: note
-                }
+                metadata: this.packageNoteMetadata(note)
             }));
-            this._noteVectorService = new ai_vectors_memory_1.SimpleVectorService();
+            this._noteVectorService = new SimpleVectorService();
             this._noteVectorService.LoadVectors(entries);
         }
         catch (error) {
-            (0, core_1.LogError)(`AIEngine: Failed to load note embeddings: ${error instanceof Error ? error.message : String(error)}`);
+            LogError(`AIEngine: Failed to load note embeddings: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Takes in a note and packages up the metadata for the vector service
+     * @param note
+     */
+    packageNoteMetadata(note) {
+        return {
+            id: note.ID,
+            agentId: note.AgentID,
+            userId: note.UserID,
+            companyId: note.CompanyID,
+            type: note.Type,
+            noteText: note.Note,
+            noteEntity: note
+        };
+    }
+    /**
+     * Updates the vector service to the latest vector containd within the specified agent note that is passed in
+     * @param note
+     */
+    AddOrUpdateSingleNoteEmbedding(note) {
+        if (this._noteVectorService) {
+            this._noteVectorService.AddOrUpdateVector(note.ID, JSON.parse(note.EmbeddingVector), this.packageNoteMetadata(note));
+        }
+        else {
+            throw new Error('note vector service not initialized, error state');
+        }
+    }
+    /**
+     * Takes in an example and packages up the metadata for the vector service
+     * @param example
+     */
+    packageExampleMetadata(example) {
+        return {
+            id: example.ID,
+            agentId: example.AgentID,
+            userId: example.UserID,
+            companyId: example.CompanyID,
+            type: example.Type,
+            exampleInput: example.ExampleInput,
+            exampleOutput: example.ExampleOutput,
+            successScore: example.SuccessScore,
+            exampleEntity: example
+        };
+    }
+    /**
+     * Updates the vector service to the latest vector contained within the specified agent example that is passed in
+     * @param example
+     */
+    AddOrUpdateSingleExampleEmbedding(example) {
+        if (this._exampleVectorService) {
+            this._exampleVectorService.AddOrUpdateVector(example.ID, JSON.parse(example.EmbeddingVector), this.packageExampleMetadata(example));
+        }
+        else {
+            throw new Error('example vector service not initialized, error state');
         }
     }
-    async loadExampleEmbeddings(contextUser) {
+    /**
+     * Refresh the vector service with the latest persisted vectors that are stored in the Agent Examples
+     * table. This does **not** calculate embeddings, that is done by the AI Agent Example sub-class upon save
+     * as needed. This method simply uses the stored vectors and parses them from their JSON serialized format into
+     * vectors that are used by the vector service.
+     */
+    async RefreshExampleEmbeddings(contextUser) {
         try {
             const examples = this.AgentExamples.filter(e => e.Status === 'Active' && e.EmbeddingVector);
             if (examples.length === 0) {
@@ -370,73 +558,64 @@ class AIEngine extends global_1.BaseSingleton {
             const entries = examples.map(example => ({
                 key: example.ID,
                 vector: JSON.parse(example.EmbeddingVector),
-                metadata: {
-                    id: example.ID,
-                    agentId: example.AgentID,
-                    userId: example.UserID,
-                    companyId: example.CompanyID,
-                    type: example.Type,
-                    exampleInput: example.ExampleInput,
-                    exampleOutput: example.ExampleOutput,
-                    successScore: example.SuccessScore,
-                    exampleEntity: example
-                }
+                metadata: this.packageExampleMetadata(example)
             }));
-            this._exampleVectorService = new ai_vectors_memory_1.SimpleVectorService();
+            this._exampleVectorService = new SimpleVectorService();
             this._exampleVectorService.LoadVectors(entries);
         }
         catch (error) {
-            (0, core_1.LogError)(`AIEngine: Failed to load example embeddings: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    async generateSingleAgentEmbedding(agent) {
-        try {
-            if (agent.IsRestricted) {
-                return;
-            }
-            const entries = await AgentEmbeddingService_1.AgentEmbeddingService.GenerateAgentEmbeddings([agent], (text) => this.EmbedTextLocal(text));
-            if (entries.length > 0) {
-                this._agentEmbeddingsCache.set(agent.ID, true);
-                if (!this._agentVectorService) {
-                    this._agentVectorService = new ai_vectors_memory_1.SimpleVectorService();
-                }
-                this._agentVectorService.LoadVectors(entries);
-            }
-        }
-        catch (error) {
-            (0, core_1.LogError)(`AIEngine: Failed to generate embedding for agent ${agent.Name}: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    async generateSingleActionEmbedding(action) {
-        try {
-            const entries = await ActionEmbeddingService_1.ActionEmbeddingService.GenerateActionEmbeddings([action], (text) => this.EmbedTextLocal(text));
-            if (entries.length > 0) {
-                this._actionEmbeddingsCache.set(action.ID, true);
-                if (!this._actionVectorService) {
-                    this._actionVectorService = new ai_vectors_memory_1.SimpleVectorService();
-                }
-                this._actionVectorService.LoadVectors(entries);
-            }
-        }
-        catch (error) {
-            (0, core_1.LogError)(`AIEngine: Failed to generate embedding for action ${action.Name}: ${error instanceof Error ? error.message : String(error)}`);
+            LogError(`AIEngine: Failed to load example embeddings: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    // ========================================================================
+    // LLM Utility Methods
+    // ========================================================================
+    /**
+     * Prepares standard chat parameters with system and user messages.
+     *
+     * @param userPrompt The user message/query to send to the model
+     * @param systemPrompt Optional system prompt to set context/persona for the model
+     * @returns Array of properly formatted chat messages
+     */
     PrepareChatMessages(userPrompt, systemPrompt) {
         const messages = [];
         if (systemPrompt && systemPrompt.length > 0) {
-            messages.push({ role: ai_1.ChatMessageRole.system, content: systemPrompt });
+            messages.push({ role: ChatMessageRole.system, content: systemPrompt });
         }
-        messages.push({ role: ai_1.ChatMessageRole.user, content: userPrompt });
+        messages.push({ role: ChatMessageRole.user, content: userPrompt });
         return messages;
     }
+    /**
+     * Prepares an LLM model instance with the appropriate parameters.
+     * This method handles common tasks needed before calling an LLM:
+     * - Loading AI metadata if needed
+     * - Selecting the appropriate model (user-provided or highest power)
+     * - Getting the correct API key
+     * - Creating the LLM instance
+     *
+     * @param contextUser The user context for authentication and permissions
+     * @param model Optional specific model to use, otherwise uses highest power LLM
+     * @param apiKey Optional API key to use with the model
+     * @returns Object containing the prepared model instance and model information
+     */
     async PrepareLLMInstance(contextUser, model, apiKey) {
         await AIEngine.Instance.Config(false, contextUser);
         const modelToUse = model ? model : await this.GetHighestPowerLLM(undefined, contextUser);
-        const apiKeyToUse = apiKey ? apiKey : (0, ai_1.GetAIAPIKey)(modelToUse.DriverClass);
-        const modelInstance = global_1.MJGlobal.Instance.ClassFactory.CreateInstance(ai_1.BaseLLM, modelToUse.DriverClass, apiKeyToUse);
+        const apiKeyToUse = apiKey ? apiKey : GetAIAPIKey(modelToUse.DriverClass);
+        const modelInstance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseLLM, modelToUse.DriverClass, apiKeyToUse);
         return { modelInstance, modelToUse };
     }
+    /**
+     * Executes a simple completion task using the provided parameters.
+     *
+     * @param userPrompt The user message/query to send to the model
+     * @param contextUser The user context for authentication and permissions
+     * @param systemPrompt Optional system prompt to set context/persona for the model
+     * @param model Optional specific model to use, otherwise uses highest power LLM
+     * @param apiKey Optional API key to use with the model
+     * @returns The text response from the LLM
+     * @throws Error if user prompt is not provided or if there are issues with model creation
+     */
     async SimpleLLMCompletion(userPrompt, contextUser, systemPrompt, model, apiKey) {
         try {
             if (!userPrompt || userPrompt.length === 0) {
@@ -444,7 +623,7 @@ class AIEngine extends global_1.BaseSingleton {
             }
             const { modelInstance, modelToUse } = await this.PrepareLLMInstance(contextUser, model, apiKey);
             const messages = this.PrepareChatMessages(userPrompt, systemPrompt);
-            const params = new ai_1.ChatParams();
+            const params = new ChatParams();
             params.messages = messages;
             params.model = modelToUse.APIName;
             const result = await modelInstance.ChatCompletion(params);
@@ -455,10 +634,24 @@ class AIEngine extends global_1.BaseSingleton {
                 throw new Error(`Error executing LLM model ${modelToUse.Name} : ${result.errorMessage}`);
         }
         catch (e) {
-            (0, core_1.LogError)(e);
+            LogError(e);
             throw e;
         }
     }
+    /**
+     * Executes multiple parallel chat completions with the same model but potentially different parameters.
+     *
+     * @param userPrompt The user's message/question to send to the model
+     * @param contextUser The user context for authentication and logging
+     * @param systemPrompt Optional system prompt to set the context/persona
+     * @param iterations Number of parallel completions to run (default: 3)
+     * @param temperatureIncrement The amount to increment temperature for each iteration (default: 0.1)
+     * @param baseTemperature The starting temperature value (default: 0.7)
+     * @param model Optional specific model to use, otherwise uses highest power LLM
+     * @param apiKey Optional API key to use with the model
+     * @param callbacks Optional callbacks for monitoring progress
+     * @returns Array of ChatResult objects, one for each parallel completion
+     */
     async ParallelLLMCompletions(userPrompt, contextUser, systemPrompt, iterations = 3, temperatureIncrement = 0.1, baseTemperature = 0.7, model, apiKey, callbacks) {
         try {
             if (!userPrompt || userPrompt.length === 0) {
@@ -470,7 +663,7 @@ class AIEngine extends global_1.BaseSingleton {
             const { modelInstance, modelToUse } = await this.PrepareLLMInstance(contextUser, model, apiKey);
             const messages = this.PrepareChatMessages(userPrompt, systemPrompt);
             const paramsArray = Array(iterations).fill(0).map((_, i) => {
-                const params = new ai_1.ChatParams();
+                const params = new ChatParams();
                 params.messages = [...messages];
                 params.model = modelToUse.APIName;
                 params.temperature = baseTemperature + (i * temperatureIncrement);
@@ -479,12 +672,19 @@ class AIEngine extends global_1.BaseSingleton {
             return await modelInstance.ChatCompletions(paramsArray, callbacks);
         }
         catch (e) {
-            (0, core_1.LogError)(e);
+            LogError(e);
             throw e;
         }
     }
+    // ========================================================================
+    // Embedding Methods
+    // ========================================================================
+    /**
+     * Returns an array of the local embedding models, sorted with the highest power models first
+     */
     get LocalEmbeddingModels() {
         const embeddingModels = this.Models.filter(m => {
+            // Guard against AIModelType being non-string (defensive coding for data issues)
             const modelType = typeof m.AIModelType === 'string' ? m.AIModelType.trim().toLowerCase() : '';
             const vendor = typeof m.Vendor === 'string' ? m.Vendor.trim().toLowerCase() : '';
             return modelType === this.EmbeddingModelTypeName.toLowerCase() &&
@@ -492,51 +692,78 @@ class AIEngine extends global_1.BaseSingleton {
         });
         return embeddingModels.sort((a, b) => (b.PowerRank || 0) - (a.PowerRank || 0));
     }
+    /**
+     * Returns the highest power local embedding model
+     */
     get HighestPowerLocalEmbeddingModel() {
         const models = this.LocalEmbeddingModels;
         return models && models.length > 0 ? models[0] : null;
     }
+    /**
+     * Returns the lowest power local embedding model
+     */
     get LowestPowerLocalEmbeddingModel() {
         const models = this.LocalEmbeddingModels;
         return models && models.length > 0 ? models[models.length - 1] : null;
     }
+    /**
+     * Helper method that generates an embedding for the given text using the highest power local embedding model.
+     */
     async EmbedTextLocal(text) {
         const model = this.HighestPowerLocalEmbeddingModel;
         if (!model) {
-            (0, core_1.LogError)('AIEngine: No local embedding model found. Cannot generate embedding.');
+            LogError('AIEngine: No local embedding model found. Cannot generate embedding.');
             return null;
         }
         const result = await this.EmbedText(model, text);
         return { result, model };
     }
+    /**
+     * Helper method to instantiate a class instance for the given model and calculate an embedding
+     * vector from the provided text.
+     */
     async EmbedText(model, text, apiKey) {
         const params = {
             text: text,
             model: model.APIName
         };
-        const embedding = global_1.MJGlobal.Instance.ClassFactory.CreateInstance(ai_1.BaseEmbeddings, model.DriverClass, apiKey);
+        const embedding = MJGlobal.Instance.ClassFactory.CreateInstance(BaseEmbeddings, model.DriverClass, apiKey);
         if (!embedding) {
-            (0, core_1.LogError)(`AIEngine: Failed to create embedding instance for model ${model.Name}. Skipping embedding generation.`);
+            LogError(`AIEngine: Failed to create embedding instance for model ${model.Name}. Skipping embedding generation.`);
             return null;
         }
         const result = await embedding.EmbedText(params);
         return result;
     }
+    // ========================================================================
+    // Semantic Search Methods
+    // ========================================================================
+    /**
+     * Find agents similar to a task description using semantic search.
+     */
     async FindSimilarAgents(taskDescription, topK = 5, minSimilarity = 0.5) {
         if (!this._agentVectorService) {
             throw new Error('Agent embeddings not loaded. Ensure AIEngine.Config() has completed.');
         }
-        return AgentEmbeddingService_1.AgentEmbeddingService.FindSimilarAgents(this._agentVectorService, taskDescription, (text) => this.EmbedTextLocal(text), topK, minSimilarity);
+        return AgentEmbeddingService.FindSimilarAgents(this._agentVectorService, taskDescription, (text) => this.EmbedTextLocal(text), topK, minSimilarity);
     }
+    /**
+     * Find actions similar to a task description using semantic search.
+     */
     async FindSimilarActions(taskDescription, topK = 10, minSimilarity = 0.5) {
         if (!this._actionVectorService) {
             throw new Error('Action embeddings not loaded. Ensure AIEngine.Config() has completed.');
         }
-        return ActionEmbeddingService_1.ActionEmbeddingService.FindSimilarActions(this._actionVectorService, taskDescription, (text) => this.EmbedTextLocal(text), topK, minSimilarity);
+        return ActionEmbeddingService.FindSimilarActions(this._actionVectorService, taskDescription, (text) => this.EmbedTextLocal(text), topK, minSimilarity);
     }
+    /**
+     * Find notes similar to query text using semantic search.
+     * Falls back to returning notes from cache if vector service is unavailable.
+     */
     async FindSimilarAgentNotes(queryText, agentId, userId, companyId, topK = 5, minSimilarity = 0.5) {
         if (!this._noteVectorService) {
-            (0, core_1.LogError)('FindSimilarAgentNotes: Note vector service not initialized. Falling back to cached notes without semantic ranking.');
+            // Vector service not available - fall back to returning notes from cache filtered by scope
+            LogError('FindSimilarAgentNotes: Note vector service not initialized. Falling back to cached notes without semantic ranking.');
             return this.fallbackGetNotesFromCache(agentId, userId, companyId, topK);
         }
         if (!queryText || queryText.trim().length === 0) {
@@ -544,7 +771,7 @@ class AIEngine extends global_1.BaseSingleton {
         }
         const queryEmbedding = await this.EmbedTextLocal(queryText);
         if (!queryEmbedding || !queryEmbedding.result || queryEmbedding.result.vector.length === 0) {
-            (0, core_1.LogError)('FindSimilarAgentNotes: Failed to generate embedding for query text. Falling back to cached notes.');
+            LogError('FindSimilarAgentNotes: Failed to generate embedding for query text. Falling back to cached notes.');
             return this.fallbackGetNotesFromCache(agentId, userId, companyId, topK);
         }
         const needsFiltering = agentId || userId || companyId;
@@ -563,6 +790,10 @@ class AIEngine extends global_1.BaseSingleton {
             similarity: r.score
         }));
     }
+    /**
+     * Fallback method to get notes from cache when vector service is unavailable.
+     * Returns notes filtered by scope, sorted by creation date.
+     */
     fallbackGetNotesFromCache(agentId, userId, companyId, topK = 5) {
         const notes = this.AgentNotes.filter(n => {
             if (n.Status !== 'Active')
@@ -575,17 +806,24 @@ class AIEngine extends global_1.BaseSingleton {
                 return false;
             return true;
         });
+        // Sort by creation date (most recent first) and take topK
         const sorted = notes
             .sort((a, b) => (b.__mj_CreatedAt?.getTime() || 0) - (a.__mj_CreatedAt?.getTime() || 0))
             .slice(0, topK);
+        // Return with similarity of 0 to indicate no semantic ranking was applied
         return sorted.map(note => ({
             note,
             similarity: 0
         }));
     }
+    /**
+     * Find examples similar to query text using semantic search.
+     * Falls back to returning examples from cache if vector service is unavailable.
+     */
     async FindSimilarAgentExamples(queryText, agentId, userId, companyId, topK = 3, minSimilarity = 0.5) {
         if (!this._exampleVectorService) {
-            (0, core_1.LogError)('FindSimilarAgentExamples: Example vector service not initialized. Falling back to cached examples without semantic ranking.');
+            // Vector service not available - fall back to returning examples from cache filtered by scope
+            LogError('FindSimilarAgentExamples: Example vector service not initialized. Falling back to cached examples without semantic ranking.');
             return this.fallbackGetExamplesFromCache(agentId, userId, companyId, topK);
         }
         if (!queryText || queryText.trim().length === 0) {
@@ -593,7 +831,7 @@ class AIEngine extends global_1.BaseSingleton {
         }
         const queryEmbedding = await this.EmbedTextLocal(queryText);
         if (!queryEmbedding || !queryEmbedding.result || queryEmbedding.result.vector.length === 0) {
-            (0, core_1.LogError)('FindSimilarAgentExamples: Failed to generate embedding for query text. Falling back to cached examples.');
+            LogError('FindSimilarAgentExamples: Failed to generate embedding for query text. Falling back to cached examples.');
             return this.fallbackGetExamplesFromCache(agentId, userId, companyId, topK);
         }
         const needsFiltering = agentId || userId || companyId;
@@ -612,6 +850,10 @@ class AIEngine extends global_1.BaseSingleton {
             similarity: r.score
         }));
     }
+    /**
+     * Fallback method to get examples from cache when vector service is unavailable.
+     * Returns examples filtered by scope, sorted by success score then creation date.
+     */
     fallbackGetExamplesFromCache(agentId, userId, companyId, topK = 3) {
         const examples = this.AgentExamples.filter(e => {
             if (e.Status !== 'Active')
@@ -624,6 +866,7 @@ class AIEngine extends global_1.BaseSingleton {
                 return false;
             return true;
         });
+        // Sort by success score (highest first), then by creation date (most recent first)
         const sorted = examples
             .sort((a, b) => {
             const scoreA = a.SuccessScore ?? 0;
@@ -633,11 +876,18 @@ class AIEngine extends global_1.BaseSingleton {
             return (b.__mj_CreatedAt?.getTime() || 0) - (a.__mj_CreatedAt?.getTime() || 0);
         })
             .slice(0, topK);
+        // Return with similarity of 0 to indicate no semantic ranking was applied
         return sorted.map(example => ({
             example,
             similarity: 0
         }));
     }
+    // ========================================================================
+    // Deprecated AI Action Methods
+    // ========================================================================
+    /**
+     * @deprecated Entity AI Actions are deprecated. Use AIPromptRunner with the new AI Prompt system instead.
+     */
     async ExecuteEntityAIAction(params) {
         const startTime = new Date();
         try {
@@ -664,7 +914,7 @@ class AIEngine extends global_1.BaseSingleton {
                 modelId: modelId,
                 systemPrompt: entityPrompt,
                 userMessage: userMessage,
-                apiKey: (0, ai_1.GetAIAPIKey)(model.DriverClass),
+                apiKey: GetAIAPIKey(model.DriverClass),
                 result: null
             };
             if (!await params.entityRecord.BeforeEntityAIAction(entityParams))
@@ -691,10 +941,11 @@ class AIEngine extends global_1.BaseSingleton {
                     }
                 }
                 else if (entityAction.OutputType.trim().toLowerCase() === 'entity') {
-                    const md = new core_1.Metadata();
+                    const md = new Metadata();
                     const newRecord = await md.GetEntityObject(entityAction.OutputEntity);
                     newRecord.NewRecord();
                     newRecord.Set('EntityID', params.entityRecord.EntityInfo.ID);
+                    // Use concatenated key format to properly support both single and composite primary keys
                     newRecord.Set('RecordID', params.entityRecord.PrimaryKey.ToConcatenatedString());
                     newRecord.Set(entityAction.OutputField, sOutput);
                     await newRecord.Save();
@@ -703,7 +954,7 @@ class AIEngine extends global_1.BaseSingleton {
             return results;
         }
         catch (err) {
-            (0, core_1.LogError)('AIEngine: ExecuteEntityAIAction failed', undefined, err instanceof Error ? err : undefined);
+            LogError('AIEngine: ExecuteEntityAIAction failed', undefined, err instanceof Error ? err : undefined);
             return {
                 success: false,
                 startTime: startTime,
@@ -726,6 +977,9 @@ class AIEngine extends global_1.BaseSingleton {
         }
         return temp;
     }
+    /**
+     * @deprecated AI Actions are deprecated. Use AIPromptRunner with the new AI Prompt system instead.
+     */
     async ExecuteAIAction(params) {
         const action = this.Actions.find(a => a.ID === params.actionId);
         if (!action)
@@ -737,7 +991,7 @@ class AIEngine extends global_1.BaseSingleton {
             throw new Error(`Model ${params.modelId} not found.`);
         if (model.IsActive === false)
             throw new Error(`Model ${params.modelId} is not active.`);
-        const driver = await this.getDriver(model, (0, ai_1.GetAIAPIKey)(model.DriverClass));
+        const driver = await this.getDriver(model, GetAIAPIKey(model.DriverClass));
         if (driver) {
             const modelParams = {
                 model: params.modelName,
@@ -769,6 +1023,9 @@ class AIEngine extends global_1.BaseSingleton {
         else
             throw new Error(`Driver ${model.DriverClass} not found or couldn't be loaded.`);
     }
+    /**
+     * @deprecated This method is related to deprecated AI Actions. Use AIPromptRunner instead.
+     */
     GetStringOutputFromActionResults(action, result) {
         switch (action.Name.trim().toLowerCase()) {
             case 'classify':
@@ -789,20 +1046,15 @@ class AIEngine extends global_1.BaseSingleton {
         const driverModuleName = model.DriverImportPath;
         try {
             if (driverModuleName && driverModuleName.length > 0) {
-                const driverModule = await Promise.resolve(`${driverModuleName}`).then(s => __importStar(require(s)));
+                const driverModule = await import(driverModuleName);
                 if (!driverModule)
                     throw new Error(`Error loading driver module '${driverModuleName}'`);
             }
-            return global_1.MJGlobal.Instance.ClassFactory.CreateInstance(ai_1.BaseModel, driverClassName, apiKey);
+            return MJGlobal.Instance.ClassFactory.CreateInstance(BaseModel, driverClassName, apiKey);
         }
         catch (e) {
             throw new Error(`Error loading driver '${driverModuleName}' / '${driverClassName}' : ${e.message}`);
         }
     }
 }
-exports.AIEngine = AIEngine;
-function LoadAIEngine() {
-    (0, ai_engine_base_1.LoadBaseAIEngine)();
-}
-exports.LoadAIEngine = LoadAIEngine;
 //# sourceMappingURL=AIEngine.js.map