@memberjunction/aiengine 2.50.0 → 2.52.0

package/README.md

@@ -9,9 +9,21 @@ The MemberJunction AI Engine package provides a comprehensive framework for AI-p
 - **📊 Performance Monitoring**: Basic tracking and analytics for AI operations
 - **🔗 Entity Integration**: Seamless integration with MemberJunction entity system
 - **⚡ Simple Prompt Execution**: Basic prompt execution for quick AI tasks
+- **🏗️ Agent Type System**: Defines agent types and their behavioral characteristics
 
 > **📝 Advanced Prompt Management**: For sophisticated stored prompt management, template rendering, and parallel execution capabilities, see the [@memberjunction/ai-prompts](../Prompts/README.md) package.
 
+### Type Organization Update (2025)
+
+As part of improving code organization:
+- **This package** now contains:
+  - Extended entity classes for AI operations
+  - Agent type definitions and factory interfaces
+  - The new `agent-types.ts` file with agent type classes
+- **Base AI types** are imported from `@memberjunction/ai` (Core)
+- **Agent execution types** are imported from `@memberjunction/ai-agents`
+- **Prompt types** are imported from `@memberjunction/ai-prompts`
+
 ## Installation
 
 ```bash
@@ -22,6 +34,7 @@ npm install @memberjunction/aiengine
 
 - Node.js 16+
 - MemberJunction Core libraries
+- [@memberjunction/ai](../Core/README.md) for base AI types
 - At least one AI model provider (e.g., `@memberjunction/ai-openai`)
 
 ## Core Architecture
@@ -190,6 +203,63 @@ class AIPromptCategoryEntityExtended extends AIPromptCategoryEntity {
 
 The AI Engine automatically extends AI Model entities with additional capabilities from the AI provider system. These extended models include all driver-specific functionality and API integration.
 
+### Agent Type System
+
+The Engine now includes specialized agent type classes in `agent-types.ts`:
+
+```typescript
+// Base agent type - foundation for all agent types
+import { BaseAgentType } from '@memberjunction/aiengine';
+
+// Specialized agent types
+import { LoopAgentType } from '@memberjunction/aiengine';
+
+// Agent types define behavioral characteristics:
+// - System prompts for consistent behavior
+// - Decision-making patterns
+// - Execution flow control
+```
+
+### Type-Safe Sub-Agent Requests (New in v2.51.0)
+
+The AI Engine now provides type-safe context propagation for sub-agent requests. Context is optional in the request definition and is provided at execution time by the framework:
+
+```typescript
+import { AgentSubAgentRequest, BaseAgentNextStep } from '@memberjunction/aiengine';
+
+// Define your context type
+interface MyContext {
+    apiEndpoint: string;
+    apiKey: string;
+    environment: 'dev' | 'staging' | 'prod';
+}
+
+// Create a typed sub-agent request - context is optional here
+const subAgentRequest: AgentSubAgentRequest<MyContext> = {
+    id: 'sub-agent-uuid',
+    name: 'DataProcessorAgent',
+    message: 'Process the uploaded data',
+    terminateAfter: false
+    // context is NOT set by AI agents - it's provided by the framework at execution time
+};
+
+// Use in agent next step decisions
+const nextStep: BaseAgentNextStep<MyContext> = {
+    step: 'sub-agent',
+    subAgent: subAgentRequest
+};
+
+// At execution time, the framework provides the context:
+// The parent agent's context is automatically passed to sub-agents
+// This ensures consistent runtime configuration across the agent hierarchy
+```
+
+This pattern ensures:
+- Type safety when defining sub-agent requests
+- Context is consistently provided by the execution framework
+- AI agents focus on decision logic without managing runtime configuration
+- Runtime contexts (API keys, endpoints, etc.) flow through the agent hierarchy automatically
+
 
 ## Advanced Features
 
@@ -267,12 +337,35 @@ const response = await AIEngine.Instance.SimpleLLMCompletion(
 
 For sophisticated parallel execution, template rendering, and stored prompt management, see the [@memberjunction/ai-prompts](../Prompts/README.md) package.
 
+## Import Examples
+
+```typescript
+// Import main AI Engine class
+import { AIEngine } from '@memberjunction/aiengine';
+
+// Import extended entity types
+import { 
+  AIAgentEntityExtended,
+  AIPromptCategoryEntityExtended,
+  AIModelEntityExtended 
+} from '@memberjunction/aiengine';
+
+// Import agent type classes
+import { BaseAgentType, LoopAgentType } from '@memberjunction/aiengine';
+
+// Import base AI types from Core
+import { BaseLLM, ChatParams, ChatResult } from '@memberjunction/ai';
+
+// When working with agents, import execution types
+import { AgentExecutionParams, AgentExecutionResult } from '@memberjunction/ai-agents';
+```
+
 ## Dependencies
 
 - `@memberjunction/core`: MemberJunction core library
 - `@memberjunction/global`: MemberJunction global utilities  
 - `@memberjunction/core-entities`: MemberJunction entity definitions
-- `@memberjunction/ai`: AI abstractions and interfaces
+- `@memberjunction/ai`: Base AI types and interfaces (imported for core types)
 - `@memberjunction/templates`: Template engine integration
 - `@memberjunction/templates-base-types`: Template base type definitions
 - `rxjs`: Reactive programming support

package/dist/agent-types.d.ts

@@ -0,0 +1,127 @@
+import { AIPromptRunResult } from '@memberjunction/ai';
+import { AIAgentRunEntity, AIAgentRunStepEntity } from '@memberjunction/core-entities';
+import { ActionResult, ActionResultSimple } from '@memberjunction/actions-base';
+export type AgentAction = {
+    id: string;
+    name: string;
+    params: Record<string, unknown>;
+};
+export type AgentSubAgentRequest<TContext = any> = {
+    id: string;
+    name: string;
+    message: string;
+    terminateAfter: boolean;
+    context?: TContext;
+};
+export type BaseAgentNextStep<TContext = any> = {
+    step: 'success' | 'failed' | 'retry' | 'sub-agent' | 'actions' | 'chat';
+    returnValue?: any;
+    errorMessage?: string;
+    retryReason?: string;
+    retryInstructions?: string;
+    subAgent?: AgentSubAgentRequest<TContext>;
+    actions?: AgentAction[];
+    userMessage?: string;
+};
+export type ExecuteAgentResult = {
+    success: boolean;
+    finalStep: BaseAgentNextStep['step'];
+    returnValue?: any;
+    errorMessage?: string;
+    cancelled?: boolean;
+    cancellationReason?: 'user_requested' | 'timeout' | 'system';
+    agentRun: AIAgentRunEntity;
+    executionTree: ExecutionNode[];
+};
+export type ExecutionChainStep = {
+    stepEntity: AIAgentRunStepEntity;
+    executionType: 'prompt' | 'action' | 'sub-agent' | 'decision' | 'chat' | 'validation';
+    executionResult: StepExecutionResult;
+    nextStepDecision: NextStepDecision;
+    startTime: Date;
+    endTime?: Date;
+    durationMs?: number;
+};
+export type StepExecutionResult = PromptExecutionResult | ActionExecutionResult | SubAgentExecutionResult | DecisionExecutionResult | ChatExecutionResult | ValidationExecutionResult;
+export type ExecutionNode = {
+    step: AIAgentRunStepEntity;
+    inputData: any;
+    outputData: any;
+    executionType: 'prompt' | 'action' | 'sub-agent' | 'decision' | 'chat' | 'validation';
+    startTime: Date;
+    endTime?: Date;
+    durationMs?: number;
+    nextStepDecision?: NextStepDecision;
+    children?: ExecutionNode[];
+    depth: number;
+    parentStepId?: string;
+    agentHierarchy: string[];
+};
+export type PromptExecutionResult = {
+    type: 'prompt';
+    promptId: string;
+    promptName: string;
+    result: AIPromptRunResult;
+};
+export type ActionExecutionResult = {
+    type: 'action';
+    actionId: string;
+    actionName: string;
+    result: ActionResult | ActionResultSimple;
+};
+export type SubAgentExecutionResult = {
+    type: 'sub-agent';
+    subAgentId: string;
+    subAgentName: string;
+    result: ExecuteAgentResult;
+};
+export type DecisionExecutionResult = {
+    type: 'decision';
+    decisionLogic: string;
+    inputContext: any;
+    result: BaseAgentNextStep;
+};
+export type ChatExecutionResult = {
+    type: 'chat';
+    userMessage: string;
+    userResponse?: string;
+    result: {
+        success: boolean;
+        continueExecution: boolean;
+    };
+};
+export type ValidationExecutionResult = {
+    type: 'validation';
+    validationTarget: string;
+    result: {
+        valid: boolean;
+        errors?: string[];
+    };
+};
+export type NextStepDecision = {
+    decision: BaseAgentNextStep['step'];
+    reasoning?: string;
+    nextStepDetails?: NextStepDetails;
+};
+export type NextStepDetails = {
+    type: 'prompt';
+    promptId: string;
+    promptName: string;
+} | {
+    type: 'action';
+    actions: AgentAction[];
+} | {
+    type: 'sub-agent';
+    subAgent: AgentSubAgentRequest;
+} | {
+    type: 'retry';
+    retryReason: string;
+    retryInstructions: string;
+} | {
+    type: 'chat';
+    message: string;
+} | {
+    type: 'complete';
+    returnValue?: any;
+};
+//# sourceMappingURL=agent-types.d.ts.map

package/dist/agent-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-types.d.ts","sourceRoot":"","sources":["../src/agent-types.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAUhF,MAAM,MAAM,WAAW,GAAG;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAA;AAwCD,MAAM,MAAM,oBAAoB,CAAC,QAAQ,GAAG,GAAG,IAAI;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,QAAQ,CAAC;CACtB,CAAA;AAgCD,MAAM,MAAM,iBAAiB,CAAC,QAAQ,GAAG,GAAG,IAAI;IAC5C,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;IACxE,WAAW,CAAC,EAAE,GAAG,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB,CAAA;AAoBD,MAAM,MAAM,kBAAkB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,GAAG,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kBAAkB,CAAC,EAAE,gBAAgB,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC7D,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,aAAa,EAAE,aAAa,EAAE,CAAC;CAClC,CAAA;AAkBD,MAAM,MAAM,kBAAkB,GAAG;IAC7B,UAAU,EAAE,oBAAoB,CAAC;IACjC,aAAa,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;IACtF,eAAe,EAAE,mBAAmB,CAAC;IACrC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,CAAA;AAQD,MAAM,MAAM,mBAAmB,GACzB,qBAAqB,GACrB,qBAAqB,GACrB,uBAAuB,GACvB,uBAAuB,GACvB,mBAAmB,GACnB,yBAAyB,CAAC;AAuBhC,MAAM,MAAM,aAAa,GAAG;IACxB,IAAI,EAAE,oBAAoB,CAAC;IAC3B,SAAS,EAAE,GAAG,CAAC;IACf,UAAU,EAAE,GAAG,CAAC;IAChB,aAAa,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,YAAY,CAAC;IACtF,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAA;AAWD,MAAM,MAAM,qBAAqB,GAAG;IAChC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;CAC7B,CAAA;AAWD,MAAM,MAAM,qBAAqB,GAAG;IAChC,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,YAAY,GAAG,kBAAkB,CAAC;CAC7C,CAAA;AAcD,MAAM,MAAM,uBAAuB,GAAG;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,kBAAkB,CAAC;CAC9B,CAAA;AAWD,MAAM,MAAM,uBAAuB,GAAG;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,GAAG,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;CAC7B,CAAA;AAWD,MAAM,MAAM,mBAAmB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,iBAAiB,EAAE,OAAO,CAAA;KAAE,CAAC;CAC5D,CAAA;AAUD,MAAM,MAAM,yBAAyB,GAAG;IACpC,IAAI,EAAE,YAAY,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACjD,CAAA;AAaD,MAAM,MAAM,gBAAgB,GAAG;IAC3B,QAAQ,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACrC,CAAA;AAQD,MAAM,MAAM,eAAe,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,WAAW,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,WAAW,CAAC,EAAE,GAAG,CAAA;CAAE,CAAC"}

package/dist/agent-types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=agent-types.js.map

package/dist/agent-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-types.js","sourceRoot":"","sources":["../src/agent-types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './AIEngine';
+export * from './agent-types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./AIEngine"), exports);
+__exportStar(require("./agent-types"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,gDAA8B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/aiengine",
-  "version": "2.50.0",
+  "version": "2.52.0",
   "description": "MemberJunction: AI Engine Package - handles automatic execution of Entity AI Actions using AI Models",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,11 +15,11 @@
   "author": "MemberJunction.com",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/core": "2.50.0",
-    "@memberjunction/global": "2.50.0",
-    "@memberjunction/core-entities": "2.50.0",
-    "@memberjunction/ai": "2.50.0",
-    "@memberjunction/ai-engine-base": "2.50.0",
+    "@memberjunction/core": "2.52.0",
+    "@memberjunction/global": "2.52.0",
+    "@memberjunction/core-entities": "2.52.0",
+    "@memberjunction/ai": "2.52.0",
+    "@memberjunction/ai-engine-base": "2.52.0",
     "dotenv": "^16.4.1",
     "rxjs": "^7.8.1"
   },