@memberjunction/ai-core-plus

Shared type definitions and extended entity classes for the MemberJunction AI Framework. This package bridges the gap between the standalone @memberjunction/ai core and the full MJ entity system, providing types that are usable on both server and client. It defines prompt execution result types, agent execution types, system placeholder management, conversation utilities, and extended entity classes with additional computed properties.

Architecture

graph TD
    AI["@memberjunction/ai"]
    style AI fill:#2d6a9f,stroke:#1a4971,color:#fff

    CORE["@memberjunction/core"]
    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"]
    style ACP fill:#2d8659,stroke:#1a5c3a,color:#fff

    subgraph "ai-core-plus Modules"
        PT["Prompt Types<br/>AIPromptParams, AIPromptRunResult"]
        style PT fill:#7c5295,stroke:#563a6b,color:#fff

        AT["Agent Types<br/>ExecuteAgentParams, ExecuteAgentResult"]
        style AT fill:#7c5295,stroke:#563a6b,color:#fff

        SP["System Placeholders<br/>Date/Time, User Context"]
        style SP fill:#b8762f,stroke:#8a5722,color:#fff

        EXT["Extended Entities<br/>AIPrompt, AIModel, AIAgent"]
        style EXT fill:#2d6a9f,stroke:#1a4971,color:#fff

        CU["ConversationUtility"]
        style CU fill:#b8762f,stroke:#8a5722,color:#fff

        RF["Response Forms<br/>& UI Commands"]
        style RF fill:#7c5295,stroke:#563a6b,color:#fff
    end

    AI --> ACP
    CORE --> ACP
    CE --> ACP
    ACP --> PT
    ACP --> AT
    ACP --> SP
    ACP --> EXT
    ACP --> CU
    ACP --> RF

Installation

npm install @memberjunction/ai-core-plus

Key Exports

Prompt Types (prompt.types.ts)

Type / Class	Purpose
AIPromptParams	Full parameter set for prompt execution: prompt reference, data context, configuration, child prompts, streaming callbacks, cancellation, credential overrides, effort level, and more
AIPromptRunResult<T>	Generic result from prompt execution including raw/parsed output, token usage, cost, validation attempts, model selection info, and media references
ChildPromptParam	Links a child prompt to a placeholder in a parent template for hierarchical composition
AIModelSelectionInfo	Debugging info about which models were considered and why one was selected
ExecutionProgressCallback	Callback for real-time execution progress (template rendering, model selection, execution, validation)
ExecutionStreamingCallback	Callback for streaming content chunks during execution
ValidationAttempt	Detailed record of each validation attempt with attempt number, errors, and raw/parsed output
PromptRunMediaReference	Reference to generated media (image, audio, video) with metadata
ExecutionStatus	Status enum: 'Pending', 'Running', 'Completed', 'Failed', 'Cancelled'

Agent Types (agent-types.ts)

Type / Class	Purpose
ExecuteAgentParams	Parameters for agent execution: agent reference, messages, conversation context, user scope, configuration presets, effort level, action changes, and callbacks
ExecuteAgentResult	Agent execution result with success status, output messages, actions performed, sub-agent requests, and model selection info
AgentContextData	Contextual data injected into agent prompts (notes, examples, data sources)
AgentConfiguration	Runtime configuration for an agent run (model overrides, effort level, max iterations)
UserScope	Multi-tenant scoping for agent memory with primary/secondary dimensions
AgentAction	Description of an action an agent wants to execute
AgentSubAgentRequest	Request from one agent to delegate work to a sub-agent
AgentChatMessage / AgentChatMessageMetadata	Chat messages with lifecycle metadata (expiration, compaction)
MediaOutput	Media generated by an agent (modality, MIME type, data)
ActionChange / ActionChangeScope	Runtime action customization for multi-tenant scenarios

Consolidation Observability in ExecuteAgentResult

ExecuteAgentResult surfaces the agent run’s step list. As of v5.30.x, MemoryManagerAgent runs emit two new step types when its consolidation pipeline executes:

Step name	Cardinality	Notable payload fields
Process Consolidation Cluster	One per cluster identified	clusterSize, noteIds, shouldConsolidate, consolidatedNoteId, sourceNotesArchived, verificationPassed, entitiesChecked, entitiesMissing
Verify Consolidation Output	One per maintenance run	Phase-level summary of post-consolidation entity coverage check

Run-level payload additions include scoreDistribution, entityTriplesExtracted, decayScoreDistribution, protectedPreserved, ephemeralAccelerated, and triggerType ('forced' / 'time' / 'event' / 'count'). These flow through unchanged via ExecuteAgentResult.steps[*].outputData — consumers that already deserialize step output data will pick them up without code changes.

For pipeline mechanics, see @memberjunction/ai-agents.

System Placeholders (prompt.system-placeholders.ts)

The SystemPlaceholderManager automatically injects common values into all prompt templates:

• {{CurrentDate}}, {{CurrentTime}}, {{CurrentDateTime}} — Current date/time in user’s timezone
• {{CurrentTimezone}} — User’s timezone identifier
• {{UserName}}, {{UserEmail}}, {{UserFirstName}}, {{UserLastName}} — User context
• Custom placeholders can be registered at runtime

Extended Entity Classes

Class	Extends	Additional Properties
AIPromptEntityExtended	AIPromptEntity	Prompt category associations, template relationships
AIPromptCategoryEntityExtended	AIPromptCategoryEntity	Prompts array of child prompts
AIModelEntityExtended	AIModelEntity	ModelVendors array, vendor association helpers
AIAgentEntityExtended	AIAgentEntity	Actions, Notes arrays, agent relationships
AIAgentRunEntityExtended	AIAgentRunEntity	Extended run tracking
AIAgentRunStepEntityExtended	AIAgentRunStepEntity	Extended step tracking
AIPromptRunEntityExtended	AIPromptRunEntity	Extended prompt run tracking

Other Exports

Export	Purpose
ConversationUtility	Helper for creating, loading, and managing conversation records
AgentResponseForm	Structured response format definitions for agent outputs
ActionableCommand / AutomaticCommand	UI command types for agent-driven interfaces
AgentPayloadChangeRequest	Request to modify agent payload data during execution
ForEachOperation / WhileOperation	Loop operation definitions for flow-based agents

Usage

Prompt Execution Parameters

import { AIPromptParams, ChildPromptParam } from '@memberjunction/ai-core-plus';

const params = new AIPromptParams();
params.prompt = myPromptEntity;
params.data = { customerName: 'Acme Corp', orderCount: 42 };
params.contextUser = currentUser;
params.effortLevel = 75;

// Hierarchical prompt composition
params.childPrompts = [
    new ChildPromptParam(analysisParams, 'analysis'),
    new ChildPromptParam(summaryParams, 'summary')
];

// Model override at runtime
params.override = {
    modelId: 'specific-model-id',
    vendorId: 'specific-vendor-id'
};

// Force the runner to credential-check EVERY candidate model-vendor combination
// instead of short-circuiting at the first usable one. Default false — only enable
// for diagnostics that need a complete per-candidate availability report, since it
// runs a credential lookup for every configured model on the run.
params.forceFullModelEvaluation = true;

AIPromptParams field reference

Field	Type	Purpose
prompt	MJAIPromptEntityExtended	Required. The prompt to execute.
data	Record<string, unknown>	Data context merged into the template (user data overrides system placeholders).
templateData	Record<string, unknown>	Highest-priority template data (overrides data).
contextUser	UserInfo	Required server-side. The user the run executes as (security/audit).
configurationId	string	AI Configuration scoping model selection (supports inheritance chains).
conversationMessages	ChatMessage[]	Prior conversation turns appended after the rendered prompt.
templateMessageRole	'system' | 'user' | 'none'	Where the rendered prompt lands in the message array.
override	{ modelId?, vendorId? }	Runtime model/vendor override (highest selection precedence).
modelSelectionPrompt	MJAIPromptEntityExtended	Use a different prompt’s model config for selection.
forceFullModelEvaluation	boolean	Probe credentials for every candidate instead of short-circuiting (default false).
childPrompts	ChildPromptParam[]	Hierarchical template composition (children render first).
parentPromptRunId / agentRunId	string	Link this run to a parent prompt run / agent run.
rerunFromPromptRunID	string	Mark this run as a re-run of a prior one.
effortLevel	number	Reasoning effort override (highest precedence — see Effort Level Control).
additionalParameters	Record<string, any>	Override inference params (temperature/topP/seed/stopSequences/…) per request.
systemPromptOverride	string	Bypass template rendering and use this system prompt verbatim.
skipValidation	boolean	Skip output validation/parsing.
cleanValidationSyntax	boolean	Strip ?/*/:type markers from result keys (auto-on when OutputExample set).
attemptJSONRepair	boolean	Repair malformed JSON object output via JSON5 then LLM repair.
credentialId	string	Per-request credential override (highest credential precedence).
apiKeys	AIAPIKey[]	Legacy per-request API keys (used only if no credential bindings resolve).
nativeFileInputs	NativeFileInput[]	Files attached natively when the driver supports the modality (else text fallback).
cancellationToken	AbortSignal	Cooperative cancellation, checked at each phase.
onProgress / onStreaming	callbacks	Progress updates / streamed output chunks.
onPromptRunCreated	(promptRunId) => void	Fired with the AIPromptRun.ID as soon as the record is created (ID available immediately; the save is fire-and-forget).
verbose	boolean	Verbose status logging for this run.
maxErrorLength	number	Truncate long error messages (e.g. provider failed-generation dumps).
provider	IMetadataProvider	Metadata provider for multi-provider scenarios.

Agent Execution Parameters

import { ExecuteAgentParams, UserScope } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: [{ role: 'user', content: 'Analyze this data' }],
    contextUser: currentUser,
    userScope: {
        primaryEntityName: 'Organizations',
        primaryRecordId: orgId,
        secondary: { TeamID: teamId }
    },
    onProgress: (step) => console.log(`${step.step}: ${step.message}`)
};

Runtime Action Changes

import { ExecuteAgentParams, ActionChange } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: messages,
    actionChanges: [
        { scope: 'global', mode: 'add', actionIds: ['crm-action-id'] },
        { scope: 'all-subagents', mode: 'remove', actionIds: ['dangerous-action-id'] }
    ]
};

Message Lifecycle Management

import { ExecuteAgentParams, MessageLifecycleEvent } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: messages,
    messageExpirationOverride: {
        expirationTurns: 2,
        expirationMode: 'Compact',
        compactMode: 'First N Chars',
        compactLength: 500
    },
    onMessageLifecycle: (event: MessageLifecycleEvent) => {
        console.log(`[Turn ${event.turn}] ${event.type}: ${event.reason}`);
    }
};

Effort Level Control

MemberJunction supports a 1-100 scale for AI model reasoning effort. The resolution precedence is:

1. ExecuteAgentParams.effortLevel (runtime override, highest priority)
2. AIAgent.DefaultPromptEffortLevel (agent default)
3. AIPrompt.EffortLevel (prompt default)
4. Provider default behavior (lowest priority)

Provider mappings:

• OpenAI: 1-33 = low, 34-66 = medium, 67-100 = high
• Anthropic: Thinking mode with 25K-2M token budgets
• Groq: Experimental reasoning_effort parameter
• Gemini: Reasoning mode intensity

Dependencies

• @memberjunction/ai — Core AI abstractions
• @memberjunction/core — MJ framework core (Metadata, RunView, UserInfo)
• @memberjunction/core-entities — Generated entity classes
• @memberjunction/global — Class factory and global utilities
• @memberjunction/actions-base — Action framework base types
• @memberjunction/templates-base-types — Template engine base types
• date-fns / date-fns-tz — Date/time formatting and timezone support