# @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

```mermaid
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

```bash
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`](../Agents/README.md#consolidation-pipeline).

### 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

```typescript
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

```typescript
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

```typescript
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

```typescript
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