@memberjunction/ai-engine-base 3.3.0 → 4.0.0

package/dist/BaseAIEngine.js

@@ -1,4 +1,3 @@
-"use strict";
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -6,16 +5,16 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var AIEngineBase_1;
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AIEngineBase = void 0;
-const core_1 = require("@memberjunction/core");
-const AIAgentPermissionHelper_1 = require("./AIAgentPermissionHelper");
-const templates_base_types_1 = require("@memberjunction/templates-base-types");
-const core_2 = require("@memberjunction/core");
-const DEFAULT_MAX_SIZE_BYTES = 20 * 1024 * 1024;
+import { BaseEngine, LogError, Metadata, RunView } from "@memberjunction/core";
+import { AIAgentPermissionHelper } from "./AIAgentPermissionHelper.js";
+import { TemplateEngineBase } from "@memberjunction/templates-base-types";
+import { RegisterForStartup } from "@memberjunction/core";
+// Default fallback values when no metadata is configured
+const DEFAULT_MAX_SIZE_BYTES = 20 * 1024 * 1024; // 20MB
 const DEFAULT_MAX_COUNT_PER_MESSAGE = 10;
 const DEFAULT_MAX_DIMENSION = 4096;
-let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine {
+// this class handles execution of AI Actions
+let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends BaseEngine {
     constructor() {
         super(...arguments);
         this._models = [];
@@ -51,6 +50,10 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
         this._modalities = [];
         this._agentModalities = [];
         this._modelModalities = [];
+        /**
+         * Cache for configuration inheritance chains.
+         * Key: configurationId, Value: array of AIConfigurationEntity from child to root
+         */
         this._configurationChainCache = new Map();
     }
     async Config(forceRefresh, contextUser, provider) {
@@ -221,11 +224,16 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
                 CacheLocal: true
             }
         ];
-        await templates_base_types_1.TemplateEngineBase.Instance.Config(false, contextUser);
+        // make sure template engine base is loaded up
+        await TemplateEngineBase.Instance.Config(false, contextUser);
         return await this.Load(params, provider, forceRefresh, contextUser);
     }
     async AdditionalLoading(contextUser) {
+        // Clear the configuration chain cache when data is reloaded
         this._configurationChainCache.clear();
+        // handle associating prompts with prompt categories
+        //here we're using the underlying data (i.e _promptCategories and _prompts)
+        //rather than the getter methods because the engine's Loaded property is still false
         for (const PromptCategory of this._promptCategories) {
             this._prompts.filter((prompt) => {
                 return prompt.CategoryID === PromptCategory.ID;
@@ -233,6 +241,7 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
                 PromptCategory.Prompts.push(prompt);
             });
         }
+        // handle association agent actions, models, and notes with agents
         for (const agent of this._agents) {
             this._agentActions.filter((action) => {
                 return action.AgentID === agent.ID;
@@ -252,10 +261,18 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
             });
         }
     }
+    /**
+     * Convenience method to returns the highest power model for a given vendor and model type. Loads the metadata if not already loaded.
+     * @param vendorName - if set to null, undefined, or an empty string, then all models of the specified type are considered
+     * @param modelType - the type of model to consider
+     * @param contextUser required on the server side
+     * @returns
+     */
     async GetHighestPowerModel(vendorName, modelType, contextUser) {
         try {
-            await AIEngineBase_1.Instance.Config(false, contextUser);
+            await AIEngineBase_1.Instance.Config(false, contextUser); // most of the time this is already loaded, but just in case it isn't we will load it here
             const models = AIEngineBase_1.Instance.Models.filter(m => {
+                // Guard against AIModelType/Vendor being non-string (defensive coding for data issues)
                 const mModelType = typeof m.AIModelType === 'string' ? m.AIModelType.trim().toLowerCase() : '';
                 const mVendor = typeof m.Vendor === 'string' ? m.Vendor.trim().toLowerCase() : '';
                 const targetType = modelType.trim().toLowerCase();
@@ -263,17 +280,31 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
                 return mModelType === targetType &&
                     (targetVendor === '' || mVendor === targetVendor);
             });
-            models.sort((a, b) => b.PowerRank - a.PowerRank);
+            // next, sort the models by the PowerRank field so that the highest power rank model is the first array element
+            models.sort((a, b) => b.PowerRank - a.PowerRank); // highest power rank first
             return models[0];
         }
         catch (e) {
-            (0, core_1.LogError)(e);
+            LogError(e); // force logging to help debug scenario here
             throw e;
         }
     }
+    /**
+     * Convenience method to return the highest power LLM model for a given vendor. Loads the metadata if not already loaded.
+     * @param vendorName - if provided, filters to only consider models from the specified vendor, otherwise considers all models
+     * @param contextUser
+     * @returns
+     */
     async GetHighestPowerLLM(vendorName, contextUser) {
         return await this.GetHighestPowerModel(vendorName, 'LLM', contextUser);
     }
+    /**
+     * Gets the active cost configuration for a specific model and vendor combination
+     * @param modelID - The ID of the AI model
+     * @param vendorID - The ID of the vendor
+     * @param processingType - 'Realtime' or 'Batch' (defaults to 'Realtime')
+     * @returns The active AIModelCostEntity or null if none found
+     */
     GetActiveModelCost(modelID, vendorID, processingType = 'Realtime') {
         const now = new Date();
         const activeCosts = this._modelCosts.filter(cost => cost.ModelID === modelID &&
@@ -282,6 +313,7 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
             cost.Status === 'Active' &&
             (!cost.StartedAt || new Date(cost.StartedAt) <= now) &&
             (!cost.EndedAt || new Date(cost.EndedAt) > now));
+        // If multiple active costs exist, return the most recently started one
         if (activeCosts.length > 0) {
             return activeCosts.sort((a, b) => {
                 const aStart = a.StartedAt ? new Date(a.StartedAt).getTime() : 0;
@@ -297,15 +329,29 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
     get AgentRelationships() {
         return this._agentRelationships;
     }
+    /**
+     * Returns the sub-agents for a given agent ID, optionally filtering by status.
+     * Includes both child agents (ParentID relationship) and related agents (AgentRelationships).
+     *
+     * @param agentID - The ID of the parent agent to get sub-agents for
+     * @param status - Optional status to filter sub-agents by (e.g., 'Active', 'Inactive'). If not provided, all sub-agents are returned.
+     * @param relationshipStatus - Optional status to filter agent relationships by. Defaults to 'Active' if not provided.
+     * @returns AIAgentEntityExtended[] - Array of sub-agent entities matching the criteria (deduplicated by ID).
+     * @memberof
+     */
     GetSubAgents(agentID, status, relationshipStatus) {
+        // Get child agents (ParentID relationship)
         const childAgents = this._agents.filter(a => a.ParentID === agentID &&
             (!status || a.Status === status));
-        const relStatus = relationshipStatus ?? 'Active';
+        // Get related agents (AgentRelationships)
+        const relStatus = relationshipStatus ?? 'Active'; // Default to Active for relationships
         const activeRelationships = this._agentRelationships.filter(ar => ar.AgentID === agentID &&
             ar.Status === relStatus);
+        // Get the actual agent entities for related agents
         const relatedAgents = activeRelationships
             .map(ar => this._agents.find(a => a.ID === ar.SubAgentID))
             .filter(a => a != null && (!status || a.Status === status));
+        // Combine and deduplicate by ID
         const uniqueAgentIDs = new Set();
         const allSubAgents = [];
         for (const agent of [...childAgents, ...relatedAgents]) {
@@ -328,9 +374,19 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
     get AgentPrompts() {
         return this._agentPrompts;
     }
+    /**
+     * Cached array of AI Agent Configurations loaded from the database.
+     * These define semantic presets for agents (e.g., "Fast", "High Quality").
+     */
     get AgentConfigurations() {
         return this._agentConfigurations;
     }
+    /**
+     * Gets all configuration presets for a specific agent
+     * @param agentId The agent ID
+     * @param activeOnly If true, only returns Active status presets (default: true)
+     * @returns Array of configuration presets sorted by Priority
+     */
     GetAgentConfigurationPresets(agentId, activeOnly = true) {
         let presets = this._agentConfigurations.filter(ac => ac.AgentID === agentId);
         if (activeOnly) {
@@ -338,10 +394,21 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
         }
         return presets.sort((a, b) => a.Priority - b.Priority);
     }
+    /**
+     * Gets the default configuration preset for an agent
+     * @param agentId The agent ID
+     * @returns The default preset, or undefined if none exists
+     */
     GetDefaultAgentConfigurationPreset(agentId) {
         const presets = this.GetAgentConfigurationPresets(agentId, true);
         return presets.find(ac => ac.IsDefault);
     }
+    /**
+     * Gets a specific configuration preset by agent ID and preset name
+     * @param agentId The agent ID
+     * @param presetName The preset name (e.g., "Fast", "HighQuality")
+     * @returns The configuration preset, or undefined if not found
+     */
     GetAgentConfigurationPresetByName(agentId, presetName) {
         return this._agentConfigurations.find(ac => ac.AgentID === agentId &&
             ac.Name === presetName &&
@@ -374,6 +441,13 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
     get CredentialBindings() {
         return this._credentialBindings;
     }
+    /**
+     * Gets credential bindings for a specific target, filtered by binding type and sorted by priority.
+     * Only returns active bindings.
+     * @param bindingType - The type of binding: 'Vendor', 'ModelVendor', or 'PromptModel'
+     * @param targetId - The ID of the target entity (AIVendorID, AIModelVendorID, or AIPromptModelID)
+     * @returns Array of active credential bindings sorted by Priority (lower = higher priority)
+     */
     GetCredentialBindingsForTarget(bindingType, targetId) {
         return this._credentialBindings
             .filter(b => {
@@ -394,6 +468,12 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
         })
             .sort((a, b) => a.Priority - b.Priority);
     }
+    /**
+     * Checks if any credential bindings exist for a specific target.
+     * @param bindingType - The type of binding: 'Vendor', 'ModelVendor', or 'PromptModel'
+     * @param targetId - The ID of the target entity
+     * @returns True if at least one active binding exists
+     */
     HasCredentialBindings(bindingType, targetId) {
         return this.GetCredentialBindingsForTarget(bindingType, targetId).length > 0;
     }
@@ -418,6 +498,9 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
     get ArtifactTypes() {
         return this._artifactTypes;
     }
+    /**
+     * Convenience method to return only the Language Models. Loads the metadata if not already loaded.
+     */
     get LanguageModels() {
         return this._models.filter(m => m.AIModelType.trim().toLowerCase() === 'llm');
     }
@@ -439,14 +522,60 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
     get ConfigurationParams() {
         return this._configurationParams;
     }
+    /**
+     * Gets configuration parameters for a specific configuration
+     * @param configurationId - The ID of the configuration
+     * @returns Array of configuration parameters for the specified configuration
+     */
     GetConfigurationParams(configurationId) {
         return this._configurationParams.filter(p => p.ConfigurationID === configurationId);
     }
+    /**
+     * Gets a specific configuration parameter value
+     * @param configurationId - The ID of the configuration
+     * @param paramName - The name of the parameter
+     * @returns The parameter entity or null if not found
+     */
     GetConfigurationParam(configurationId, paramName) {
         return this._configurationParams.find(p => p.ConfigurationID === configurationId &&
             p.Name.toLowerCase() === paramName.toLowerCase()) || null;
     }
+    /**
+     * Returns the inheritance chain for a configuration, starting with the specified
+     * configuration and walking up through parent configurations to the root.
+     *
+     * The chain is ordered from most-specific (the requested configuration) to
+     * least-specific (the root parent with no ParentID).
+     *
+     * Results are cached for performance. Cache is invalidated when configurations
+     * are reloaded via Config().
+     *
+     * @param configurationId - The ID of the configuration to get the chain for
+     * @returns Array of AIConfigurationEntity objects representing the inheritance chain,
+     *          or empty array if the configuration is not found
+     * @throws Error if a circular reference is detected in the configuration hierarchy
+     *
+     * @example
+     * // Single configuration with no parent
+     * const chain = AIEngine.Instance.GetConfigurationChain('config-a');
+     * // Returns: [ConfigA]
+     *
+     * @example
+     * // Child -> Parent -> Grandparent chain
+     * const chain = AIEngine.Instance.GetConfigurationChain('child-config');
+     * // Returns: [ChildConfig, ParentConfig, GrandparentConfig]
+     *
+     * @example
+     * // Usage in model selection - first config in chain with a match wins
+     * const chain = AIEngine.Instance.GetConfigurationChain(configId);
+     * for (const config of chain) {
+     *   const models = promptModels.filter(pm => pm.ConfigurationID === config.ID);
+     *   if (models.length > 0) return models;
+     * }
+     * // Fall back to null-config models if no match in chain
+     */
     GetConfigurationChain(configurationId) {
+        // Check cache first
         if (this._configurationChainCache.has(configurationId)) {
             return this._configurationChainCache.get(configurationId);
         }
@@ -454,6 +583,7 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
         const visitedIds = new Set();
         let currentId = configurationId;
         while (currentId) {
+            // Cycle detection
             if (visitedIds.has(currentId)) {
                 const chainNames = chain.map(c => c.Name).join(' -> ');
                 throw new Error(`Circular reference detected in AI Configuration hierarchy. ` +
@@ -465,16 +595,37 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
                 break;
             visitedIds.add(currentId);
             chain.push(config);
-            currentId = config.ParentID;
+            currentId = config.ParentID; // Will be null for root configs
         }
+        // Cache the result
         this._configurationChainCache.set(configurationId, chain);
         return chain;
     }
+    /**
+     * Returns all configuration parameters for a configuration, including inherited
+     * parameters from parent configurations. Child parameters override parent parameters
+     * with the same name (case-insensitive match).
+     *
+     * The inheritance chain is walked from root to child, so child values take precedence
+     * over parent values for parameters with the same name.
+     *
+     * @param configurationId - The ID of the configuration to get parameters for
+     * @returns Array of AIConfigurationParamEntity objects, with child overrides applied.
+     *          Returns empty array if configuration is not found.
+     *
+     * @example
+     * // Parent has: temperature=0.7, maxTokens=4000
+     * // Child has: temperature=0.9
+     * // Result: temperature=0.9 (child), maxTokens=4000 (inherited from parent)
+     * const params = AIEngine.Instance.GetConfigurationParamsWithInheritance('child-config-id');
+     */
     GetConfigurationParamsWithInheritance(configurationId) {
         const chain = this.GetConfigurationChain(configurationId);
         if (chain.length === 0) {
             return [];
         }
+        // Use a map to track params by name (lowercase for case-insensitive matching)
+        // Walk chain in reverse (root first, child last) so child overwrites parent
         const paramMap = new Map();
         for (let i = chain.length - 1; i >= 0; i--) {
             const configParams = this._configurationParams.filter(p => p.ConfigurationID === chain[i].ID);
@@ -493,58 +644,133 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
     get AgentStepPaths() {
         return this._agentStepPaths;
     }
+    // ==========================================
+    // Modality Accessors and Helper Methods
+    // ==========================================
+    /**
+     * Gets all AI modalities (Text, Image, Audio, Video, File, Embedding, etc.)
+     */
     get Modalities() {
         return this._modalities;
     }
+    /**
+     * Gets all agent-modality mappings
+     */
     get AgentModalities() {
         return this._agentModalities;
     }
+    /**
+     * Gets all model-modality mappings
+     */
     get ModelModalities() {
         return this._modelModalities;
     }
+    /**
+     * Gets a modality by name (case-insensitive)
+     * @param name - The modality name (e.g., 'Text', 'Image', 'Audio', 'Video', 'File')
+     * @returns The modality entity or undefined if not found
+     */
     GetModalityByName(name) {
         return this._modalities.find(m => m.Name.toLowerCase() === name.toLowerCase());
     }
+    /**
+     * Gets all modalities supported by an agent for a given direction
+     * @param agentId - The agent ID
+     * @param direction - 'Input' or 'Output'
+     * @returns Array of modality entities the agent supports
+     */
     GetAgentModalities(agentId, direction) {
         const agentModalityRecords = this._agentModalities.filter(am => am.AgentID === agentId && am.Direction === direction);
         return agentModalityRecords
             .map(am => this._modalities.find(m => m.ID === am.ModalityID))
             .filter((m) => m !== undefined);
     }
+    /**
+     * Gets all modalities supported by a model for a given direction
+     * @param modelId - The model ID
+     * @param direction - 'Input' or 'Output'
+     * @returns Array of modality entities the model supports
+     */
     GetModelModalities(modelId, direction) {
         const modelModalityRecords = this._modelModalities.filter(mm => mm.ModelID === modelId && mm.Direction === direction);
         return modelModalityRecords
             .map(mm => this._modalities.find(m => m.ID === mm.ModalityID))
             .filter((m) => m !== undefined);
     }
+    /**
+     * Checks if an agent supports a specific modality for a given direction.
+     * If no agent modalities are configured, defaults to text-only.
+     * @param agentId - The agent ID
+     * @param modalityName - The modality name (e.g., 'Image', 'Audio')
+     * @param direction - 'Input' or 'Output'
+     * @returns True if the agent supports this modality
+     */
     AgentSupportsModality(agentId, modalityName, direction) {
+        // Check if agent has explicit modality records
         const agentModalities = this.GetAgentModalities(agentId, direction);
         if (agentModalities.length > 0) {
+            // Agent has explicit modality configuration - check it
             return agentModalities.some(m => m.Name.toLowerCase() === modalityName.toLowerCase());
         }
+        // No explicit agent modalities configured - default to text-only
         return modalityName.toLowerCase() === 'text';
     }
+    /**
+     * Checks if a model supports a specific modality for a given direction
+     * @param modelId - The model ID
+     * @param modalityName - The modality name (e.g., 'Image', 'Audio')
+     * @param direction - 'Input' or 'Output'
+     * @returns True if the model supports this modality
+     */
     ModelSupportsModality(modelId, modalityName, direction) {
         const modelModalities = this.GetModelModalities(modelId, direction);
         if (modelModalities.length > 0) {
             return modelModalities.some(m => m.Name.toLowerCase() === modalityName.toLowerCase());
         }
+        // No explicit model modalities - assume text-only (default for LLMs)
         return modalityName.toLowerCase() === 'text';
     }
+    /**
+     * Checks if an agent supports any non-text input modalities (images, audio, video, files).
+     * This is used to determine if attachment upload should be enabled in the UI.
+     * @param agentId - The agent ID
+     * @returns True if the agent supports at least one non-text input modality
+     */
     AgentSupportsAttachments(agentId) {
         const nonTextModalities = ['image', 'audio', 'video', 'file'];
         return nonTextModalities.some(modalityName => this.AgentSupportsModality(agentId, modalityName, 'Input'));
     }
+    /**
+     * Gets all input modality names supported by an agent (for UI display/filtering)
+     * @param agentId - The agent ID
+     * @returns Array of modality names the agent accepts as input
+     */
     GetAgentSupportedInputModalities(agentId) {
+        // Check explicit agent modalities
         const agentModalities = this.GetAgentModalities(agentId, 'Input');
         if (agentModalities.length > 0) {
             return agentModalities.map(m => m.Name);
         }
+        // No explicit modalities configured - default to text-only
         return ['Text'];
     }
+    // ==========================================
+    // Modality Limit Resolution Methods
+    // ==========================================
+    /**
+     * Resolves the effective limits for a specific modality for an agent.
+     * Uses precedence chain: Agent → Model → System → Defaults.
+     *
+     * @param agentId - The ID of the agent
+     * @param modalityName - The modality name (e.g., 'Image', 'Audio', 'Video', 'File')
+     * @param modelId - Optional model ID to check model-specific limits (falls back to system defaults if not provided)
+     * @returns The resolved modality limits with source information
+     */
     GetAgentModalityLimits(agentId, modalityName, modelId) {
+        // Get the base modality record
         const modality = this.GetModalityByName(modalityName);
         if (!modality) {
+            // Modality doesn't exist - return defaults indicating not allowed
             return {
                 maxSizeBytes: null,
                 maxCountPerMessage: null,
@@ -554,33 +780,46 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
                 source: 'Default'
             };
         }
+        // Check agent-specific modality settings first (highest priority)
         const agentModality = this._agentModalities.find(am => am.AgentID === agentId && am.ModalityID === modality.ID && am.Direction === 'Input');
         if (agentModality) {
+            // Agent has explicit modality configuration
             return {
                 maxSizeBytes: agentModality.MaxSizeBytes,
                 maxCountPerMessage: agentModality.MaxCountPerMessage,
-                maxDimension: null,
-                supportedFormats: null,
+                maxDimension: null, // Agent modality doesn't have MaxDimension
+                supportedFormats: null, // Agent modality doesn't have SupportedFormats
                 isAllowed: agentModality.IsAllowed,
                 source: 'Agent'
             };
         }
+        // Check model-specific modality settings (second priority)
         if (modelId) {
             const modelLimits = this.GetModelModalityLimits(modelId, modalityName);
             if (modelLimits.source === 'Model') {
                 return modelLimits;
             }
         }
+        // Fall back to system-wide modality defaults
         return {
             maxSizeBytes: modality.DefaultMaxSizeBytes,
             maxCountPerMessage: modality.DefaultMaxCountPerMessage,
-            maxDimension: null,
-            supportedFormats: null,
-            isAllowed: true,
+            maxDimension: null, // System modality doesn't have MaxDimension
+            supportedFormats: null, // System modality doesn't have SupportedFormats by default
+            isAllowed: true, // If modality exists at system level, it's generally allowed
             source: 'System'
         };
     }
+    /**
+     * Resolves the effective limits for a specific modality for a model.
+     * Uses precedence chain: Model → System → Defaults.
+     *
+     * @param modelId - The ID of the model
+     * @param modalityName - The modality name (e.g., 'Image', 'Audio', 'Video', 'File')
+     * @returns The resolved modality limits with source information
+     */
     GetModelModalityLimits(modelId, modalityName) {
+        // Get the base modality record
         const modality = this.GetModalityByName(modalityName);
         if (!modality) {
             return {
@@ -592,6 +831,7 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
                 source: 'Default'
             };
         }
+        // Check model-specific modality settings
         const modelModality = this._modelModalities.find(mm => mm.ModelID === modelId && mm.ModalityID === modality.ID && mm.Direction === 'Input');
         if (modelModality && modelModality.IsSupported) {
             return {
@@ -603,6 +843,7 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
                 source: 'Model'
             };
         }
+        // Fall back to system-wide modality defaults
         return {
             maxSizeBytes: modality.DefaultMaxSizeBytes,
             maxCountPerMessage: modality.DefaultMaxCountPerMessage,
@@ -612,6 +853,15 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
             source: 'System'
         };
     }
+    /**
+     * Gets aggregated attachment limits for an agent, suitable for passing to UI components.
+     * Combines limits from all supported input modalities (Image, Audio, Video, File).
+     * Uses the most restrictive limits across all modalities for the aggregate values.
+     *
+     * @param agentId - The ID of the agent
+     * @param modelId - Optional model ID to include model-specific limits in the resolution
+     * @returns Aggregated attachment limits ready for UI component configuration
+     */
     GetAgentAttachmentLimits(agentId, modelId) {
         const attachmentModalityNames = ['Image', 'Audio', 'Video', 'File'];
         const modalityLimitsMap = new Map();
@@ -624,12 +874,15 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
             modalityLimitsMap.set(modalityName, limits);
             if (limits.isAllowed) {
                 hasAnyAllowed = true;
+                // Track the most restrictive size limit
                 if (limits.maxSizeBytes != null && limits.maxSizeBytes < minMaxSize) {
                     minMaxSize = limits.maxSizeBytes;
                 }
+                // Track the most restrictive count limit
                 if (limits.maxCountPerMessage != null && limits.maxCountPerMessage < minMaxCount) {
                     minMaxCount = limits.maxCountPerMessage;
                 }
+                // Build accepted file types based on allowed modalities
                 const mimePattern = this.getModalityMimePattern(modalityName, limits.supportedFormats);
                 if (mimePattern) {
                     acceptedTypes.push(mimePattern);
@@ -644,10 +897,15 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
             modalities: modalityLimitsMap
         };
     }
+    /**
+     * Helper to get MIME type pattern for a modality
+     */
     getModalityMimePattern(modalityName, supportedFormats) {
+        // If specific formats are provided, use them
         if (supportedFormats) {
             return supportedFormats;
         }
+        // Default MIME patterns by modality
         switch (modalityName.toLowerCase()) {
             case 'image':
                 return 'image/*';
@@ -656,27 +914,52 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
             case 'video':
                 return 'video/*';
             case 'file':
-                return '*/*';
+                return '*/*'; // Accept all file types
             default:
                 return null;
         }
     }
+    /**
+     * Gets agent steps for a specific agent, optionally filtered by status
+     * @param agentId - The ID of the agent
+     * @param status - Optional status filter ('Active', 'Pending', 'Disabled')
+     * @returns Array of agent steps
+     */
     GetAgentSteps(agentId, status) {
         return this._agentSteps.filter(step => step.AgentID === agentId &&
             (!status || step.Status === status));
     }
+    /**
+     * Gets a specific agent step by ID
+     * @param stepId - The ID of the step
+     * @returns The step or null if not found
+     */
     GetAgentStepByID(stepId) {
         return this._agentSteps.find(step => step.ID === stepId) || null;
     }
+    /**
+     * Gets paths originating from a specific step
+     * @param stepId - The ID of the origin step
+     * @returns Array of paths from the step
+     */
     GetPathsFromStep(stepId) {
         return this._agentStepPaths.filter(path => path.OriginStepID === stepId);
     }
+    /**
+     * @deprecated AI Model Actions are deprecated. Returns an empty array.
+     */
     get ModelActions() {
         return [];
     }
+    /**
+     * @deprecated AI Actions are deprecated. Returns an empty array.
+     */
     get Actions() {
         return [];
     }
+    /**
+     * @deprecated Entity AI Actions are deprecated. Returns an empty array.
+     */
     get EntityAIActions() {
         return [];
     }
@@ -687,15 +970,19 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
         if (!AIEngineBase_1.Instance.Loaded)
             throw new Error("AI Metadata not loaded, call AIEngineBase.Config() first.");
     }
+    /**
+     * This method will check the result cache for the given params and return the result if it exists, otherwise it will return null if the request is not cached.
+     * @param prompt - the fully populated prompt to check the cache for
+     */
     async CheckResultCache(prompt) {
         try {
-            const rv = new core_1.RunView();
+            const rv = new RunView();
             const escapedPrompt = prompt.replace(/'/g, "''");
             const result = await rv.RunView({
                 EntityName: 'AI Result Cache',
                 ExtraFilter: `PromptText = '${escapedPrompt}' AND Status='Active'`,
                 OrderBy: 'RunAt DESC',
-                MaxRows: 1,
+                MaxRows: 1, // get only the latest one
                 ResultType: 'entity_object'
             }, this.ContextUser);
             if (result && result.Success && result.Results && result.Results.length > 0) {
@@ -705,12 +992,15 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
                 return null;
         }
         catch (err) {
-            (0, core_1.LogError)(err);
+            LogError(err);
             return null;
         }
     }
+    /**
+     * Utility method that will cache the result of a prompt in the AI Result Cache entity
+     */
     async CacheResult(model, prompt, promptText, resultText) {
-        const md = new core_1.Metadata();
+        const md = new Metadata();
         const cacheItem = await md.GetEntityObject('AI Result Cache', this.ContextUser);
         cacheItem.AIModelID = model.ID;
         cacheItem.AIPromptID = prompt.ID;
@@ -720,33 +1010,80 @@ let AIEngineBase = AIEngineBase_1 = class AIEngineBase extends core_1.BaseEngine
         cacheItem.RunAt = new Date();
         return await cacheItem.Save();
     }
+    // ==========================================
+    // AI Agent Permission Helper Methods
+    // ==========================================
+    /**
+     * Checks if a user has permission to view an agent.
+     * @param agentId - The ID of the agent to check
+     * @param user - The user to check permissions for
+     * @returns True if the user can view the agent
+     */
     async CanUserViewAgent(agentId, user) {
-        return await AIAgentPermissionHelper_1.AIAgentPermissionHelper.HasPermission(agentId, user, 'view');
-    }
+        return await AIAgentPermissionHelper.HasPermission(agentId, user, 'view');
+    }
+    /**
+     * Checks if a user has permission to run an agent.
+     * @param agentId - The ID of the agent to check
+     * @param user - The user to check permissions for
+     * @returns True if the user can run the agent
+     */
     async CanUserRunAgent(agentId, user) {
-        return await AIAgentPermissionHelper_1.AIAgentPermissionHelper.HasPermission(agentId, user, 'run');
-    }
+        return await AIAgentPermissionHelper.HasPermission(agentId, user, 'run');
+    }
+    /**
+     * Checks if a user has permission to edit an agent.
+     * @param agentId - The ID of the agent to check
+     * @param user - The user to check permissions for
+     * @returns True if the user can edit the agent
+     */
     async CanUserEditAgent(agentId, user) {
-        return await AIAgentPermissionHelper_1.AIAgentPermissionHelper.HasPermission(agentId, user, 'edit');
-    }
+        return await AIAgentPermissionHelper.HasPermission(agentId, user, 'edit');
+    }
+    /**
+     * Checks if a user has permission to delete an agent.
+     * @param agentId - The ID of the agent to check
+     * @param user - The user to check permissions for
+     * @returns True if the user can delete the agent
+     */
     async CanUserDeleteAgent(agentId, user) {
-        return await AIAgentPermissionHelper_1.AIAgentPermissionHelper.HasPermission(agentId, user, 'delete');
-    }
+        return await AIAgentPermissionHelper.HasPermission(agentId, user, 'delete');
+    }
+    /**
+     * Gets all effective permissions a user has for a specific agent.
+     * @param agentId - The ID of the agent
+     * @param user - The user to check permissions for
+     * @returns Object containing all permission flags and ownership status
+     */
     async GetUserAgentPermissions(agentId, user) {
-        return await AIAgentPermissionHelper_1.AIAgentPermissionHelper.GetEffectivePermissions(agentId, user);
-    }
+        return await AIAgentPermissionHelper.GetEffectivePermissions(agentId, user);
+    }
+    /**
+     * Gets all agents a user has access to with a specific permission level.
+     * @param user - The user to check permissions for
+     * @param permission - The minimum permission level required ('view', 'run', 'edit', or 'delete')
+     * @returns Array of agents the user can access
+     */
     async GetAccessibleAgents(user, permission) {
-        return await AIAgentPermissionHelper_1.AIAgentPermissionHelper.GetAccessibleAgents(user, permission);
+        return await AIAgentPermissionHelper.GetAccessibleAgents(user, permission);
     }
+    /**
+     * Clears the agent permissions cache. Call this after modifying permissions.
+     */
     ClearAgentPermissionsCache() {
-        AIAgentPermissionHelper_1.AIAgentPermissionHelper.ClearCache();
+        AIAgentPermissionHelper.ClearCache();
     }
+    /**
+     * Refreshes the permissions cache for a specific agent.
+     * @param agentId - The ID of the agent to refresh
+     * @param user - The user context for server-side operations
+     */
     async RefreshAgentPermissionsCache(agentId, user) {
-        await AIAgentPermissionHelper_1.AIAgentPermissionHelper.RefreshCache(user);
+        await AIAgentPermissionHelper.RefreshCache(user);
     }
 };
-exports.AIEngineBase = AIEngineBase;
-exports.AIEngineBase = AIEngineBase = AIEngineBase_1 = __decorate([
-    (0, core_2.RegisterForStartup)()
+AIEngineBase = AIEngineBase_1 = __decorate([
+    RegisterForStartup()
 ], AIEngineBase);
+export { AIEngineBase };
 //# sourceMappingURL=BaseAIEngine.js.map