@memberjunction/ai-recommendations 3.4.0 → 4.1.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/dist/Engine.d.ts

@@ -1,6 +1,6 @@
 import { BaseEngine, UserInfo, IMetadataProvider } from '@memberjunction/core';
 import { RecommendationProviderEntity } from '@memberjunction/core-entities';
-import { RecommendationRequest, RecommendationResult } from './generic/types';
+import { RecommendationRequest, RecommendationResult } from './generic/types.js';
 /**
  * Engine class to be used for running all recommendation requests
  */

package/dist/Engine.js

@@ -1,13 +1,10 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecommendationEngineBase = void 0;
-const core_1 = require("@memberjunction/core");
-const global_1 = require("@memberjunction/global");
-const ProviderBase_1 = require("./ProviderBase");
+import { BaseEngine, Metadata, LogStatus, RunView, LogError } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+import { RecommendationProviderBase } from './ProviderBase.js';
 /**
  * Engine class to be used for running all recommendation requests
  */
-class RecommendationEngineBase extends core_1.BaseEngine {
+export class RecommendationEngineBase extends BaseEngine {
     constructor() {
         super(...arguments);
         this._RecommendationProviders = [];
@@ -39,14 +36,14 @@ class RecommendationEngineBase extends core_1.BaseEngine {
                 provider = this.RecommendationProviders[0];
             }
         }
-        (0, core_1.LogStatus)(`Recommendation Engine is using provider: ${provider.Name}`);
+        LogStatus(`Recommendation Engine is using provider: ${provider.Name}`);
         // get the driver
-        const driver = global_1.MJGlobal.Instance.ClassFactory.CreateInstance(ProviderBase_1.RecommendationProviderBase, provider.Name);
+        const driver = MJGlobal.Instance.ClassFactory.CreateInstance(RecommendationProviderBase, provider.Name);
         if (!driver) {
             throw new Error(`Could not find driver for provider: ${provider.Name}`);
         }
         const recommendations = await this.GetRecommendationEntities(request);
-        (0, core_1.LogStatus)(`Processing ${recommendations.length} recommendations`);
+        LogStatus(`Processing ${recommendations.length} recommendations`);
         if (recommendations.length == 0) {
             return {
                 Success: true,
@@ -55,7 +52,7 @@ class RecommendationEngineBase extends core_1.BaseEngine {
         }
         request.Recommendations = recommendations;
         // load the run
-        const recommendationRunEntity = await new core_1.Metadata().GetEntityObject('Recommendation Runs', request.CurrentUser);
+        const recommendationRunEntity = await new Metadata().GetEntityObject('Recommendation Runs', request.CurrentUser);
         recommendationRunEntity.NewRecord();
         // update status for current run
         recommendationRunEntity.Status = 'In Progress';
@@ -64,7 +61,7 @@ class RecommendationEngineBase extends core_1.BaseEngine {
         recommendationRunEntity.RunByUserID = request.CurrentUser ? request.CurrentUser.ID : super.ContextUser.ID;
         const saveResult = await recommendationRunEntity.Save();
         if (!saveResult) {
-            (0, core_1.LogStatus)(`Error saving RecommendationRun entity: `, undefined, recommendationRunEntity.LatestResult);
+            LogStatus(`Error saving RecommendationRun entity: `, undefined, recommendationRunEntity.LatestResult);
             throw new Error('Error creating Recommendation Run entity');
         }
         if (request.CreateErrorList) {
@@ -79,7 +76,7 @@ class RecommendationEngineBase extends core_1.BaseEngine {
         recommendationRunEntity.Description = recommendResult.ErrorMessage;
         const postRunSaveResult = await recommendationRunEntity.Save();
         if (!postRunSaveResult) {
-            (0, core_1.LogStatus)(`Error saving RecommendationRun entity: `, undefined, recommendationRunEntity.LatestResult);
+            LogStatus(`Error saving RecommendationRun entity: `, undefined, recommendationRunEntity.LatestResult);
             throw new Error('Error updating Recommendation Run entity');
         }
         return recommendResult;
@@ -108,8 +105,8 @@ class RecommendationEngineBase extends core_1.BaseEngine {
         }
     }
     async GetRecommendationsByListID(listID, currentUser) {
-        const rv = new core_1.RunView();
-        const md = new core_1.Metadata();
+        const rv = new RunView();
+        const md = new Metadata();
         const rvListDetailsResult = await rv.RunViews([
             {
                 EntityName: 'Lists',
@@ -132,7 +129,7 @@ class RecommendationEngineBase extends core_1.BaseEngine {
         }
         const list = listViewResult.Results[0];
         const entityName = list.Entity;
-        (0, core_1.LogStatus)(`Getting recommendations for list: ${list.Name}. Entity: ${entityName}`);
+        LogStatus(`Getting recommendations for list: ${list.Name}. Entity: ${entityName}`);
         const entityID = list.EntityID;
         const entity = md.Entities.find((e) => e.ID == entityID);
         const needsQuotes = entity.FirstPrimaryKey.NeedsQuotes ? "'" : '';
@@ -164,13 +161,13 @@ class RecommendationEngineBase extends core_1.BaseEngine {
         return recommendations;
     }
     async GetRecommendationsByRecordIDs(entityName, recordIDs, currentUser) {
-        const md = new core_1.Metadata();
-        const rv = new core_1.RunView();
+        const md = new Metadata();
+        const rv = new RunView();
         const entity = md.Entities.find((e) => e.Name.toLowerCase() == entityName.toLowerCase());
         if (!entity) {
             throw new Error(`Unable to get recommendations by entity info: Entity not found with name: ${entityName}`);
         }
-        (0, core_1.LogStatus)(`Getting recommendations for entity: ${entityName}`);
+        LogStatus(`Getting recommendations for entity: ${entityName}`);
         const needsQuotes = entity.FirstPrimaryKey.NeedsQuotes ? "'" : '';
         const recordIDsFilter = recordIDs.map((id) => `${needsQuotes}${id}${needsQuotes}`).join(',');
         const rvEntityResult = await rv.RunView({
@@ -191,18 +188,18 @@ class RecommendationEngineBase extends core_1.BaseEngine {
         return recommendations;
     }
     async CreateRecommendationErrorList(recommendationRunID, entityID, currentUser) {
-        const md = new core_1.Metadata();
+        const md = new Metadata();
         const list = await md.GetEntityObject('Lists', currentUser);
         list.Name = `Recommendation Run ${recommendationRunID} Errors`;
         list.EntityID = entityID;
         list.UserID = currentUser ? currentUser.ID : super.ContextUser.ID;
         const saveResult = await list.Save();
         if (!saveResult) {
-            (0, core_1.LogError)(`Error saving Recommendation Error List entity: `, undefined, list.LatestResult);
+            LogError(`Error saving Recommendation Error List entity: `, undefined, list.LatestResult);
             return null;
         }
         else {
-            (0, core_1.LogStatus)(`Error list created for recommendation run: ${recommendationRunID}. List ID: ${list.ID}`);
+            LogStatus(`Error list created for recommendation run: ${recommendationRunID}. List ID: ${list.ID}`);
         }
         return list;
     }
@@ -210,5 +207,4 @@ class RecommendationEngineBase extends core_1.BaseEngine {
         return value === null || value === undefined;
     }
 }
-exports.RecommendationEngineBase = RecommendationEngineBase;
 //# sourceMappingURL=Engine.js.map

package/dist/Engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"Engine.js","sourceRoot":"","sources":["../src/Engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Engine.js","sourceRoot":"","sources":["../src/Engine.ts"],"names":[],"mappings":"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"}

package/dist/ProviderBase.d.ts

@@ -1,6 +1,6 @@
 import { RecommendationEntity, RecommendationItemEntity } from '@memberjunction/core-entities';
 import { UserInfo } from '@memberjunction/core';
-import { RecommendationRequest, RecommendationResult } from './generic/types';
+import { RecommendationRequest, RecommendationResult } from './generic/types.js';
 /**
  * Base class for all recommendation providers
  */

package/dist/ProviderBase.js

@@ -1,14 +1,11 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecommendationProviderBase = void 0;
-const core_1 = require("@memberjunction/core");
+import { LogError, Metadata } from '@memberjunction/core';
 /**
  * Base class for all recommendation providers
  */
-class RecommendationProviderBase {
+export class RecommendationProviderBase {
     constructor(ContextUser) {
         this._ContextUser = ContextUser;
-        this._md = new core_1.Metadata();
+        this._md = new Metadata();
     }
     get ContextUser() {
         return this._ContextUser;
@@ -23,7 +20,7 @@ class RecommendationProviderBase {
         recommendation.RecommendationRunID = RunID;
         const recommendationSaveResult = await recommendation.Save();
         if (!recommendationSaveResult) {
-            (0, core_1.LogError)(`Error saving recommendation for ${recommendation.ID}`, undefined, recommendation.LatestResult);
+            LogError(`Error saving recommendation for ${recommendation.ID}`, undefined, recommendation.LatestResult);
             return false;
         }
         let allSaved = true;
@@ -31,12 +28,11 @@ class RecommendationProviderBase {
             item.RecommendationID = recommendation.ID;
             const saveResult = await item.Save();
             if (!saveResult) {
-                (0, core_1.LogError)(`Error saving recommendation item for recommendation ${recommendation.ID}`, undefined, item.LatestResult);
+                LogError(`Error saving recommendation item for recommendation ${recommendation.ID}`, undefined, item.LatestResult);
                 allSaved = false;
             }
         }
         return allSaved;
     }
 }
-exports.RecommendationProviderBase = RecommendationProviderBase;
 //# sourceMappingURL=ProviderBase.js.map

package/dist/ProviderBase.js.map

@@ -1 +1 @@
-{"version":3,"file":"ProviderBase.js","sourceRoot":"","sources":["../src/ProviderBase.ts"],"names":[],"mappings":";;;AACA,+CAAoE;AAGpE;;GAEG;AACH,MAAsB,0BAA0B;IAI9C,YAAmB,WAAqB;QACtC,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAChC,IAAI,CAAC,GAAG,GAAG,IAAI,eAAQ,EAAE,CAAC;IAC5B,CAAC;IAED,IAAW,WAAW;QACpB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAUD;;;;;OAKG;IACO,KAAK,CAAC,kBAAkB,CAAC,cAAoC,EAAE,KAAa,EAAE,KAAiC;QACvH,cAAc,CAAC,mBAAmB,GAAG,KAAK,CAAC;QAC3C,MAAM,wBAAwB,GAAY,MAAM,cAAc,CAAC,IAAI,EAAE,CAAC;QACtE,IAAG,CAAC,wBAAwB,EAAE,CAAC;YAC7B,IAAA,eAAQ,EAAC,mCAAmC,cAAc,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;YACzG,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,QAAQ,GAAY,IAAI,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,gBAAgB,GAAG,cAAc,CAAC,EAAE,CAAC;YAC1C,MAAM,UAAU,GAAY,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAG,CAAC,UAAU,EAAE,CAAC;gBACf,IAAA,eAAQ,EAAC,uDAAuD,cAAc,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;gBACnH,QAAQ,GAAG,KAAK,CAAC;YACnB,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF;AA/CD,gEA+CC"}
+{"version":3,"file":"ProviderBase.js","sourceRoot":"","sources":["../src/ProviderBase.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAGpE;;GAEG;AACH,MAAM,OAAgB,0BAA0B;IAI9C,YAAmB,WAAqB;QACtC,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC;QAChC,IAAI,CAAC,GAAG,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAED,IAAW,WAAW;QACpB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAUD;;;;;OAKG;IACO,KAAK,CAAC,kBAAkB,CAAC,cAAoC,EAAE,KAAa,EAAE,KAAiC;QACvH,cAAc,CAAC,mBAAmB,GAAG,KAAK,CAAC;QAC3C,MAAM,wBAAwB,GAAY,MAAM,cAAc,CAAC,IAAI,EAAE,CAAC;QACtE,IAAG,CAAC,wBAAwB,EAAE,CAAC;YAC7B,QAAQ,CAAC,mCAAmC,cAAc,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,cAAc,CAAC,YAAY,CAAC,CAAC;YACzG,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,QAAQ,GAAY,IAAI,CAAC;QAC7B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,gBAAgB,GAAG,cAAc,CAAC,EAAE,CAAC;YAC1C,MAAM,UAAU,GAAY,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;YAC9C,IAAG,CAAC,UAAU,EAAE,CAAC;gBACf,QAAQ,CAAC,uDAAuD,cAAc,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;gBACnH,QAAQ,GAAG,KAAK,CAAC;YACnB,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/generic/types.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RecommendationResult = exports.RecommendationRequest = void 0;
 /**
  * Used to make requests to Recommendation providers
  */
-class RecommendationRequest {
+export class RecommendationRequest {
     constructor() {
         /**
          * Array of the requested recommendations. When preparing a batch of recommendations to request, do NOT set the RecommendationRunID or attempt
@@ -14,11 +11,10 @@ class RecommendationRequest {
         this.Recommendations = [];
     }
 }
-exports.RecommendationRequest = RecommendationRequest;
 /**
  * This response is generated for each Recommend() request
  */
-class RecommendationResult {
+export class RecommendationResult {
     constructor(request) {
         /**
          * The Recommendation Item Entities that were created by the recommendation provider
@@ -54,5 +50,4 @@ class RecommendationResult {
         return this.ErrorMessage.split('\n');
     }
 }
-exports.RecommendationResult = RecommendationResult;
 //# sourceMappingURL=types.js.map

package/dist/generic/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/generic/types.ts"],"names":[],"mappings":";;;AAGA;;GAEG;AACH,MAAa,qBAAqB;IAAlC;QAQI;;;;WAIG;QACH,oBAAe,GAA4B,EAAE,CAAC;IA6ClD,CAAC;CAAA;AA1DD,sDA0DC;AAED;;GAEG;AACH,MAAa,oBAAoB;IAa7B,YAAY,OAA8B;QAP1C;;WAEG;QACH,wBAAmB,GAAgC,EAAE,CAAC;QAKlD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,cAAsB;QAChC,IAAI,CAAC,YAAY,IAAI,YAAY,cAAc,KAAK,CAAC;IACzD,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,YAAoB;QAC5B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,YAAY,IAAI,UAAU,YAAY,KAAK,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACZ,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;CACJ;AA9CD,oDA8CC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/generic/types.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,OAAO,qBAAqB;IAAlC;QAQI;;;;WAIG;QACH,oBAAe,GAA4B,EAAE,CAAC;IA6ClD,CAAC;CAAA;AAED;;GAEG;AACH,MAAM,OAAO,oBAAoB;IAa7B,YAAY,OAA8B;QAP1C;;WAEG;QACH,wBAAmB,GAAgC,EAAE,CAAC;QAKlD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,YAAY,GAAG,EAAE,CAAC;IAC3B,CAAC;IAED;;;;OAIG;IACH,aAAa,CAAC,cAAsB;QAChC,IAAI,CAAC,YAAY,IAAI,YAAY,cAAc,KAAK,CAAC;IACzD,CAAC;IAED;;;;OAIG;IACH,WAAW,CAAC,YAAoB;QAC5B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,IAAI,CAAC,YAAY,IAAI,UAAU,YAAY,KAAK,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACZ,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;CACJ"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export * from './Engine';
-export * from './ProviderBase';
-export * from './generic/types';
+export * from './Engine.js';
+export * from './ProviderBase.js';
+export * from './generic/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,20 +1,4 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./Engine"), exports);
-__exportStar(require("./ProviderBase"), exports);
-__exportStar(require("./generic/types"), exports);
+export * from './Engine.js';
+export * from './ProviderBase.js';
+export * from './generic/types.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2CAAyB;AACzB,iDAA+B;AAC/B,kDAAgC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@memberjunction/ai-recommendations",
-  "version": "3.4.0",
+  "type": "module",
+  "version": "4.1.0",
   "description": "MemberJunction Recommendations Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,20 +10,20 @@
   ],
   "scripts": {
     "start": "ts-node-dev src/index.ts",
-    "build": "tsc",
+    "build": "tsc && tsc-alias -f",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "author": "MemberJunction.com",
   "license": "ISC",
   "devDependencies": {
     "ts-node-dev": "^2.0.0",
-    "typescript": "^5.4.5"
+    "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@memberjunction/global": "3.4.0",
-    "@memberjunction/core": "3.4.0",
-    "@memberjunction/core-entities": "3.4.0",
-    "@memberjunction/ai": "3.4.0"
+    "@memberjunction/global": "4.1.0",
+    "@memberjunction/core": "4.1.0",
+    "@memberjunction/core-entities": "4.1.0",
+    "@memberjunction/ai": "4.1.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