@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
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
Extended Entities"]
        style ACP fill:#2d6a9f,stroke:#1a4971,color:#fff
    end

    AIB["AIEngineBase
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
Copy

Installation

npm install @memberjunction/ai-engine-base
Copy

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;
Copy

Cached Entity Collections

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);
Copy

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
Copy

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);
Copy

Model Cost Tracking

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

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);
Copy

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
Copy

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');
Copy

Additional Exports

Skill Gating

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

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