@memberjunction/ai-engine-base

@memberjunction/ai-engine-base

Base AI Engine package for MemberJunction. Provides a comprehensive metadata cache for all AI-related entities -- models, vendors, prompts, agents, configurations, modalities, permissions, and more. This package extends BaseEngine to load and cache AI metadata in a single batch, making it available on both server and client without duplicating data loading logic.

Architecture

graph TD
    subgraph Dependencies
        CORE["@memberjunction/core<br/>BaseEngine"]
        style CORE fill:#2d6a9f,stroke:#1a4971,color:#fff

        CE["@memberjunction/core-entities"]
        style CE fill:#2d6a9f,stroke:#1a4971,color:#fff

        ACP["@memberjunction/ai-core-plus<br/>Extended Entities"]
        style ACP fill:#2d6a9f,stroke:#1a4971,color:#fff
    end

    AIB["AIEngineBase<br/>Singleton Metadata Cache"]
    style AIB fill:#2d8659,stroke:#1a5c3a,color:#fff

    subgraph "Cached Metadata"
        M["Models & Model Types"]
        style M fill:#7c5295,stroke:#563a6b,color:#fff

        V["Vendors & Model Vendors"]
        style V fill:#7c5295,stroke:#563a6b,color:#fff

        P["Prompts, Categories & Types"]
        style P fill:#7c5295,stroke:#563a6b,color:#fff

        A["Agents, Types & Relationships"]
        style A fill:#7c5295,stroke:#563a6b,color:#fff

        CFG["Configurations & Params"]
        style CFG fill:#b8762f,stroke:#8a5722,color:#fff

        MOD["Modalities & Limits"]
        style MOD fill:#b8762f,stroke:#8a5722,color:#fff

        PERM["Permissions & Credentials"]
        style PERM fill:#b8762f,stroke:#8a5722,color:#fff
    end

    CORE --> AIB
    CE --> AIB
    ACP --> AIB
    AIB --> M
    AIB --> V
    AIB --> P
    AIB --> A
    AIB --> CFG
    AIB --> MOD
    AIB --> PERM

    SRV["AIEngine (Server)"]
    style SRV fill:#2d6a9f,stroke:#1a4971,color:#fff

    AIB --> SRV

Installation

npm install @memberjunction/ai-engine-base

Key Exports

AIEngineBase (Singleton)

The core class that loads and caches all AI metadata. Access via AIEngineBase.Instance.

import { AIEngineBase } from '@memberjunction/ai-engine-base';

// Initialize (typically at app startup)
await AIEngineBase.Instance.Config(false, contextUser);

// Access cached metadata
const models = AIEngineBase.Instance.Models;
const agents = AIEngineBase.Instance.Agents;
const prompts = AIEngineBase.Instance.Prompts;

Cached Entity Collections

Property	Entity	Description
Models	AI Models	All registered AI models with extended properties
ModelTypes	AI Model Types	Model type categories (LLM, Embeddings, etc.)
Vendors	MJ: AI Vendors	AI service providers
ModelVendors	MJ: AI Model Vendors	Model-vendor associations
Prompts	AI Prompts	All prompt definitions with category associations
PromptModels	MJ: AI Prompt Models	Prompt-model associations
PromptTypes	AI Prompt Types	Prompt type categories
PromptCategories	AI Prompt Categories	Hierarchical prompt organization
Agents	AI Agents	All agent definitions with actions and notes
AgentTypes	MJ: AI Agent Types	Agent type definitions
AgentActions	AI Agent Actions	Actions associated with agents
AgentPrompts	MJ: AI Agent Prompts	Prompts associated with agents
AgentSteps	MJ: AI Agent Steps	Flow agent step definitions
AgentStepPaths	MJ: AI Agent Step Paths	Transitions between flow steps
AgentRelationships	MJ: AI Agent Relationships	Sub-agent relationships
AgentPermissions	MJ: AI Agent Permissions	User/role permission grants
AgentConfigurations	MJ: AI Agent Configurations	Semantic presets (Fast, High Quality)
Configurations	MJ: AI Configurations	Global AI configurations with inheritance
ConfigurationParams	MJ: AI Configuration Params	Key-value parameters for configurations
ModelCosts	MJ: AI Model Costs	Cost tracking per model/vendor
ModelPriceTypes	MJ: AI Model Price Types	Price type definitions
ModelPriceUnitTypes	MJ: AI Model Price Unit Types	Unit type definitions
CredentialBindings	MJ: AI Credential Bindings	Credential bindings for vendors/models
Modalities	MJ: AI Modalities	Input/output modality definitions
AgentModalities	MJ: AI Agent Modalities	Agent modality support
ModelModalities	MJ: AI Model Modalities	Model modality support
VectorDatabases	Vector Databases	Vector database configurations
ArtifactTypes	MJ: Artifact Types	Artifact type definitions
AgentPairedAgents	MJ: AI Agent Paired Agents	Realtime co-agent → target-agent pairing junction
AgentChannels	MJ: AI Agent Channels	Interactive-channel registry (plugin classes, transport)

Realtime pairing + channel registries (new): AgentPairedAgents (MJ: AI Agent Paired Agents) and AgentChannels (MJ: AI Agent Channels) are cached as unfiltered local datasets like every other small metadata table here. Pairing rows constrain which target agents a Realtime co-agent may front (Sequence ordering, at most one IsDefault per co-agent; zero rows = universal co-agent), and channel rows declare the interactive-channel surfaces (e.g. the live Whiteboard) with their server/client plugin class keys and IsActive flag. Consumers (the voice picker/session services, RealtimeChannelServerHost, and RealtimeClientSessionResolver) read these getters and filter in memory instead of issuing per-call RunViews — BaseEngine's save/delete/remote-invalidate reactivity keeps both caches fresh.

Convenience Methods

// Get the highest-power model of a given type
const bestLLM = await AIEngineBase.Instance.GetHighestPowerLLM('OpenAI', contextUser);
const bestEmbedding = await AIEngineBase.Instance.GetHighestPowerModel('OpenAI', 'Embeddings', contextUser);

// Get agent by name
const agent = AIEngineBase.Instance.GetAgentByName('Customer Support Agent');

// Get sub-agents (children + relationships)
const subAgents = AIEngineBase.Instance.GetSubAgents(agentId, 'Active');

// Configuration presets
const presets = AIEngineBase.Instance.GetAgentConfigurationPresets(agentId);
const defaultPreset = AIEngineBase.Instance.GetDefaultAgentConfigurationPreset(agentId);

Fast Lookups (O(1) indexes + memoized helpers)

The cached collections are plain arrays, but the engine also exposes lazily-built lookup indexes and memoized helpers so hot paths (model selection, credential resolution) don't re-scan them on every call. All indexes are rebuilt automatically when the metadata reloads.

const eng = AIEngineBase.Instance;

// O(1) by-ID lookups (keys are NormalizeUUID'd — case/whitespace safe)
const model  = eng.ModelsByID.get(NormalizeUUID(modelId));
const vendor = eng.VendorsByID.get(NormalizeUUID(vendorId));
const config = eng.ConfigurationsByID.get(NormalizeUUID(configId));
const type   = eng.ModelTypesByID.get(NormalizeUUID(typeId));

// Grouped indexes
const vendorsForModel = eng.ModelVendorsByModelID.get(NormalizeUUID(modelId)) ?? [];
const modelsForPrompt = eng.PromptModelsByPromptID.get(NormalizeUUID(promptId)) ?? [];

// Inference-provider check (memoized vendor-type lookup; Model-Developer fallback)
if (eng.IsInferenceProvider(modelVendor)) { /* runs the model, not just develops it */ }
const inferenceTypeId = eng.InferenceProviderTypeID; // memoized

When you already hold a model entity, prefer model.ModelVendors (the per-model vendor array the engine attaches at load) over ModelVendorsByModelID. The index exists for callers that only have a ModelID.

Configuration Inheritance

Configurations support parent-child inheritance chains:

// Get the full inheritance chain (child -> parent -> grandparent)
const chain = AIEngineBase.Instance.GetConfigurationChain(configId);

// Get parameters with inheritance (child overrides parent)
const params = AIEngineBase.Instance.GetConfigurationParamsWithInheritance(configId);

Model Cost Tracking

// Get active cost for a model/vendor combination
const cost = AIEngineBase.Instance.GetActiveModelCost(modelId, vendorId, 'Realtime');

Credential Bindings

// Get credential bindings for a vendor
const bindings = AIEngineBase.Instance.GetCredentialBindingsForTarget('Vendor', vendorId);

// Check if bindings exist
const hasBindings = AIEngineBase.Instance.HasCredentialBindings('ModelVendor', modelVendorId);

Modality System

The modality system tracks which input/output types (Text, Image, Audio, Video, File) agents and models support.

// Check if an agent supports image input
const supportsImages = AIEngineBase.Instance.AgentSupportsModality(agentId, 'Image', 'Input');

// Check if agent accepts any attachments
const supportsAttachments = AIEngineBase.Instance.AgentSupportsAttachments(agentId);

// Get aggregated attachment limits for UI configuration
const limits = AIEngineBase.Instance.GetAgentAttachmentLimits(agentId, modelId);
// limits.enabled, limits.maxAttachments, limits.maxAttachmentSizeBytes, limits.acceptedFileTypes

Agent Permission Helper

// Check individual permissions
const canView = await AIEngineBase.Instance.CanUserViewAgent(agentId, user);
const canRun = await AIEngineBase.Instance.CanUserRunAgent(agentId, user);

// Get all permissions at once
const perms = await AIEngineBase.Instance.GetUserAgentPermissions(agentId, user);
// perms.canView, perms.canRun, perms.canEdit, perms.canDelete, perms.isOwner

// Get all accessible agents for a user
const agents = await AIEngineBase.Instance.GetAccessibleAgents(user, 'run');

Additional Exports

Export	Purpose
ModalityLimits	Resolved limits for a specific modality (size, count, dimension, formats)
AgentAttachmentLimits	Aggregated attachment limits for UI components
PriceUnitTypes	Price unit type utilities
AIAgentPermissionHelper	Static helper for agent permission checks
EffectiveAgentPermissions	Complete permission set for a user/agent combination
AICredentialBindingEntityExtended	Extended credential binding entity

Skill Gating

AIEngineBase is the single source of truth for which skills an agent may use, via two methods with distinct purposes:

Method	Question it answers	Gates applied
GetSkillsForAgent(agent, user?)	May this agent+user use this skill at all? (availability)	AIAgent.AcceptsSkills (None/All/Limited) × AISkill.Status='Active' × per-grant MJ: AI Agent Skills.Status (Limited only) × user Run permission (when user supplied)
GetAutoActivatableSkillsForAgent(agent, user?)	May this agent self-activate this skill? (trigger)	Everything above plus the double activation gate: AIAgent.SkillActivationMode === 'Auto' AND AISkill.ActivationMode === 'Auto' (both default 'RequestedOnly')

Use the availability set for the user-requested path (/skill mentions → ExecuteAgentParams.requestedSkillIDs) and for pickers/tooling; use the auto set for anything the agent triggers on its own judgment (the prompt catalog, Skill-step validation). Because both ActivationMode defaults are RequestedOnly, the Auto × Auto "super agent" posture is always a deliberate double opt-in.

Bundle membership is resolved by ID via GetSkillActionIDs(skillID) / GetSkillSubAgentIDs(skillID); skill permission rows are cached on SkillPermissions and evaluated by AISkillPermissionHelper (open-by-default). Full architecture: Agent Skills & Plan Mode Guide.

Dependencies

• @memberjunction/core -- BaseEngine, Metadata, RunView
• @memberjunction/core-entities -- Generated entity classes
• @memberjunction/ai -- Core AI abstractions
• @memberjunction/ai-core-plus -- Extended entity classes
• @memberjunction/global -- Class factory
• @memberjunction/templates-base-types -- Template engine integration