@memberjunction/ai-recommendations 4.0.0 → 4.2.0

package/README.md

@@ -0,0 +1,376 @@
+# @memberjunction/ai-recommendations
+
+A provider-based recommendation engine for MemberJunction. Manages recommendation runs, delegates to pluggable providers via the class factory, and tracks results through Recommendation, Recommendation Run, and Recommendation Item entities.
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph Engine["@memberjunction/ai-recommendations"]
+        REB["RecommendationEngineBase<br/>(singleton BaseEngine)"]
+        RPB["RecommendationProviderBase<br/>(abstract)"]
+        RR["RecommendationRequest&lt;T&gt;"]
+        RRES["RecommendationResult"]
+    end
+
+    subgraph Providers["Registered Providers"]
+        P1["Provider A"]
+        P2["Provider B"]
+    end
+
+    subgraph MJEntities["MemberJunction Entities"]
+        RP["Recommendation Providers"]
+        RUN["Recommendation Runs"]
+        REC["Recommendations"]
+        RI["Recommendation Items"]
+        LIST["Lists / List Details"]
+    end
+
+    subgraph MJCore["MemberJunction Core"]
+        BE["BaseEngine"]
+        CF["ClassFactory"]
+        MD["Metadata"]
+    end
+
+    REB -->|extends| BE
+    REB -->|discovers| CF
+    CF -->|creates| P1
+    CF -->|creates| P2
+    P1 -->|extends| RPB
+    P2 -->|extends| RPB
+    REB --> RP
+    REB --> RUN
+    RPB --> REC
+    RPB --> RI
+    REB --> LIST
+
+    style Engine fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Providers fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style MJEntities fill:#b8762f,stroke:#8a5722,color:#fff
+    style MJCore fill:#7c5295,stroke:#563a6b,color:#fff
+```
+
+## Installation
+
+```bash
+npm install @memberjunction/ai-recommendations
+```
+
+## Overview
+
+This package provides the framework for running recommendations in MemberJunction. It follows the engine/provider pattern used throughout the platform:
+
+1. **RecommendationEngineBase** -- a singleton engine (extending `BaseEngine`) that loads provider metadata, selects a provider, creates Recommendation Run tracking records, and delegates the actual recommendation logic
+2. **RecommendationProviderBase** -- an abstract class that concrete providers implement to generate recommendations for each source record
+3. **RecommendationRequest/RecommendationResult** -- typed request and response objects that flow through the pipeline
+
+Providers are discovered at runtime through MemberJunction's `ClassFactory` using `@RegisterClass(RecommendationProviderBase, 'ProviderName')`.
+
+## Recommendation Flow
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant Engine as RecommendationEngineBase
+    participant CF as ClassFactory
+    participant Provider as RecommendationProvider
+    participant DB as MJ Database
+
+    Caller->>Engine: Recommend(request)
+    Engine->>Engine: TryThrowIfNotLoaded()
+
+    alt Provider specified
+        Engine->>Engine: Use request.Provider
+    else No provider
+        Engine->>Engine: Use first available
+    end
+
+    Engine->>Engine: GetRecommendationEntities(request)
+
+    alt From List
+        Engine->>DB: Load List + List Details
+        Engine->>DB: Load entity records by IDs
+    else From EntityAndRecordsInfo
+        Engine->>DB: Load records by entity name + IDs
+    else Pre-built
+        Engine->>Engine: Validate Recommendations array
+    end
+
+    Engine->>DB: Create Recommendation Run (Status: In Progress)
+
+    opt CreateErrorList = true
+        Engine->>DB: Create error tracking List
+    end
+
+    Engine->>CF: CreateInstance(provider.Name)
+    CF-->>Engine: Provider instance
+
+    Engine->>Provider: Recommend(request)
+
+    loop For each recommendation
+        Provider->>Provider: Call external API
+        Provider->>DB: SaveRecommendation + Items
+    end
+
+    Provider-->>Engine: RecommendationResult
+
+    Engine->>DB: Update Run (Completed/Error)
+    Engine-->>Caller: RecommendationResult
+```
+
+## Core Components
+
+### RecommendationEngineBase
+
+A singleton engine that manages the recommendation lifecycle.
+
+```typescript
+import { RecommendationEngineBase } from '@memberjunction/ai-recommendations';
+
+// Access the singleton
+const engine = RecommendationEngineBase.Instance;
+
+// Initialize (loads Recommendation Providers metadata)
+await engine.Config(false, contextUser);
+
+// Run recommendations
+const result = await engine.Recommend(request);
+```
+
+**Key properties and methods:**
+
+| Member | Description |
+|---|---|
+| `Instance` | Static getter for the singleton instance |
+| `RecommendationProviders` | Array of `RecommendationProviderEntity` loaded from metadata |
+| `Config(forceRefresh?, contextUser?, provider?)` | Loads provider metadata into cache |
+| `Recommend<T>(request)` | Runs the full recommendation pipeline |
+
+### RecommendationProviderBase
+
+Abstract base class for implementing recommendation providers.
+
+```mermaid
+classDiagram
+    class RecommendationProviderBase {
+        <<abstract>>
+        -_md : Metadata
+        -_ContextUser : UserInfo
+        +ContextUser : UserInfo
+        +Recommend(request)* RecommendationResult
+        #SaveRecommendation(rec, runID, items) boolean
+    }
+
+    class ConcreteProvider {
+        +Recommend(request) RecommendationResult
+    }
+
+    RecommendationProviderBase <|-- ConcreteProvider
+
+    style RecommendationProviderBase fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style ConcreteProvider fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
+
+The `SaveRecommendation` helper method handles:
+1. Setting the `RecommendationRunID` on the recommendation entity
+2. Saving the recommendation record
+3. Linking and saving all `RecommendationItemEntity` records
+
+### RecommendationRequest\<T\>
+
+The request object supports three ways to specify source records:
+
+```mermaid
+graph TD
+    RR["RecommendationRequest"]
+    OPT1["Recommendations[]<br/>Pre-built entities"]
+    OPT2["EntityAndRecordsInfo<br/>Entity name + Record IDs"]
+    OPT3["ListID<br/>MJ List reference"]
+
+    RR --> OPT1
+    RR --> OPT2
+    RR --> OPT3
+
+    style RR fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style OPT1 fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style OPT2 fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style OPT3 fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `Recommendations` | `RecommendationEntity[]` | Pre-built unsaved recommendation entities |
+| `EntityAndRecordsInfo` | `{ EntityName, RecordIDs }` | Entity name and array of record IDs to process |
+| `ListID` | `string` | ID of a MJ List whose details become the source records |
+| `Provider` | `RecommendationProviderEntity` | Specific provider to use (defaults to first available) |
+| `CurrentUser` | `UserInfo` | User context |
+| `Options` | `T` | Generic additional options passed to the provider |
+| `CreateErrorList` | `boolean` | Whether to create an error tracking list |
+| `RunID` | `string` | Set automatically by the engine |
+| `ErrorListID` | `string` | Set automatically if error list is created |
+
+### RecommendationResult
+
+```typescript
+class RecommendationResult {
+    Request: RecommendationRequest;
+    RecommendationRun?: RecommendationRunEntity;
+    RecommendationItems?: RecommendationItemEntity[];
+    Success: boolean;
+    ErrorMessage: string;
+
+    AppendWarning(message: string): void;   // Adds warning without setting Success=false
+    AppendError(message: string): void;     // Adds error and sets Success=false
+    GetErrorMessages(): string[];           // Splits ErrorMessage into array
+}
+```
+
+## Usage
+
+### Running Recommendations from a List
+
+```typescript
+import { RecommendationEngineBase } from '@memberjunction/ai-recommendations';
+import { RecommendationRequest } from '@memberjunction/ai-recommendations';
+
+const engine = RecommendationEngineBase.Instance;
+await engine.Config(false, contextUser);
+
+const request = new RecommendationRequest();
+request.ListID = 'list-uuid';
+request.CurrentUser = contextUser;
+request.CreateErrorList = true;
+
+const result = await engine.Recommend(request);
+
+if (result.Success) {
+    console.log(`Generated ${result.RecommendationItems?.length ?? 0} items`);
+} else {
+    console.error(result.ErrorMessage);
+}
+```
+
+### Running Recommendations by Entity and Record IDs
+
+```typescript
+const request = new RecommendationRequest();
+request.EntityAndRecordsInfo = {
+    EntityName: 'Products',
+    RecordIDs: ['id-1', 'id-2', 'id-3']
+};
+request.CurrentUser = contextUser;
+
+const result = await engine.Recommend(request);
+```
+
+### Implementing a Provider
+
+```typescript
+import { RecommendationProviderBase } from '@memberjunction/ai-recommendations';
+import { RecommendationRequest, RecommendationResult } from '@memberjunction/ai-recommendations';
+import { RegisterClass } from '@memberjunction/global';
+import { Metadata } from '@memberjunction/core';
+import { RecommendationItemEntity } from '@memberjunction/core-entities';
+
+@RegisterClass(RecommendationProviderBase, 'My Recommendation Provider')
+export class MyProvider extends RecommendationProviderBase {
+    async Recommend(request: RecommendationRequest): Promise<RecommendationResult> {
+        const result = new RecommendationResult(request);
+        const md = new Metadata();
+
+        for (const rec of request.Recommendations) {
+            // Call your recommendation API/algorithm
+            const suggestions = await this.getSuggestions(rec.SourceEntityRecordID);
+
+            const items: RecommendationItemEntity[] = [];
+            for (const suggestion of suggestions) {
+                const item = await md.GetEntityObject<RecommendationItemEntity>(
+                    'Recommendation Items', request.CurrentUser
+                );
+                item.NewRecord();
+                item.DestinationEntityID = suggestion.entityID;
+                item.DestinationEntityRecordID = suggestion.recordID;
+                item.MatchProbability = suggestion.score;
+                items.push(item);
+            }
+
+            await this.SaveRecommendation(rec, request.RunID, items);
+        }
+
+        return result;
+    }
+
+    private async getSuggestions(recordID: string): Promise<Suggestion[]> {
+        // Your recommendation logic here
+        return [];
+    }
+}
+```
+
+## Database Entities
+
+```mermaid
+erDiagram
+    RECOMMENDATION_PROVIDERS {
+        string ID PK
+        string Name
+        string Description
+    }
+
+    RECOMMENDATION_RUNS {
+        string ID PK
+        string RecommendationProviderID FK
+        string RunByUserID FK
+        datetime StartDate
+        string Status
+        string Description
+    }
+
+    RECOMMENDATIONS {
+        string ID PK
+        string RecommendationRunID FK
+        string SourceEntityID FK
+        string SourceEntityRecordID
+    }
+
+    RECOMMENDATION_ITEMS {
+        string ID PK
+        string RecommendationID FK
+        string DestinationEntityID FK
+        string DestinationEntityRecordID
+        float MatchProbability
+    }
+
+    LISTS {
+        string ID PK
+        string Name
+        string EntityID FK
+        string UserID FK
+    }
+
+    RECOMMENDATION_PROVIDERS ||--o{ RECOMMENDATION_RUNS : has
+    RECOMMENDATION_RUNS ||--o{ RECOMMENDATIONS : contains
+    RECOMMENDATIONS ||--o{ RECOMMENDATION_ITEMS : produces
+```
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| `@memberjunction/core` | `BaseEngine`, `Metadata`, `RunView`, `UserInfo`, `LogStatus` |
+| `@memberjunction/core-entities` | `RecommendationEntity`, `RecommendationRunEntity`, `RecommendationItemEntity`, `RecommendationProviderEntity`, `ListEntity` |
+| `@memberjunction/global` | `MJGlobal` class factory for provider discovery |
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Development mode
+npm run start
+```
+
+## License
+
+ISC

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/ai-recommendations",
   "type": "module",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "MemberJunction Recommendations Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,10 +20,10 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@memberjunction/global": "4.0.0",
-    "@memberjunction/core": "4.0.0",
-    "@memberjunction/core-entities": "4.0.0",
-    "@memberjunction/ai": "4.0.0"
+    "@memberjunction/global": "4.2.0",
+    "@memberjunction/core": "4.2.0",
+    "@memberjunction/core-entities": "4.2.0",
+    "@memberjunction/ai": "4.2.0"
   },
   "repository": {
     "type": "git",

package/readme.md

@@ -1,16 +1,54 @@
 # @memberjunction/ai-recommendations
 
-The MemberJunction Recommendations Engine provides a flexible and extensible framework for integrating with AI-powered recommendation systems. It handles the orchestration of recommendation requests, provider management, and the storage of recommendation results within the MemberJunction ecosystem.
-
-## Features
-
-- **Extensible Provider Framework**: Support for multiple recommendation providers through a unified API
-- **Built-in Tracking**: Automatic tracking of recommendation runs and results
-- **Entity Integration**: Seamless integration with MemberJunction entities and records
-- **List Support**: Generate recommendations for records in a list
-- **Error Handling**: Comprehensive error tracking and reporting
-- **Batch Processing**: Process multiple recommendation requests efficiently
-- **Metadata Management**: Automatic management of recommendation metadata
+A provider-based recommendation engine for MemberJunction. Manages recommendation runs, delegates to pluggable providers via the class factory, and tracks results through Recommendation, Recommendation Run, and Recommendation Item entities.
+
+## Architecture
+
+```mermaid
+graph TD
+    subgraph Engine["@memberjunction/ai-recommendations"]
+        REB["RecommendationEngineBase<br/>(singleton BaseEngine)"]
+        RPB["RecommendationProviderBase<br/>(abstract)"]
+        RR["RecommendationRequest&lt;T&gt;"]
+        RRES["RecommendationResult"]
+    end
+
+    subgraph Providers["Registered Providers"]
+        P1["Provider A"]
+        P2["Provider B"]
+    end
+
+    subgraph MJEntities["MemberJunction Entities"]
+        RP["Recommendation Providers"]
+        RUN["Recommendation Runs"]
+        REC["Recommendations"]
+        RI["Recommendation Items"]
+        LIST["Lists / List Details"]
+    end
+
+    subgraph MJCore["MemberJunction Core"]
+        BE["BaseEngine"]
+        CF["ClassFactory"]
+        MD["Metadata"]
+    end
+
+    REB -->|extends| BE
+    REB -->|discovers| CF
+    CF -->|creates| P1
+    CF -->|creates| P2
+    P1 -->|extends| RPB
+    P2 -->|extends| RPB
+    REB --> RP
+    REB --> RUN
+    RPB --> REC
+    RPB --> RI
+    REB --> LIST
+
+    style Engine fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Providers fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style MJEntities fill:#b8762f,stroke:#8a5722,color:#fff
+    style MJCore fill:#7c5295,stroke:#563a6b,color:#fff
+```
 
 ## Installation
 
@@ -18,220 +56,321 @@ The MemberJunction Recommendations Engine provides a flexible and extensible fra
 npm install @memberjunction/ai-recommendations
 ```
 
+## Overview
+
+This package provides the framework for running recommendations in MemberJunction. It follows the engine/provider pattern used throughout the platform:
+
+1. **RecommendationEngineBase** -- a singleton engine (extending `BaseEngine`) that loads provider metadata, selects a provider, creates Recommendation Run tracking records, and delegates the actual recommendation logic
+2. **RecommendationProviderBase** -- an abstract class that concrete providers implement to generate recommendations for each source record
+3. **RecommendationRequest/RecommendationResult** -- typed request and response objects that flow through the pipeline
+
+Providers are discovered at runtime through MemberJunction's `ClassFactory` using `@RegisterClass(RecommendationProviderBase, 'ProviderName')`.
+
+## Recommendation Flow
+
+```mermaid
+sequenceDiagram
+    participant Caller
+    participant Engine as RecommendationEngineBase
+    participant CF as ClassFactory
+    participant Provider as RecommendationProvider
+    participant DB as MJ Database
+
+    Caller->>Engine: Recommend(request)
+    Engine->>Engine: TryThrowIfNotLoaded()
+
+    alt Provider specified
+        Engine->>Engine: Use request.Provider
+    else No provider
+        Engine->>Engine: Use first available
+    end
+
+    Engine->>Engine: GetRecommendationEntities(request)
+
+    alt From List
+        Engine->>DB: Load List + List Details
+        Engine->>DB: Load entity records by IDs
+    else From EntityAndRecordsInfo
+        Engine->>DB: Load records by entity name + IDs
+    else Pre-built
+        Engine->>Engine: Validate Recommendations array
+    end
+
+    Engine->>DB: Create Recommendation Run (Status: In Progress)
+
+    opt CreateErrorList = true
+        Engine->>DB: Create error tracking List
+    end
+
+    Engine->>CF: CreateInstance(provider.Name)
+    CF-->>Engine: Provider instance
+
+    Engine->>Provider: Recommend(request)
+
+    loop For each recommendation
+        Provider->>Provider: Call external API
+        Provider->>DB: SaveRecommendation + Items
+    end
+
+    Provider-->>Engine: RecommendationResult
+
+    Engine->>DB: Update Run (Completed/Error)
+    Engine-->>Caller: RecommendationResult
+```
+
 ## Core Components
 
 ### RecommendationEngineBase
 
-The main engine class that coordinates recommendation requests:
+A singleton engine that manages the recommendation lifecycle.
 
 ```typescript
-import { RecommendationEngineBase, RecommendationRequest } from '@memberjunction/ai-recommendations';
+import { RecommendationEngineBase } from '@memberjunction/ai-recommendations';
 
-// Initialize and load the engine
-await RecommendationEngineBase.Instance.Config();
-
-// Create a recommendation request
-const request = new RecommendationRequest();
+// Access the singleton
+const engine = RecommendationEngineBase.Instance;
 
-// Configure the request
-request.EntityAndRecordsInfo = {
-  EntityName: 'Customers',
-  RecordIDs: ['CUST001', 'CUST002']
-};
+// Initialize (loads Recommendation Providers metadata)
+await engine.Config(false, contextUser);
 
-// Execute the recommendation
-const result = await RecommendationEngineBase.Instance.Recommend(request);
+// Run recommendations
+const result = await engine.Recommend(request);
 ```
 
-### RecommendationProviderBase
+**Key properties and methods:**
 
-Abstract base class for implementing recommendation providers:
+| Member | Description |
+|---|---|
+| `Instance` | Static getter for the singleton instance |
+| `RecommendationProviders` | Array of `RecommendationProviderEntity` loaded from metadata |
+| `Config(forceRefresh?, contextUser?, provider?)` | Loads provider metadata into cache |
+| `Recommend<T>(request)` | Runs the full recommendation pipeline |
 
-```typescript
-import { RecommendationProviderBase, RecommendationRequest, RecommendationResult } from '@memberjunction/ai-recommendations';
-import { UserInfo } from '@memberjunction/core';
-import { RecommendationItemEntity } from '@memberjunction/core-entities';
+### RecommendationProviderBase
 
-export class MyRecommendationProvider extends RecommendationProviderBase {
-  constructor(contextUser: UserInfo) {
-    super(contextUser);
-  }
-
-  public async Recommend(request: RecommendationRequest): Promise<RecommendationResult> {
-    const result = new RecommendationResult(request);
-    
-    try {
-      // Process each recommendation
-      for (const recommendation of request.Recommendations) {
-        // Generate items for this recommendation
-        const items: RecommendationItemEntity[] = [];
-        
-        // Your recommendation logic here
-        // ...
-        
-        // Save the recommendation and its items
-        await this.SaveRecommendation(recommendation, request.RunID, items);
-      }
-    } catch (error) {
-      result.AppendError(error.message);
+Abstract base class for implementing recommendation providers.
+
+```mermaid
+classDiagram
+    class RecommendationProviderBase {
+        <<abstract>>
+        -_md : Metadata
+        -_ContextUser : UserInfo
+        +ContextUser : UserInfo
+        +Recommend(request)* RecommendationResult
+        #SaveRecommendation(rec, runID, items) boolean
     }
-    
-    return result;
-  }
-}
+
+    class ConcreteProvider {
+        +Recommend(request) RecommendationResult
+    }
+
+    RecommendationProviderBase <|-- ConcreteProvider
+
+    style RecommendationProviderBase fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style ConcreteProvider fill:#2d8659,stroke:#1a5c3a,color:#fff
 ```
 
-## Usage Examples
+The `SaveRecommendation` helper method handles:
+1. Setting the `RecommendationRunID` on the recommendation entity
+2. Saving the recommendation record
+3. Linking and saving all `RecommendationItemEntity` records
 
-### Generate Recommendations for Specific Records
+### RecommendationRequest\<T\>
 
-```typescript
-import { RecommendationEngineBase, RecommendationRequest } from '@memberjunction/ai-recommendations';
-
-async function getCustomerRecommendations(customerIds: string[]) {
-  // Ensure the engine is configured
-  await RecommendationEngineBase.Instance.Config();
-  
-  // Create a request for specific customer records
-  const request = new RecommendationRequest();
-  request.EntityAndRecordsInfo = {
-    EntityName: 'Customers',
-    RecordIDs: customerIds
-  };
-  
-  // Optionally specify a provider
-  // request.Provider = RecommendationEngineBase.Instance.RecommendationProviders.find(p => p.Name === 'MyProvider');
-  
-  // Execute the recommendation
-  const result = await RecommendationEngineBase.Instance.Recommend(request);
-  
-  if (result.Success) {
-    console.log('Recommendations generated successfully!');
-    return result.RecommendationItems;
-  } else {
-    console.error('Error generating recommendations:', result.ErrorMessage);
-    return null;
-  }
-}
+The request object supports three ways to specify source records:
+
+```mermaid
+graph TD
+    RR["RecommendationRequest"]
+    OPT1["Recommendations[]<br/>Pre-built entities"]
+    OPT2["EntityAndRecordsInfo<br/>Entity name + Record IDs"]
+    OPT3["ListID<br/>MJ List reference"]
+
+    RR --> OPT1
+    RR --> OPT2
+    RR --> OPT3
+
+    style RR fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style OPT1 fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style OPT2 fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style OPT3 fill:#2d8659,stroke:#1a5c3a,color:#fff
 ```
 
-### Generate Recommendations from a List
+| Field | Type | Description |
+|---|---|---|
+| `Recommendations` | `RecommendationEntity[]` | Pre-built unsaved recommendation entities |
+| `EntityAndRecordsInfo` | `{ EntityName, RecordIDs }` | Entity name and array of record IDs to process |
+| `ListID` | `string` | ID of a MJ List whose details become the source records |
+| `Provider` | `RecommendationProviderEntity` | Specific provider to use (defaults to first available) |
+| `CurrentUser` | `UserInfo` | User context |
+| `Options` | `T` | Generic additional options passed to the provider |
+| `CreateErrorList` | `boolean` | Whether to create an error tracking list |
+| `RunID` | `string` | Set automatically by the engine |
+| `ErrorListID` | `string` | Set automatically if error list is created |
+
+### RecommendationResult
 
 ```typescript
-import { RecommendationEngineBase, RecommendationRequest } from '@memberjunction/ai-recommendations';
-
-async function getRecommendationsFromList(listId: string) {
-  await RecommendationEngineBase.Instance.Config();
-  
-  // Create a request for records in a list
-  const request = new RecommendationRequest();
-  request.ListID = listId;
-  request.CreateErrorList = true; // Create a list to track errors
-  
-  // Execute the recommendation
-  const result = await RecommendationEngineBase.Instance.Recommend(request);
-  
-  if (result.Success) {
-    console.log('Recommendations generated successfully!');
-    console.log('Error list ID (if needed):', result.Request.ErrorListID);
-    return result.RecommendationItems;
-  } else {
-    console.error('Error generating recommendations:', result.ErrorMessage);
-    return null;
-  }
+class RecommendationResult {
+    Request: RecommendationRequest;
+    RecommendationRun?: RecommendationRunEntity;
+    RecommendationItems?: RecommendationItemEntity[];
+    Success: boolean;
+    ErrorMessage: string;
+
+    AppendWarning(message: string): void;   // Adds warning without setting Success=false
+    AppendError(message: string): void;     // Adds error and sets Success=false
+    GetErrorMessages(): string[];           // Splits ErrorMessage into array
 }
 ```
 
-### Using Advanced Options
+## Usage
+
+### Running Recommendations from a List
 
 ```typescript
-import { RecommendationEngineBase, RecommendationRequest } from '@memberjunction/ai-recommendations';
+import { RecommendationEngineBase } from '@memberjunction/ai-recommendations';
+import { RecommendationRequest } from '@memberjunction/ai-recommendations';
 
-// Define a custom options interface for your provider
-interface MyProviderOptions {
-  similarityThreshold: number;
-  maxRecommendations: number;
-  includeRatings: boolean;
-}
+const engine = RecommendationEngineBase.Instance;
+await engine.Config(false, contextUser);
+
+const request = new RecommendationRequest();
+request.ListID = 'list-uuid';
+request.CurrentUser = contextUser;
+request.CreateErrorList = true;
 
-async function getCustomizedRecommendations(customerId: string) {
-  await RecommendationEngineBase.Instance.Config();
-  
-  // Create a request with custom options
-  const request = new RecommendationRequest<MyProviderOptions>();
-  request.EntityAndRecordsInfo = {
-    EntityName: 'Customers',
-    RecordIDs: [customerId]
-  };
-  
-  // Add provider-specific options
-  request.Options = {
-    similarityThreshold: 0.75,
-    maxRecommendations: 5,
-    includeRatings: true
-  };
-  
-  // Execute the recommendation
-  return await RecommendationEngineBase.Instance.Recommend(request);
+const result = await engine.Recommend(request);
+
+if (result.Success) {
+    console.log(`Generated ${result.RecommendationItems?.length ?? 0} items`);
+} else {
+    console.error(result.ErrorMessage);
 }
 ```
 
-## Recommendation Flow
+### Running Recommendations by Entity and Record IDs
 
-The recommendation process follows these steps:
+```typescript
+const request = new RecommendationRequest();
+request.EntityAndRecordsInfo = {
+    EntityName: 'Products',
+    RecordIDs: ['id-1', 'id-2', 'id-3']
+};
+request.CurrentUser = contextUser;
 
-1. **Request Creation**: A `RecommendationRequest` is created with entity records or a list
-2. **Run Tracking**: A `RecommendationRun` entity is created to track the process
-3. **Provider Selection**: The appropriate recommendation provider is selected
-4. **Recommendation Generation**: The provider generates recommendations for each requested record
-5. **Result Storage**: Recommendations and items are saved to the database
-6. **Status Update**: The run status is updated (completed or error)
-7. **Result Return**: The `RecommendationResult` is returned to the caller
+const result = await engine.Recommend(request);
+```
 
-## Data Model
+### Implementing a Provider
 
-The recommendation engine works with these key entities:
+```typescript
+import { RecommendationProviderBase } from '@memberjunction/ai-recommendations';
+import { RecommendationRequest, RecommendationResult } from '@memberjunction/ai-recommendations';
+import { RegisterClass } from '@memberjunction/global';
+import { Metadata } from '@memberjunction/core';
+import { RecommendationItemEntity } from '@memberjunction/core-entities';
 
-- **RecommendationProviderEntity**: Configuration for recommendation providers
-- **RecommendationRunEntity**: Tracks each recommendation execution
-- **RecommendationEntity**: Represents a recommendation for a source record
-- **RecommendationItemEntity**: Individual recommendation items (products, content, etc.)
+@RegisterClass(RecommendationProviderBase, 'My Recommendation Provider')
+export class MyProvider extends RecommendationProviderBase {
+    async Recommend(request: RecommendationRequest): Promise<RecommendationResult> {
+        const result = new RecommendationResult(request);
+        const md = new Metadata();
+
+        for (const rec of request.Recommendations) {
+            // Call your recommendation API/algorithm
+            const suggestions = await this.getSuggestions(rec.SourceEntityRecordID);
+
+            const items: RecommendationItemEntity[] = [];
+            for (const suggestion of suggestions) {
+                const item = await md.GetEntityObject<RecommendationItemEntity>(
+                    'Recommendation Items', request.CurrentUser
+                );
+                item.NewRecord();
+                item.DestinationEntityID = suggestion.entityID;
+                item.DestinationEntityRecordID = suggestion.recordID;
+                item.MatchProbability = suggestion.score;
+                items.push(item);
+            }
+
+            await this.SaveRecommendation(rec, request.RunID, items);
+        }
+
+        return result;
+    }
 
-## Provider Implementation
+    private async getSuggestions(recordID: string): Promise<Suggestion[]> {
+        // Your recommendation logic here
+        return [];
+    }
+}
+```
 
-To create a custom recommendation provider:
+## Database Entities
 
-1. Create a class that extends `RecommendationProviderBase`
-2. Implement the `Recommend` method to generate recommendations
-3. Register your provider implementation:
+```mermaid
+erDiagram
+    RECOMMENDATION_PROVIDERS {
+        string ID PK
+        string Name
+        string Description
+    }
 
-```typescript
-// Register your provider with MemberJunction's class factory
-import { MJGlobal } from '@memberjunction/global';
-import { RecommendationProviderBase } from '@memberjunction/ai-recommendations';
+    RECOMMENDATION_RUNS {
+        string ID PK
+        string RecommendationProviderID FK
+        string RunByUserID FK
+        datetime StartDate
+        string Status
+        string Description
+    }
 
-MJGlobal.Instance.ClassFactory.RegisterClass(
-  RecommendationProviderBase,
-  'MyRecommendationProvider',
-  MyRecommendationProvider
-);
-```
+    RECOMMENDATIONS {
+        string ID PK
+        string RecommendationRunID FK
+        string SourceEntityID FK
+        string SourceEntityRecordID
+    }
 
-## Integration with MemberJunction
+    RECOMMENDATION_ITEMS {
+        string ID PK
+        string RecommendationID FK
+        string DestinationEntityID FK
+        string DestinationEntityRecordID
+        float MatchProbability
+    }
 
-This package integrates with the MemberJunction ecosystem:
+    LISTS {
+        string ID PK
+        string Name
+        string EntityID FK
+        string UserID FK
+    }
 
-- Uses MemberJunction entities for data storage and retrieval
-- Works with MemberJunction lists for batch processing
-- Leverages MemberJunction's metadata system
+    RECOMMENDATION_PROVIDERS ||--o{ RECOMMENDATION_RUNS : has
+    RECOMMENDATION_RUNS ||--o{ RECOMMENDATIONS : contains
+    RECOMMENDATIONS ||--o{ RECOMMENDATION_ITEMS : produces
+```
 
 ## Dependencies
 
-- `@memberjunction/global`: MemberJunction global utilities
-- `@memberjunction/core`: MemberJunction core library
-- `@memberjunction/core-entities`: MemberJunction entity definitions
-- `@memberjunction/ai`: MemberJunction AI abstractions
+| Package | Purpose |
+|---|---|
+| `@memberjunction/core` | `BaseEngine`, `Metadata`, `RunView`, `UserInfo`, `LogStatus` |
+| `@memberjunction/core-entities` | `RecommendationEntity`, `RecommendationRunEntity`, `RecommendationItemEntity`, `RecommendationProviderEntity`, `ListEntity` |
+| `@memberjunction/global` | `MJGlobal` class factory for provider discovery |
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Development mode
+npm run start
+```
 
 ## License
 
-ISC
+ISC