@memberjunction/aiengine 4.0.0 → 4.1.0

package/README.md

@@ -1,736 +1,193 @@
 # @memberjunction/aiengine
 
-The MemberJunction AI Engine package provides a comprehensive framework for AI-powered operations within the MemberJunction ecosystem. It serves as the central orchestration layer for AI model management, agent coordination, and basic prompt execution capabilities.
+Server-side AI Engine for MemberJunction. Wraps `AIEngineBase` and adds server-only capabilities including LLM execution, embedding generation, vector-based semantic search for agents and actions, and conversation attachment management. This package is the main orchestration layer for AI operations on the server.
 
-## Features
+## Architecture
 
-- **🤖 AI Agents**: Intelligent agents with specialized capabilities and context management
-- **🧠 Model Management**: Registry of AI models with automatic selection and load balancing
-- **📊 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
-- **🔍 Semantic Search**: Find similar agents, actions, notes, and examples using vector embeddings
+```mermaid
+graph TD
+    AIB["AIEngineBase<br/>Metadata Cache"]
+    style AIB fill:#2d6a9f,stroke:#1a4971,color:#fff
 
-> **📝 Advanced Prompt Management**: For sophisticated stored prompt management, template rendering, and parallel execution capabilities, see the [@memberjunction/ai-prompts](../Prompts/README.md) package.
+    AIE["AIEngine<br/>Server-Side Singleton"]
+    style AIE fill:#2d8659,stroke:#1a5c3a,color:#fff
 
-### Type Organization Update (2025)
+    subgraph "Server Capabilities"
+        LLM["LLM Execution<br/>ChatCompletion, Classify, Summarize"]
+        style LLM fill:#7c5295,stroke:#563a6b,color:#fff
 
-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`
+        EMB["Embedding Services<br/>Agent & Action Embeddings"]
+        style EMB fill:#7c5295,stroke:#563a6b,color:#fff
 
-## Installation
-
-```bash
-npm install @memberjunction/aiengine
-```
-
-## Requirements
-
-- 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
-
-### AI Agents
-
-**AI Agents** are the primary interface for interacting with AI capabilities. Each agent has:
-
-- **Specialized Purpose**: Domain-specific knowledge and capabilities
-- **Model Configuration**: Associated AI models for different tasks
-- **Context Management**: Maintains conversation context and state
-- **Action Library**: Predefined actions the agent can perform
-- **Note System**: Learning and memory capabilities
+        VS["Vector Search<br/>Semantic Agent/Action/Note Matching"]
+        style VS fill:#b8762f,stroke:#8a5722,color:#fff
 
-```typescript
-import { AIEngine } from '@memberjunction/aiengine';
+        ATT["Attachment Service<br/>Conversation Media Management"]
+        style ATT fill:#b8762f,stroke:#8a5722,color:#fff
+    end
 
-// Initialize the engine
-await AIEngine.Instance.Config(false, currentUser);
+    AIB --> AIE
+    AIE --> LLM
+    AIE --> EMB
+    AIE --> VS
+    AIE --> ATT
 
-// Get available agents
-const agents = AIEngine.Instance.Agents;
-const dataAnalysisAgent = agents.find(a => a.Name === 'Data Analysis Agent');
+    subgraph "Result Types"
+        AMR["AgentMatchResult"]
+        style AMR fill:#7c5295,stroke:#563a6b,color:#fff
 
-// Agents are configured through the MemberJunction metadata system
-console.log(`Agent: ${dataAnalysisAgent.Name}`);
-console.log(`Purpose: ${dataAnalysisAgent.Purpose}`);
-console.log(`Available Actions: ${dataAnalysisAgent.Actions.length}`);
-```
+        ACMR["ActionMatchResult"]
+        style ACMR fill:#7c5295,stroke:#563a6b,color:#fff
 
-### Simple LLM Completions
+        NMR["NoteMatchResult"]
+        style NMR fill:#7c5295,stroke:#563a6b,color:#fff
 
-For quick AI tasks without complex prompt management:
+        EMR["ExampleMatchResult"]
+        style EMR fill:#7c5295,stroke:#563a6b,color:#fff
+    end
 
-```typescript
-// Simple completion with automatic model selection
-const response = await AIEngine.Instance.SimpleLLMCompletion(
-    "Explain the benefits of TypeScript over JavaScript",
-    currentUser,
-    "You are a helpful programming tutor who explains concepts clearly."
-);
-
-console.log("AI Response:", response);
-
-// With specific model
-const specificModel = allModels.find(m => m.Name === 'GPT-4');
-const response2 = await AIEngine.Instance.SimpleLLMCompletion(
-    "Analyze this code for potential issues",
-    currentUser,
-    "You are an expert code reviewer",
-    specificModel
-);
+    VS --> AMR
+    VS --> ACMR
+    VS --> NMR
+    VS --> EMR
 ```
 
-> **Note**: For advanced prompt management with templates, parallel execution, and stored prompts, use the [@memberjunction/ai-prompts](../Prompts/README.md) package.
-
-
-
-### Model Management
-
-The engine maintains a comprehensive registry of AI models:
-
-```typescript
-// Get all available models
-const allModels = AIEngine.Instance.Models;
-const llmModels = AIEngine.Instance.LanguageModels;
-
-// Get the most powerful model for a specific vendor
-const bestOpenAI = await AIEngine.Instance.GetHighestPowerLLM('OpenAI', currentUser);
-const bestModel = await AIEngine.Instance.GetHighestPowerModel(null, 'LLM', currentUser);
-
-// Models are automatically selected based on:
-// - PowerRank: Relative capability ranking
-// - ModelType: LLM, Vision, Audio, etc.
-// - Vendor: OpenAI, Anthropic, Google, etc.
-// - Cost and performance characteristics
-```
-
-
-### Performance Monitoring & Analytics
-
-The engine provides basic tracking and analytics for AI operations. Advanced execution metrics, caching analytics, and parallel execution analytics are available in the [@memberjunction/ai-prompts](../Prompts/README.md) package.
-
-## API Reference
-
-### AIEngine Class
-
-The central orchestration class for all AI operations.
-
-#### Key Methods
-
-##### Initialization
-- `Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider)`: Load AI configuration metadata from the MemberJunction system
-
-##### Simple LLM Operations
-- `SimpleLLMCompletion(userPrompt: string, contextUser: UserInfo, systemPrompt?: string, model?: AIModelEntityExtended, apiKey?: string)`: Quick text completion for basic use cases
-- `ParallelLLMCompletions(userPrompt: string, contextUser: UserInfo, systemPrompt?: string, iterations?: number, temperatureIncrement?: number, baseTemperature?: number, model?: AIModelEntityExtended, apiKey?: string, callbacks?: ParallelChatCompletionsCallbacks)`: Execute multiple parallel completions with different parameters
-
-##### Model Management
-- `GetHighestPowerModel(vendorName: string, modelType: string, contextUser?: UserInfo)`: Get the most powerful model of a specific type from a vendor
-- `GetHighestPowerLLM(vendorName?: string, contextUser?: UserInfo)`: Get the most powerful LLM, optionally filtered by vendor
-- `PrepareLLMInstance(contextUser: UserInfo, model?: AIModelEntityExtended, apiKey?: string)`: Prepare an LLM instance with proper configuration
-- `PrepareChatMessages(userPrompt: string, systemPrompt?: string)`: Format chat messages in the standard format
-
-##### Agent Management
-- `GetAgentByName(agentName: string)`: Get a specific AI agent by name
-- `AgenteNoteTypeIDByName(agentNoteTypeName: string)`: Get the ID of an agent note type by name
-
-#### Key Properties
-
-##### Models and Databases
-- `Models`: All registered AI models with extended capabilities
-- `LanguageModels`: Filtered list of LLM type models
-- `VectorDatabases`: Available vector database configurations
-- `ArtifactTypes`: Registered artifact types for AI outputs
-
-##### AI Agents
-- `Agents`: Available AI agents with their capabilities and configurations
-- `AgentActions`: All available agent actions
-- `AgentModels`: Model associations for agents (deprecated)
-- `AgentNoteTypes`: Types of notes agents can create
-- `AgentNotes`: All agent notes/learnings
-
-##### Prompts (Reference Only)
-- `Prompts`: All registered prompts (use @memberjunction/ai-prompts for execution)
-- `PromptModels`: Model associations for prompts
-- `PromptTypes`: Available prompt types
-- `PromptCategories`: Prompt category hierarchy
-
-##### Deprecated Properties
-- `Actions`: Legacy AI actions (deprecated)
-- `EntityAIActions`: Legacy entity AI actions (deprecated)
-- `ModelActions`: Legacy model actions (deprecated)
-
-> **Note**: `Prompts` and `PromptCategories` properties are now available in the [@memberjunction/ai-prompts](../Prompts/README.md) package.
-
-### Advanced Prompt Execution
-
-For sophisticated prompt management with templates, parallel execution, and stored prompts, see the [@memberjunction/ai-prompts](../Prompts/README.md) package which provides the `AIPromptRunner` class and related functionality.
-
-### Extended Entity Classes
-
-#### AIAgentEntityExtended
-
-Extended AI Agent entity with relationship management:
-
-```typescript
-class AIAgentEntityExtended extends AIAgentEntity {
-    get Actions(): AIAgentActionEntity[];  // Agent's available actions
-    get Models(): AIAgentModelEntity[];    // Associated models (deprecated - use prompts)
-    get Notes(): AIAgentNoteEntity[];      // Agent's learning notes
-}
-```
-
-#### AIPromptCategoryEntityExtended
-
-Extended prompt category with hierarchical prompt management:
-
-```typescript
-class AIPromptCategoryEntityExtended extends AIPromptCategoryEntity {
-    get Prompts(): AIPromptEntity[];  // Prompts in this category
-}
-```
-
-#### AIModelEntityExtended
-
-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:
+## Installation
 
-```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
+```bash
+npm install @memberjunction/aiengine
 ```
 
-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
-
+**Note:** This package is server-side only. For metadata access on the client, use `@memberjunction/ai-engine-base` directly.
 
-## Advanced Features
+## Key Exports
 
-### Parallel Execution
+### AIEngine (Singleton)
 
-The AI Engine supports parallel execution of LLM calls with varying parameters:
+The main server-side engine. Uses composition (not inheritance) to delegate metadata operations to `AIEngineBase.Instance` while adding server-specific features.
 
 ```typescript
-// Execute 5 parallel completions with increasing temperature
-const results = await AIEngine.Instance.ParallelLLMCompletions(
-    "Generate creative product names for a smart water bottle",
-    currentUser,
-    "You are a creative product naming expert",
-    5,        // iterations
-    0.15,     // temperature increment
-    0.5,      // base temperature
-    null,     // use best available model
-    null,     // use default API key
-    {
-        onProgress: (completed, total) => {
-            console.log(`Progress: ${completed}/${total}`);
-        },
-        onComplete: (results) => {
-            console.log(`All ${results.length} completions finished`);
-        }
-    }
-);
-
-// Results array contains all completion responses
-results.forEach((result, index) => {
-    if (result.success) {
-        console.log(`Result ${index + 1}:`, result.data.choices[0].message.content);
-    }
-});
-```
-
-### Model Selection Strategies
-
-The AI Engine provides intelligent model selection:
-
-```typescript
-// Get the best model regardless of vendor
-const bestModel = await AIEngine.Instance.GetHighestPowerModel(null, 'LLM', currentUser);
-
-// Get the best OpenAI model specifically
-const bestOpenAI = await AIEngine.Instance.GetHighestPowerLLM('OpenAI', currentUser);
-
-// Get the best vision model
-const bestVision = await AIEngine.Instance.GetHighestPowerModel(null, 'Vision', currentUser);
-
-// Get the best audio model
-const bestAudio = await AIEngine.Instance.GetHighestPowerModel(null, 'Audio', currentUser);
-```
-
-### Working with AI Agents
+import { AIEngine } from '@memberjunction/aiengine';
 
-AI Agents provide specialized capabilities:
+// Initialize
+await AIEngine.Instance.Config(false, contextUser);
 
-```typescript
-// Find a specific agent
-const codeAgent = AIEngine.Instance.GetAgentByName('Code Assistant Agent');
-
-// Access agent properties
-console.log('Agent Purpose:', codeAgent.Purpose);
-console.log('Available Actions:', codeAgent.Actions.length);
-console.log('Learning Notes:', codeAgent.Notes.length);
-
-// Use agent context in prompts
-const response = await AIEngine.Instance.SimpleLLMCompletion(
-    "Review this TypeScript code for best practices",
-    currentUser,
-    `You are ${codeAgent.Name}. ${codeAgent.Purpose}`
-);
+// All AIEngineBase properties are delegated:
+const models = AIEngine.Instance.Models;
+const agents = AIEngine.Instance.Agents;
 ```
 
-### Semantic Search with Vector Embeddings
-
-The AI Engine provides semantic search capabilities using vector embeddings for finding similar agents, actions, notes, and examples. All search operations support efficient metadata filtering for scoped searches.
-
-#### Finding Similar Agents
+#### LLM Execution
 
 ```typescript
-// Find agents similar to a task description
-const taskDescription = "I need to analyze sales data and generate insights";
-const similarAgents = await AIEngine.Instance.FindSimilarAgents(
-    taskDescription,
-    5,        // topK: return top 5 matches
-    0.5       // minSimilarity: minimum similarity threshold (0-1)
-);
-
-similarAgents.forEach(match => {
-    console.log(`Agent: ${match.agent.Name}`);
-    console.log(`Similarity: ${(match.similarity * 100).toFixed(1)}%`);
-    console.log(`Purpose: ${match.agent.Purpose}\n`);
+// Direct chat completion
+const result = await AIEngine.Instance.ChatCompletion({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Explain quantum computing' }]
 });
-```
-
-#### Finding Similar Actions
 
-```typescript
-// Find actions that match a capability description
-const capability = "send email notifications to users";
-const similarActions = await AIEngine.Instance.FindSimilarActions(
-    capability,
-    10,       // topK
-    0.6       // minSimilarity
-);
-
-similarActions.forEach(match => {
-    console.log(`Action: ${match.action.Name}`);
-    console.log(`Match: ${(match.similarity * 100).toFixed(1)}%`);
-    console.log(`Description: ${match.action.Description}\n`);
+// Summarize text
+const summary = await AIEngine.Instance.SummarizeText({
+    model: 'gpt-4',
+    text: longDocument
 });
-```
-
-#### Finding Similar Agent Notes (with Filtering)
 
-Agent notes can be filtered by agent, user, or company for scoped searches. **Filtering happens before similarity calculation for optimal performance (10-20x faster!):**
-
-```typescript
-// Find notes similar to a query for a specific agent
-const queryText = "best practices for error handling";
-const agentId = 'agent-uuid-here';
-
-const similarNotes = await AIEngine.Instance.FindSimilarAgentNotes(
-    queryText,
-    agentId,    // Filter by agent ID (efficient pre-filtering)
-    undefined,  // userId filter (optional)
-    undefined,  // companyId filter (optional)
-    5,          // topK
-    0.7         // minSimilarity
-);
-
-similarNotes.forEach(match => {
-    console.log(`Note ID: ${match.note.ID}`);
-    console.log(`Similarity: ${(match.similarity * 100).toFixed(1)}%`);
-    console.log(`Content: ${match.note.Note}\n`);
+// Classify text
+const classification = await AIEngine.Instance.ClassifyText({
+    model: 'gpt-4',
+    text: inputText,
+    categories: ['positive', 'negative', 'neutral']
 });
-
-// Search across all agents (no filtering)
-const allNotes = await AIEngine.Instance.FindSimilarAgentNotes(
-    queryText,
-    undefined,  // No agent filter
-    undefined,  // No user filter
-    undefined,  // No company filter
-    10,
-    0.6
-);
 ```
 
-#### Finding Similar Examples (with Filtering)
+#### Semantic Search
 
-Agent examples also support efficient metadata filtering:
+Find agents, actions, notes, and examples using vector similarity:
 
 ```typescript
-// Find examples similar to an input for a specific agent
-const inputText = "Calculate the total revenue for Q4";
-const agentId = 'data-analysis-agent-uuid';
-
-const similarExamples = await AIEngine.Instance.FindSimilarAgentExamples(
-    inputText,
-    agentId,    // Filter by agent ID (efficient pre-filtering)
-    undefined,  // userId filter (optional)
-    undefined,  // companyId filter (optional)
-    3,          // topK
-    0.75        // minSimilarity
+// Find agents matching a user query
+const agentMatches: AgentMatchResult[] = await AIEngine.Instance.FindSimilarAgents(
+    'Help me analyze sales data',
+    5,           // topK
+    contextUser
 );
 
-similarExamples.forEach(match => {
-    console.log(`Example: ${match.example.ID}`);
-    console.log(`Similarity: ${(match.similarity * 100).toFixed(1)}%`);
-    console.log(`Input: ${match.example.ExampleInput}`);
-    console.log(`Output: ${match.example.ExampleOutput}\n`);
-});
-```
-
-#### Performance Benefits of Filtering
-
-The semantic search methods use pre-filtering for optimal performance:
-
-```typescript
-// ✅ EFFICIENT: Filter applied BEFORE similarity calculation
-// For 1000 notes where 50 belong to the agent:
-// - Filters to 50 notes (fast metadata check)
-// - Calculates similarity for 50 vectors
-// - Returns top 5 matches
-const filtered = await AIEngine.Instance.FindSimilarAgentNotes(
-    queryText,
-    agentId,     // Pre-filter by agent
-    undefined,
-    undefined,
+// Find relevant actions
+const actionMatches: ActionMatchResult[] = await AIEngine.Instance.FindSimilarActions(
+    'Send an email notification',
     5,
-    0.7
+    contextUser
 );
 
-// ❌ INEFFICIENT: Don't do this (old pattern)
-// Would calculate similarity for ALL 1000 notes then filter
-const all = await AIEngine.Instance.FindSimilarAgentNotes(queryText);
-const filtered = all.filter(n => n.note.AgentID === agentId).slice(0, 5);
-```
-
-**Speedup**: Pre-filtering provides 10-20x performance improvement for scoped searches because similarity calculation is much more expensive than metadata checks.
-
-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`: 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
-- `dotenv`: Environment variable management
-
-## Related Packages
-
-- `@memberjunction/ai-prompts`: Advanced prompt management with templates, parallel execution, and stored prompts
-- `@memberjunction/ai-agents`: AI Agent implementations and specialized behaviors
-- `@memberjunction/ai`: Core AI abstractions and interfaces
-- AI Provider Packages:
-  - `@memberjunction/ai-openai`: OpenAI model provider
-  - `@memberjunction/ai-anthropic`: Anthropic (Claude) model provider
-  - `@memberjunction/ai-groq`: Groq model provider
-  - `@memberjunction/ai-mistral`: Mistral AI model provider
-  - `@memberjunction/ai-azure`: Azure AI model provider
-  - `@memberjunction/ai-bedrock`: AWS Bedrock model provider
-  - `@memberjunction/ai-vertex`: Google Vertex AI model provider
-  - `@memberjunction/ai-cerebras`: Cerebras model provider
-  - `@memberjunction/ai-bettybot`: BettyBot model provider
-
-## Migration Guide
-
-### From AI Actions to AI Prompts
-
-If you're migrating from the deprecated AI Actions system, you can either:
-
-1. **Use Simple LLM Completions** (basic use cases):
-```typescript
-// Old AI Actions approach (deprecated)
-const actionParams: AIActionParams = {
-    actionId: 'action-id',
-    modelId: 'model-id',
-    systemPrompt: "System message",
-    userPrompt: "User message"
-};
-const result = await AIEngine.Instance.ExecuteAIAction(actionParams);
-
-// New Simple LLM approach (basic cases)
-const response = await AIEngine.Instance.SimpleLLMCompletion(
-    "User message",
-    currentUser,
-    "System message"
+// Find relevant notes for an agent
+const noteMatches: NoteMatchResult[] = await AIEngine.Instance.FindSimilarNotes(
+    agentId,
+    'Customer wants a refund',
+    10,
+    contextUser
 );
-```
-
-2. **Use Advanced Prompts** (complex use cases): See the [@memberjunction/ai-prompts](../Prompts/README.md) package for sophisticated prompt management with templates and parallel execution.
 
-### From Entity AI Actions to AI Agents
-
-```typescript
-// Old Entity AI Actions approach (deprecated)
-const entityParams: EntityAIActionParams = {
-    actionId: 'action-id',
-    modelId: 'model-id', 
-    entityAIActionId: 'entity-action-id',
-    entityRecord: entity
-};
-const result = await AIEngine.Instance.ExecuteEntityAIAction(entityParams);
-
-// New approach: Use AI Agents with either simple completions or advanced prompts
-const agent = AIEngine.Instance.Agents.find(a => a.Name === 'Your Agent Name');
-
-// For simple cases - use SimpleLLMCompletion
-const entityData = JSON.stringify(entity.GetAll());
-const response = await AIEngine.Instance.SimpleLLMCompletion(
-    `Analyze this ${entity.EntityType} entity: ${entityData}`,
-    currentUser,
-    `You are an expert ${agent.Purpose}`
+// Find relevant examples for an agent
+const exampleMatches: ExampleMatchResult[] = await AIEngine.Instance.FindSimilarExamples(
+    agentId,
+    'How do I reset my password?',
+    5,
+    contextUser
 );
-
-// For complex cases - use @memberjunction/ai-prompts package
 ```
 
-## Build and Development
+### Embedding Services
 
-### Building the Package
-```bash
-# From the package directory
-npm run build
+| Class | Purpose |
+|---|---|
+| `AgentEmbeddingService` | Generates and manages embeddings for AI agents, enabling semantic agent discovery |
+| `ActionEmbeddingService` | Generates and manages embeddings for actions, enabling semantic action matching |
 
-# Watch mode for development
-npm run watch
-```
-
-### Running Tests
-```bash
-npm test
-```
-
-## Configuration
+### Match Result Types
 
-The AI Engine uses environment variables for API keys:
+| Type | Fields | Description |
+|---|---|---|
+| `AgentMatchResult` | `agent`, `score`, `metadata` | Agent found via semantic similarity |
+| `ActionMatchResult` | `action`, `score`, `metadata` | Action found via semantic similarity |
+| `NoteMatchResult` | `note`, `score`, `metadata` | Agent note found via semantic similarity |
+| `ExampleMatchResult` | `example`, `score`, `metadata` | Agent example found via semantic similarity |
 
-```bash
-# .env file
-OPENAI_API_KEY=your-openai-key
-ANTHROPIC_API_KEY=your-anthropic-key
-GROQ_API_KEY=your-groq-key
-MISTRAL_API_KEY=your-mistral-key
-# ... other provider API keys
-```
-
-Alternatively, API keys can be passed directly to methods or configured in the MemberJunction metadata system.
+### ConversationAttachmentService
 
-## Error Handling
-
-The AI Engine provides comprehensive error handling:
+Manages media attachments (images, audio, video, files) in agent conversations:
 
 ```typescript
-try {
-    const response = await AIEngine.Instance.SimpleLLMCompletion(
-        userPrompt,
-        currentUser,
-        systemPrompt
-    );
-    console.log('Success:', response);
-} catch (error) {
-    if (error.message.includes('AI Metadata not loaded')) {
-        // Metadata needs to be loaded first
-        await AIEngine.Instance.Config(false, currentUser);
-    } else if (error.message.includes('User prompt not provided')) {
-        // Handle missing prompt
-    } else {
-        // Handle other errors
-        console.error('AI Engine Error:', error);
-    }
-}
-```
+import { ConversationAttachmentService } from '@memberjunction/aiengine';
 
-## Performance Considerations
+const service = new ConversationAttachmentService();
 
-1. **Metadata Loading**: Call `Config()` once at application startup to load all AI metadata
-2. **Model Selection**: Use `GetHighestPowerModel()` methods to automatically select optimal models
-3. **Parallel Execution**: Use `ParallelLLMCompletions()` for improved reliability and result quality
-4. **Caching**: For advanced caching capabilities, use the @memberjunction/ai-prompts package
-
-## License
-
-ISC
-
----
-
-## Deprecated Features
-
-The following features are deprecated and will be removed in a future version. Please migrate to the new AI Agents and AI Prompts system.
-
-### AI Actions (Deprecated)
-
-**⚠️ DEPRECATED**: AI Actions are deprecated in favor of the new AI Prompts system which provides better template support, parallel execution, and caching capabilities.
-
-AI Actions represented different AI operations like:
-
-- `chat`: General conversational AI
-- `summarize`: Text summarization  
-- `classify`: Text classification
-
-```typescript
-// Deprecated - use AI Prompts instead
-import { AIActionParams } from '@memberjunction/aiengine';
-
-const params: AIActionParams = {
-    actionId: 'summarize-action-id',
-    modelId: 'gpt4-model-id',
-    systemPrompt: "You are a helpful assistant that creates concise summaries.",
-    userPrompt: "Summarize the following document: " + documentText
-};
-
-const result = await AIEngine.Instance.ExecuteAIAction(params);
-console.log("Summary:", result.data?.choices[0]?.message?.content);
+// Process uploaded attachments for a conversation
+await service.ProcessAttachments(conversationId, attachments, contextUser);
 ```
 
-### Entity AI Actions (Deprecated)
-
-**⚠️ DEPRECATED**: Entity AI Actions are deprecated in favor of AI Agents which provide better context management, learning capabilities, and entity integration.
-
-Entity AI Actions connected AI actions to specific entity types, defining:
-
-- Input preparation from entity records
-- Output handling (save to fields or create related records)  
-- Default prompts and models to use
+## Usage Pattern
 
 ```typescript
-// Deprecated - use AI Agents instead
-import { EntityAIActionParams } from '@memberjunction/aiengine';
-import { Metadata } from '@memberjunction/core';
-
-// Load an entity record
-const md = new Metadata();
-const customer = await md.GetEntityObject('Customers');
-await customer.Load(customerId);
-
-// Execute an AI action
-const params: EntityAIActionParams = {
-    actionId: 'action-id-here',
-    modelId: 'model-id-here', 
-    entityAIActionId: 'entity-action-id-here',
-    entityRecord: customer
-};
-
-const result = await AIEngine.Instance.ExecuteEntityAIAction(params);
-
-if (result && result.success) {
-    console.log("AI processing completed successfully");
-    // The entity record has been updated if configured that way
-} else {
-    console.error("Error:", result.errorMessage);
-}
-```
-
-### Dynamic Prompt Generation (Legacy)
+import { AIEngine } from '@memberjunction/aiengine';
 
-**⚠️ DEPRECATED**: The old markup-based prompt generation is deprecated in favor of the template system integration.
+// 1. Initialize at server startup
+await AIEngine.Instance.Config(false, contextUser);
 
-```typescript
-// Deprecated markup approach
-const entityAction = {
-    UserMessage: "Please summarize the customer profile for {Name} who works at {Company}."
-};
+// 2. Access metadata (delegated to AIEngineBase)
+const model = AIEngine.Instance.Models.find(m => m.Name === 'GPT-4');
+const agent = AIEngine.Instance.GetAgentByName('Sales Assistant');
 
-// When executed on a record with Name="John Doe" and Company="Acme Inc"
-// The prompt becomes: "Please summarize the customer profile for John Doe who works at Acme Inc."
+// 3. Use server-side capabilities
+const similar = await AIEngine.Instance.FindSimilarAgents(userQuery, 5, contextUser);
 ```
 
-### Result Caching (Legacy Methods)
-
-**⚠️ DEPRECATED**: Manual cache management methods are deprecated in favor of automatic caching through the prompt system.
+## Dependencies
 
-```typescript
-// Deprecated manual caching
-const cached = await AIEngine.Instance.CheckResultCache(fullPromptText);
-if (cached) {
-    console.log("Using cached result:", cached.ResultText);
-    return cached.ResultText;
-}
-
-const result = await AIEngine.Instance.ExecuteAIAction(params);
-await AIEngine.Instance.CacheResult(model, prompt, fullPromptText, result.data.choices[0].message.content);
-```
+- `@memberjunction/ai-engine-base` -- Base metadata cache (AIEngineBase)
+- `@memberjunction/ai` -- Core AI abstractions (BaseLLM, BaseEmbeddings)
+- `@memberjunction/ai-core-plus` -- Extended entity classes
+- `@memberjunction/ai-vectors-memory` -- In-memory vector service for semantic search
+- `@memberjunction/core` -- MJ framework core
+- `@memberjunction/core-entities` -- Generated entity classes
+- `@memberjunction/actions-base` -- Action framework integration
+- `@memberjunction/storage` -- File storage integration for attachments

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/aiengine",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.1.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",
@@ -16,15 +16,15 @@
   "author": "MemberJunction.com",
   "license": "ISC",
   "dependencies": {
-    "@memberjunction/core": "4.0.0",
-    "@memberjunction/global": "4.0.0",
-    "@memberjunction/core-entities": "4.0.0",
-    "@memberjunction/actions-base": "4.0.0",
-    "@memberjunction/ai": "4.0.0",
-    "@memberjunction/ai-core-plus": "4.0.0",
-    "@memberjunction/ai-engine-base": "4.0.0",
-    "@memberjunction/ai-vectors-memory": "4.0.0",
-    "@memberjunction/storage": "4.0.0",
+    "@memberjunction/core": "4.1.0",
+    "@memberjunction/global": "4.1.0",
+    "@memberjunction/core-entities": "4.1.0",
+    "@memberjunction/actions-base": "4.1.0",
+    "@memberjunction/ai": "4.1.0",
+    "@memberjunction/ai-core-plus": "4.1.0",
+    "@memberjunction/ai-engine-base": "4.1.0",
+    "@memberjunction/ai-vectors-memory": "4.1.0",
+    "@memberjunction/storage": "4.1.0",
     "dotenv": "^17.2.4",
     "rxjs": "^7.8.2"
   },