@memberjunction/content-autotagging 6.2.0-edge.0 → 6.2.0-edge.2

package/dist/Engine/generic/AutotagBaseEngine.js

@@ -21,7 +21,7 @@ import * as cheerio from 'cheerio';
 import crypto from 'crypto';
 import { BaseEmbeddings, GetAIAPIKey } from '@memberjunction/ai';
 import { AIEngine } from '@memberjunction/aiengine';
-import { AIPromptRunner, AIModelRunner } from '@memberjunction/ai-prompts';
+import { AIPromptRunner, AIEmbeddingRunner } from '@memberjunction/ai-prompts';
 import { AIPromptParams } from '@memberjunction/ai-core-plus';
 import { FIXED_WINDOW_SEGMENTER_KEY, ResolveSegmenter, } from '@memberjunction/ai-segmentation';
 import { VectorDBBase } from '@memberjunction/ai-vectordb';
@@ -55,8 +55,8 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
     constructor() {
         super(...arguments);
         // Cached metadata unique to this engine — loaded by BaseEngine.Config()
-        this._ContentTypeAttributes = [];
-        this._ContentSourceTypeParams = [];
+        this._contentTypeAttributes = [];
+        this._contentSourceTypeParams = [];
         /**
          * Optional taxonomy JSON string to inject into the autotagging prompt.
          * Set by the caller (e.g., AutotagEntity) before calling ExtractTextAndProcessWithLLM.
@@ -120,9 +120,9 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
     /** All content file types — delegated to KnowledgeHubMetadataEngine */
     get ContentFileTypes() { return this.khEngine.ContentFileTypes; }
     /** All content type attributes, cached at startup */
-    get ContentTypeAttributes() { return this._ContentTypeAttributes; }
+    get ContentTypeAttributes() { return this._contentTypeAttributes; }
     /** All content source type params, cached at startup */
-    get ContentSourceTypeParams() { return this._ContentSourceTypeParams; }
+    get ContentSourceTypeParams() { return this._contentSourceTypeParams; }
     async Config(forceRefresh, contextUser, provider) {
         // Content Types, Content Source Types, and Content File Types are delegated to
         // KnowledgeHubMetadataEngine (avoid redundant loading). Only cache entities unique to this engine.
@@ -131,12 +131,12 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             {
                 Type: 'entity',
                 EntityName: 'MJ: Content Type Attributes',
-                PropertyName: '_ContentTypeAttributes',
+                PropertyName: '_contentTypeAttributes',
             },
             {
                 Type: 'entity',
                 EntityName: 'MJ: Content Source Type Params',
-                PropertyName: '_ContentSourceTypeParams',
+                PropertyName: '_contentSourceTypeParams',
             },
         ];
         await this.Load(configs, provider, forceRefresh, contextUser);
@@ -231,6 +231,9 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             buffer = [];
             batchNum++;
             anyItemsProcessed = true;
+            // The source's classification config and the type's model / tag limits are read from the
+            // KnowledgeHub cache per item; catch a source or type created after it loaded.
+            await this.ensureItemMetadataCached(batch, contextUser);
             // Rate limit before each batch of parallel LLM calls.
             await this.LLMRateLimiter.Acquire();
             let batchOk = 0;
@@ -317,7 +320,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             processRunParams.startTime = new Date();
             processRunParams.endTime = new Date();
             processRunParams.numItemsProcessed = totalProcessed - resumeOffset;
-            await this.saveProcessRun(processRunParams, contextUser);
+            await this.SaveProcessRun(processRunParams, contextUser);
         }
     }
     /**
@@ -345,8 +348,8 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         // A8: Update tagging status to Processing
         await this.updateContentItemTaggingStatus(params.contentItemID, 'Processing', contextUser);
         try {
-            const LLMResults = await this.promptAndRetrieveResultsFromLLM(params, contextUser);
-            await this.saveLLMResults(LLMResults, contextUser);
+            const LLMResults = await this.PromptAndRetrieveResultsFromLLM(params, contextUser);
+            await this.SaveLLMResults(LLMResults, contextUser);
             // A8: Update tagging status to Complete
             await this.updateContentItemTaggingStatus(params.contentItemID, 'Complete', contextUser);
         }
@@ -445,7 +448,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             }
             // Set up the bridge callback — fires after each ContentItemTag is saved
             this.OnContentItemTagSaved = async (contentItemTag, parentTagName, ctxUser) => {
-                await this.BridgeContentItemTagToTaxonomy(contentItemTag, parentTagName, ctxUser);
+                await this.bridgeContentItemTagToTaxonomy(contentItemTag, parentTagName, ctxUser);
             };
             LogStatus(`[TaxonomyBridge] Bridge callback installed`);
         }
@@ -509,7 +512,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
      * - For Entity sources: tags the original entity record (e.g., Products row)
      * - For non-Entity sources (RSS, Website, etc.): tags the ContentItem itself
      */
-    async BridgeContentItemTagToTaxonomy(contentItemTag, parentTagName, contextUser) {
+    async bridgeContentItemTagToTaxonomy(contentItemTag, parentTagName, contextUser) {
         try {
             // If the LLM suggested a parent tag, resolve it first (through the same
             // mutex, to prevent duplicate parents under concurrent batch processing)
@@ -673,14 +676,14 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         // extension keys ride along in the same JSON and are surfaced via the extended interface.
         return source.ConfigurationObject ?? null;
     }
-    async promptAndRetrieveResultsFromLLM(params, contextUser) {
+    async PromptAndRetrieveResultsFromLLM(params, contextUser) {
         await AIEngine.Instance.Config(false, contextUser);
         // Resolve the effective classification context once per item (async lookup);
         // buildPromptData reads it from params for each chunk.
         params.classificationContext = await this.resolveClassificationContext(params, contextUser);
         const prompt = this.getAutotagPrompt();
         const tokenLimit = this.resolveTokenLimit(params.modelID);
-        const chunks = await this.chunkExtractedText(params.text, tokenLimit);
+        const chunks = await this.ChunkExtractedText(params.text, tokenLimit);
         if (chunks.length === 0 || (chunks.length === 1 && (!chunks[0] || chunks[0].trim().length === 0))) {
             LogError(`[Autotag] No text to process for item ${params.contentItemID}`);
             return {};
@@ -689,7 +692,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         const startTime = new Date();
         for (let ci = 0; ci < chunks.length; ci++) {
             try {
-                LLMResults = await this.processChunkWithPromptRunner(prompt, params, chunks[ci], LLMResults, contextUser);
+                LLMResults = await this.ProcessChunkWithPromptRunner(prompt, params, chunks[ci], LLMResults, contextUser);
             }
             catch (chunkError) {
                 LogError(`[Autotag] Chunk ${ci + 1}/${chunks.length} failed for item ${params.contentItemID}: ${chunkError instanceof Error ? chunkError.message : String(chunkError)}`);
@@ -700,6 +703,10 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         LLMResults.contentItemID = params.contentItemID;
         return LLMResults;
     }
+    /** @deprecated Use {@link PromptAndRetrieveResultsFromLLM}. */
+    async promptAndRetrieveResultsFromLLM(params, contextUser) {
+        return this.PromptAndRetrieveResultsFromLLM(params, contextUser);
+    }
     /**
      * Resolves the input token limit for chunking. Uses the model specified by modelID if available,
      * otherwise falls back to a conservative default.
@@ -719,7 +726,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
      * Uses the prompt's configured model by default. If ContentType.AIModelID is set,
      * it is passed as a runtime model override via AIPromptParams.override.
      */
-    async processChunkWithPromptRunner(prompt, params, chunk, LLMResults, contextUser) {
+    async ProcessChunkWithPromptRunner(prompt, params, chunk, LLMResults, contextUser) {
         const promptParams = new AIPromptParams();
         promptParams.prompt = prompt;
         promptParams.contextUser = contextUser;
@@ -770,25 +777,37 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         }
         return LLMResults;
     }
-    async saveLLMResults(LLMResults, contextUser) {
+    /** @deprecated Use {@link ProcessChunkWithPromptRunner}. */
+    async processChunkWithPromptRunner(prompt, params, chunk, LLMResults, contextUser) {
+        return this.ProcessChunkWithPromptRunner(prompt, params, chunk, LLMResults, contextUser);
+    }
+    async SaveLLMResults(LLMResults, contextUser) {
         if (LLMResults.isValidContent === true) {
-            await this.saveResultsToContentItemAttribute(LLMResults, contextUser);
-            await this.saveContentItemTags(LLMResults.contentItemID, LLMResults, contextUser);
+            await this.SaveResultsToContentItemAttribute(LLMResults, contextUser);
+            await this.SaveContentItemTags(LLMResults.contentItemID, LLMResults, contextUser);
         }
         else if (LLMResults.isValidContent === false) {
             LogStatus(`[Autotag] LLM judged content item ${LLMResults.contentItemID} INVALID — deleting it. Title: ${String(LLMResults.title ?? '')} | Reason/description: ${String(LLMResults.description ?? LLMResults.reason ?? '')}`.slice(0, 600));
-            await this.deleteInvalidContentItem(LLMResults.contentItemID, contextUser);
+            await this.DeleteInvalidContentItem(LLMResults.contentItemID, contextUser);
         }
         else {
             LogError(`[Autotag] Unexpected LLM format for item ${LLMResults.contentItemID} — isValidContent missing. Keys: ${Object.keys(LLMResults).join(', ')}`);
         }
     }
-    async deleteInvalidContentItem(contentItemID, contextUser) {
+    /** @deprecated Use {@link SaveLLMResults}. */
+    async saveLLMResults(LLMResults, contextUser) {
+        return this.SaveLLMResults(LLMResults, contextUser);
+    }
+    async DeleteInvalidContentItem(contentItemID, contextUser) {
         const md = this.ProviderToUse;
         const contentItem = await md.GetEntityObject('MJ: Content Items', contextUser);
         await contentItem.Load(contentItemID);
         await contentItem.Delete();
     }
+    /** @deprecated Use {@link DeleteInvalidContentItem}. */
+    async deleteInvalidContentItem(contentItemID, contextUser) {
+        return this.DeleteInvalidContentItem(contentItemID, contextUser);
+    }
     /**
      * Registration key of the segmentation strategy this engine uses.
      *
@@ -827,7 +846,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
      * ({@link MAX_EMBEDDING_TOKENS}) — these two chunk sites feed different consumers and
      * must not be collapsed into one call. Tagging chunks are transient and never persisted.
      */
-    async chunkExtractedText(text, tokenLimit) {
+    async ChunkExtractedText(text, tokenLimit) {
         try {
             const maxChunkTokens = Math.ceil(tokenLimit / 1.5);
             // Short-circuit: text that already fits is passed through verbatim, preserving its
@@ -847,6 +866,10 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             return [text];
         }
     }
+    /** @deprecated Use {@link ChunkExtractedText}. */
+    async chunkExtractedText(text, tokenLimit) {
+        return this.ChunkExtractedText(text, tokenLimit);
+    }
     /**
      * Simple character-based chunking as fallback
      */
@@ -867,7 +890,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
      * After each tag is saved, invokes the OnContentItemTagSaved callback (if set)
      * for taxonomy bridge processing.
      */
-    async saveContentItemTags(contentItemID, LLMResults, contextUser) {
+    async SaveContentItemTags(contentItemID, LLMResults, contextUser) {
         const md = this.ProviderToUse;
         const keywords = LLMResults.keywords;
         if (!keywords || !Array.isArray(keywords))
@@ -926,11 +949,15 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             }));
         }
     }
+    /** @deprecated Use {@link SaveContentItemTags}. */
+    async saveContentItemTags(contentItemID, LLMResults, contextUser) {
+        return this.SaveContentItemTags(contentItemID, LLMResults, contextUser);
+    }
     /**
      * Saves LLM-extracted attributes to the database.
      * Updates content item name/description, then creates attribute records for other fields.
      */
-    async saveResultsToContentItemAttribute(LLMResults, contextUser) {
+    async SaveResultsToContentItemAttribute(LLMResults, contextUser) {
         const md = this.ProviderToUse;
         const contentItemID = LLMResults.contentItemID;
         const skipKeys = new Set(['keywords', 'processStartTime', 'processEndTime', 'contentItemID', 'isValidContent', AutotagBaseEngine_1.AI_PROMPT_RUN_ID_KEY]);
@@ -964,17 +991,25 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             }));
         }
     }
+    /** @deprecated Use {@link SaveResultsToContentItemAttribute}. */
+    async saveResultsToContentItemAttribute(LLMResults, contextUser) {
+        return this.SaveResultsToContentItemAttribute(LLMResults, contextUser);
+    }
     /**
      * Retrieves all content sources for a given content source type.
      * Throws if no sources are found.
      */
-    async getAllContentSources(contextUser, contentSourceTypeID) {
+    async GetAllContentSources(contextUser, contentSourceTypeID) {
         const sources = await this.GetAllContentSourcesSafe(contextUser, contentSourceTypeID);
         if (sources.length === 0) {
             throw new Error(`No content sources found for content source type with ID '${contentSourceTypeID}'`);
         }
         return sources;
     }
+    /** @deprecated Use {@link GetAllContentSources}. */
+    async getAllContentSources(contextUser, contentSourceTypeID) {
+        return this.GetAllContentSources(contextUser, contentSourceTypeID);
+    }
     /**
      * Retrieves all content sources for a given content source type.
      * Returns an empty array (instead of throwing) when no sources are configured.
@@ -989,7 +1024,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         }
         return sourceType.ID;
     }
-    async getContentSourceParams(contentSource, contextUser) {
+    async GetContentSourceParams(contentSource, contextUser) {
         const contentSourceParams = new Map();
         const rv = new RunView();
         const results = await rv.RunView({
@@ -1002,7 +1037,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
                 const params = this.GetDefaultContentSourceTypeParams(contentSourceParam.ContentSourceTypeParamID);
                 params.contentSourceID = contentSource.ID;
                 if (contentSourceParam.Value) {
-                    params.value = this.castValueAsCorrectType(contentSourceParam.Value, params.type);
+                    params.value = this.CastValueAsCorrectType(contentSourceParam.Value, params.type);
                 }
                 contentSourceParams.set(params.name, params.value);
             }
@@ -1012,50 +1047,70 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         }
         return contentSourceParams;
     }
+    /** @deprecated Use {@link GetContentSourceParams}. */
+    async getContentSourceParams(contentSource, contextUser) {
+        return this.GetContentSourceParams(contentSource, contextUser);
+    }
     GetDefaultContentSourceTypeParams(contentSourceTypeParamID) {
-        const result = this._ContentSourceTypeParams.find(p => UUIDsEqual(p.ID, contentSourceTypeParamID));
+        const result = this._contentSourceTypeParams.find(p => UUIDsEqual(p.ID, contentSourceTypeParamID));
         if (!result) {
             throw new Error(`Content Source Type Param with ID '${contentSourceTypeParamID}' not found in cached metadata`);
         }
         const params = new ContentSourceTypeParams();
         params.name = result.Name;
         params.type = result.Type.toLowerCase();
-        params.value = this.castValueAsCorrectType(result.DefaultValue ?? '', params.type);
+        params.value = this.CastValueAsCorrectType(result.DefaultValue ?? '', params.type);
         return params;
     }
-    castValueAsCorrectType(value, type) {
+    CastValueAsCorrectType(value, type) {
         switch (type) {
             case 'number':
                 return parseInt(value, 10);
             case 'boolean':
-                return this.stringToBoolean(value);
+                return this.StringToBoolean(value);
             case 'string':
                 return value;
             case 'string[]':
-                return this.parseStringArray(value);
+                return this.ParseStringArray(value);
             case 'regexp':
                 return new RegExp(value.replace(/\\\\/g, '\\'));
             default:
                 return value;
         }
     }
-    stringToBoolean(str) {
+    /** @deprecated Use {@link CastValueAsCorrectType}. */
+    castValueAsCorrectType(value, type) {
+        return this.CastValueAsCorrectType(value, type);
+    }
+    StringToBoolean(str) {
         return str === 'true';
     }
-    parseStringArray(value) {
+    /** @deprecated Use {@link StringToBoolean}. */
+    stringToBoolean(str) {
+        return this.StringToBoolean(str);
+    }
+    ParseStringArray(value) {
         return JSON.parse(value);
     }
+    /** @deprecated Use {@link ParseStringArray}. */
+    parseStringArray(value) {
+        return this.ParseStringArray(value);
+    }
     /**
      * Converts a run date to the user's local timezone.
      */
-    async convertLastRunDateToTimezone(lastRunDate) {
+    async ConvertLastRunDateToTimezone(lastRunDate) {
         const userTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
         return toZonedTime(lastRunDate, userTimeZone);
     }
+    /** @deprecated Use {@link ConvertLastRunDateToTimezone}. */
+    async convertLastRunDateToTimezone(lastRunDate) {
+        return this.ConvertLastRunDateToTimezone(lastRunDate);
+    }
     /**
      * Retrieves the last run date for a content source. Returns epoch date if no runs exist.
      */
-    async getContentSourceLastRunDate(contentSourceID, contextUser) {
+    async GetContentSourceLastRunDate(contentSourceID, contextUser) {
         const rv = new RunView();
         // Exclude 'Running' status to avoid using the current in-progress run's
         // start time as the cutoff — that would cause the provider to skip all records.
@@ -1067,13 +1122,17 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         }, contextUser);
         if (results.Success && results.Results.length) {
             const lastRunDate = results.Results[0].__mj_CreatedAt;
-            return this.convertLastRunDateToTimezone(lastRunDate);
+            return this.ConvertLastRunDateToTimezone(lastRunDate);
         }
         if (results.Success) {
             return new Date(0);
         }
         throw new Error(`Failed to retrieve last run date for content source with ID ${contentSourceID}`);
     }
+    /** @deprecated Use {@link GetContentSourceLastRunDate}. */
+    async getContentSourceLastRunDate(contentSourceID, contextUser) {
+        return this.GetContentSourceLastRunDate(contentSourceID, contextUser);
+    }
     GetContentItemParams(contentTypeID) {
         const contentType = this.khEngine.GetContentTypeByID(contentTypeID);
         if (!contentType) {
@@ -1107,7 +1166,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         return fileType.Name;
     }
     GetAdditionalContentTypePrompt(contentTypeID) {
-        const attrs = this._ContentTypeAttributes.filter(a => UUIDsEqual(a.ContentTypeID, contentTypeID));
+        const attrs = this._contentTypeAttributes.filter(a => UUIDsEqual(a.ContentTypeID, contentTypeID));
         if (attrs.length === 0)
             return '';
         return attrs.map(attr => `${attr.Prompt}. The data must be included in the above described JSON file in this key-value format:     { "${attr.Name}": (value of ${attr.Name} here)}`).join('\n');
@@ -1118,15 +1177,23 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         const sourceTypeName = this.GetContentSourceTypeName(contentSourceParams.ContentSourceTypeID);
         return `${contentTypeName} in ${fileTypeName} format obtained from a ${sourceTypeName} source`;
     }
-    async getChecksumFromURL(url) {
+    async GetChecksumFromURL(url) {
         const response = await HttpGet(url, { ResponseType: 'text' });
         const content = String(response.Data);
         return crypto.createHash('sha256').update(content).digest('hex');
     }
-    async getChecksumFromText(text) {
+    /** @deprecated Use {@link GetChecksumFromURL}. */
+    async getChecksumFromURL(url) {
+        return this.GetChecksumFromURL(url);
+    }
+    async GetChecksumFromText(text) {
         return crypto.createHash('sha256').update(text).digest('hex');
     }
-    async getContentItemIDFromURL(contentSourceParams, contextUser) {
+    /** @deprecated Use {@link GetChecksumFromText}. */
+    async getChecksumFromText(text) {
+        return this.GetChecksumFromText(text);
+    }
+    async GetContentItemIDFromURL(contentSourceParams, contextUser) {
         const url = contentSourceParams.URL;
         const rv = new RunView();
         const results = await rv.RunView({
@@ -1139,10 +1206,14 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         }
         throw new Error(`Content item with URL ${url} not found`);
     }
+    /** @deprecated Use {@link GetContentItemIDFromURL}. */
+    async getContentItemIDFromURL(contentSourceParams, contextUser) {
+        return this.GetContentItemIDFromURL(contentSourceParams, contextUser);
+    }
     /**
      * Saves process run metadata to the database (backward-compatible simple version).
      */
-    async saveProcessRun(processRunParams, contextUser) {
+    async SaveProcessRun(processRunParams, contextUser) {
         const md = this.ProviderToUse;
         const processRun = await md.GetEntityObject('MJ: Content Process Runs', contextUser);
         processRun.NewRecord();
@@ -1154,6 +1225,10 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         processRun.StartedByUserID = contextUser.ID;
         await processRun.Save();
     }
+    /** @deprecated Use {@link SaveProcessRun}. */
+    async saveProcessRun(processRunParams, contextUser) {
+        return this.SaveProcessRun(processRunParams, contextUser);
+    }
     /**
      * Create a new ContentProcessRun record for batched pipeline execution.
      * Returns the entity so the caller can update cursor/status as batches complete.
@@ -1235,15 +1310,23 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             }),
         };
     }
-    async parsePDF(dataBuffer) {
+    async ParsePDF(dataBuffer) {
         const dataPDF = await pdfParse(dataBuffer);
         return dataPDF.text;
     }
-    async parseDOCX(dataBuffer) {
+    /** @deprecated Use {@link ParsePDF}. */
+    async parsePDF(dataBuffer) {
+        return this.ParsePDF(dataBuffer);
+    }
+    async ParseDOCX(dataBuffer) {
         const dataDOCX = await officeparser.parseOffice(dataBuffer);
         return dataDOCX.toText();
     }
-    async parseHTML(data) {
+    /** @deprecated Use {@link ParseDOCX}. */
+    async parseDOCX(dataBuffer) {
+        return this.ParseDOCX(dataBuffer);
+    }
+    async ParseHTML(data) {
         try {
             const $ = cheerio.load(data);
             $('script, style, nav, footer, header, .hidden').remove();
@@ -1254,18 +1337,26 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             throw e;
         }
     }
-    async parseFileFromPath(filePath) {
+    /** @deprecated Use {@link ParseHTML}. */
+    async parseHTML(data) {
+        return this.ParseHTML(data);
+    }
+    async ParseFileFromPath(filePath) {
         const dataBuffer = await fs.promises.readFile(filePath);
         const fileExtension = filePath.split('.').pop()?.toLowerCase();
         switch (fileExtension) {
             case 'pdf':
-                return this.parsePDF(dataBuffer);
+                return this.ParsePDF(dataBuffer);
             case 'docx':
-                return this.parseDOCX(dataBuffer);
+                return this.ParseDOCX(dataBuffer);
             default:
                 throw new Error(`File type '${fileExtension}' not supported`);
         }
     }
+    /** @deprecated Use {@link ParseFileFromPath}. */
+    async parseFileFromPath(filePath) {
+        return this.ParseFileFromPath(filePath);
+    }
     // ---- Direct Vectorization ----
     /**
      * Embeds content items and upserts them to the appropriate vector index.
@@ -1274,7 +1365,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
      * (first active VectorIndex). Each group is processed in configurable batches with
      * parallel upserts within each batch.
      *
-     * Uses AIModelRunner to create AIPromptRun records for each embedding batch,
+     * Uses AIEmbeddingRunner to create AIPromptRun records for each embedding batch,
      * enabling token/cost tracking and linking to ContentProcessRunDetail records.
      *
      * @param items - content items to vectorize
@@ -1317,21 +1408,21 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
     }
     /**
      * Process a single infrastructure group: embed texts in batches and upsert to vector DB.
-     * Uses AIModelRunner for each embedding batch to create AIPromptRun records with
+     * Uses AIEmbeddingRunner for each embedding batch to create AIPromptRun records with
      * token/cost tracking. Upserts within each batch run in parallel for throughput.
      *
      * @param items - content items in this infrastructure group
      * @param infra - resolved embedding + vector DB infrastructure
      * @param tagMap - pre-loaded tags for metadata enrichment
      * @param batchSize - number of items per embedding batch
-     * @param contextUser - current user for AIModelRunner tracking
+     * @param contextUser - current user for AIEmbeddingRunner tracking
      * @param onBatchComplete - callback invoked after each batch with item count
      * @returns count of vectorized items and collected AIPromptRun IDs
      */
     async vectorizeGroup(items, infra, tagMap, batchSize, contextUser, pathResolver, onBatchComplete) {
         let vectorized = 0;
         const promptRunIDs = [];
-        const modelRunner = new AIModelRunner();
+        const embeddingRunner = new AIEmbeddingRunner();
         // Provider directives are built for every item BEFORE any embedding spend. A driver may
         // reject a record from BuildProviderDirectives (e.g. a mandatory routing value its config
         // requires — such as a tenant-isolation field — is missing); rejected items are marked
@@ -1361,8 +1452,8 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
             const texts = allChunks.map(c => c.text);
             // Rate limit embedding API call
             await this.EmbeddingRateLimiter.Acquire(texts.reduce((sum, t) => sum + Math.ceil(t.length / 4), 0));
-            // Use AIModelRunner to embed texts with AIPromptRun tracking
-            const runResult = await modelRunner.RunEmbedding({
+            // Use AIEmbeddingRunner to embed texts with AIPromptRun tracking
+            const runResult = await embeddingRunner.RunEmbedding({
                 Texts: texts,
                 ModelID: infra.embeddingModelID,
                 PromptID: embeddingPromptID,
@@ -1397,17 +1488,17 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         return { vectorized, promptRunIDs };
     }
     /**
-     * Resolve the "Content Embedding" prompt ID from AIEngine for AIModelRunner tracking.
-     * Returns undefined if the prompt is not found (AIModelRunner will fall back to
-     * the first active Embedding-type prompt).
+     * Resolve the "Content Embedding" prompt ID from AIEngine for AIEmbeddingRunner tracking.
+     * Returns undefined if the prompt is not found (AIEmbeddingRunner then uses the first
+     * active Embedding-type prompt).
      */
     resolveEmbeddingPromptID() {
         const prompt = AIEngine.Instance.Prompts.find(p => p.Name === 'Content Embedding' && p.Status === 'Active');
         if (prompt) {
             return prompt.ID;
         }
-        // Fall back: let AIModelRunner find the first active Embedding prompt
-        LogStatus('[Autotag] "Content Embedding" prompt not found — AIModelRunner will use default embedding prompt');
+        // Fall back: let AIEmbeddingRunner find the first active Embedding prompt
+        LogStatus('[Autotag] "Content Embedding" prompt not found — AIEmbeddingRunner will use default embedding prompt');
         return undefined;
     }
     /**
@@ -2034,7 +2125,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
     async embedAndPersistChunkBatch(embeddable, infra, tagMap, contextUser, stats, directivesByItem) {
         const texts = embeddable.map(e => e.chunk.text);
         await this.EmbeddingRateLimiter.Acquire(texts.reduce((sum, t) => sum + Math.ceil(t.length / 4), 0));
-        const runResult = await new AIModelRunner().RunEmbedding({
+        const runResult = await new AIEmbeddingRunner().RunEmbedding({
             Texts: texts,
             ModelID: infra.embeddingModelID,
             PromptID: this.resolveEmbeddingPromptID(),
@@ -2112,8 +2203,15 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
     /**
      * Load content source and content type records for all unique source/type IDs
      * referenced by the given items. Returns maps keyed by normalized ID.
-     */
-    async loadContentSourceAndTypeMaps(items, _contextUser) {
+     *
+     * Every vectorization entry point (VectorizeContentItems, PurgeDeletedChunks,
+     * EmbedPendingChunks, vector dedup) builds its maps here, so this is where a stale
+     * KnowledgeHub cache is caught — see {@link ensureItemMetadataCached}. The per-item storage
+     * config ({@link resolveItemVectorStorageConfig}) reads the same cache later in the pass, so
+     * it sees the reloaded rows too.
+     */
+    async loadContentSourceAndTypeMaps(items, contextUser) {
+        await this.ensureItemMetadataCached(items, contextUser);
         const sourceIdSet = new Set(items.map(i => NormalizeUUID(i.ContentSourceID)));
         const typeIdSet = new Set(items.map(i => NormalizeUUID(i.ContentTypeID)));
         // Use KH engine cached data instead of RunView calls
@@ -2131,6 +2229,57 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         }
         return { sourceMap, typeMap };
     }
+    /**
+     * Make sure the KnowledgeHub cache holds every content source and content type these items
+     * reference, reloading it ONCE when it does not.
+     *
+     * ── A MISS HERE MEANS THE CACHE IS STALE ────────────────────────────────────────────────────
+     * Both ids are required foreign keys on the item, so the rows exist; a miss means the cache
+     * loaded before they did. That is the normal state of a long-running worker: unless Redis
+     * cross-server cache sync is configured, nothing tells this process about a source another
+     * process created after it booted. And the source row is not decoration. It carries the item's
+     * routing (its EmbeddingModelID / VectorIndexID override) and its storage config
+     * (VectorIDStrategy, ChunkTextStorage, VectorMetadata, VectorEntityName). Read from a stale
+     * cache, every one of those silently falls back to the content type's values or the hard-coded
+     * defaults, so the item is embedded into the wrong index with the wrong vector ids until the
+     * worker restarts, and its later re-runs then write different ids.
+     *
+     * One `Config(true)` reloads all six KnowledgeHub sets in a single batched, cache-bypassing
+     * round trip. It runs only on a miss, so a warm cache costs nothing beyond the set lookups, and
+     * at most once per call however many items miss.
+     *
+     * Never makes things worse: a failed reload is logged and the pass continues on whatever the
+     * cache holds, which is exactly the pre-reload behavior (content type → default cascade).
+     */
+    async ensureItemMetadataCached(items, contextUser) {
+        const uncached = this.findUncachedItemMetadata(items);
+        if (uncached.length === 0)
+            return;
+        LogStatus(`[Autotag] KnowledgeHub cache is missing ${uncached.length} row(s) these items reference (created after it loaded) — reloading it once: ${uncached.join(', ')}`);
+        try {
+            await this.khEngine.Config(true, contextUser, this.ProviderToUse);
+        }
+        catch (e) {
+            LogError(`[Autotag] KnowledgeHub cache reload failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const stillUncached = this.findUncachedItemMetadata(items);
+        if (stillUncached.length > 0) {
+            LogError(`[Autotag] ${stillUncached.length} row(s) still absent from the KnowledgeHub cache after a reload: ${stillUncached.join(', ')} — items referencing them fall back to their content type / default configuration`);
+        }
+    }
+    /** The distinct content source / content type ids these items reference that the KnowledgeHub cache does not hold. */
+    findUncachedItemMetadata(items) {
+        const uncached = new Set();
+        for (const item of items) {
+            if (item.ContentSourceID && !this.khEngine.GetContentSourceByID(item.ContentSourceID)) {
+                uncached.add(`content source ${NormalizeUUID(item.ContentSourceID)}`);
+            }
+            if (item.ContentTypeID && !this.khEngine.GetContentTypeByID(item.ContentTypeID)) {
+                uncached.add(`content type ${NormalizeUUID(item.ContentTypeID)}`);
+            }
+        }
+        return [...uncached];
+    }
     /**
      * Resolve the (embeddingModelID, vectorIndexID) pair for a content item using
      * the cascade: ContentSource override -> ContentType default -> null (global fallback).
@@ -2193,9 +2342,9 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
      * Looks up the vector index by ID and the embedding model from AIEngine.
      */
     async buildVectorInfrastructure(embeddingModelID, vectorIndexID, _contextUser) {
-        const vectorIndex = this.khEngine.GetVectorIndexByID(vectorIndexID);
+        const vectorIndex = AIEngine.Instance.GetVectorIndexByID(vectorIndexID);
         if (!vectorIndex) {
-            throw new Error(`Vector index ${vectorIndexID} not found in KnowledgeHubMetadataEngine cache`);
+            throw new Error(`Vector index ${vectorIndexID} not found in AIEngine cache`);
         }
         return this.createInfrastructureFromIndex(vectorIndex, embeddingModelID);
     }
@@ -2203,7 +2352,7 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
      * Fallback: resolve infrastructure from the first available VectorIndex (original behavior).
      */
     async getDefaultVectorInfrastructure(_contextUser) {
-        const vectorIndexes = this.khEngine.VectorIndexes;
+        const vectorIndexes = AIEngine.Instance.VectorIndexes;
         if (vectorIndexes.length === 0) {
             throw new Error('No vector indexes found — create one in the Configuration tab first');
         }
@@ -2225,13 +2374,14 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         const aiModel = this.findEmbeddingModel(embeddingModelID);
         const driverClass = aiModel.DriverClass;
         const embeddingModelName = aiModel.APIName ?? aiModel.Name;
-        // The 3rd-party index is addressed by ExternalID (the provider-side name); Name is the MJ display label.
-        const externalIndexName = vectorIndex.ExternalID?.trim() || vectorIndex.Name;
+        const externalIndexName = AIEngine.Instance.GetProviderIndexName(vectorIndex);
         LogStatus(`VectorizeContentItems: USING embedding model "${aiModel.Name}" (${driverClass}), vector DB "${vectorDBClassKey}", index "${externalIndexName}" (Vector Index "${vectorIndex.Name}")`);
-        const embedding = this.createEmbeddingInstance(driverClass);
         const vectorDB = this.createVectorDBInstance(vectorDBClassKey);
+        const legacyEmbedding = this.legacyEmbeddingAccessor(driverClass);
         return {
-            embedding,
+            get embedding() {
+                return legacyEmbedding();
+            },
             vectorDB,
             indexName: externalIndexName,
             embeddingModelName,
@@ -2269,20 +2419,17 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         }
         return aiModel;
     }
-    /** Create a BaseEmbeddings instance for a given driver class */
-    createEmbeddingInstance(driverClass) {
-        // No pre-flight key check, deliberately — the same call the EntityDocument pipeline already
-        // makes (`entityVectorSync.ts`), for the reason documented there: an empty key is legitimate
-        // for local-only drivers (LocalEmbedding runs ONNX in-process and does `super(apiKey || 'local')`),
-        // and for a cloud driver that genuinely needs one the constructor or the first inference call
-        // raises a real provider-level auth error, which is more actionable than a guard here.
-        // Gating up front made local embedding models unusable from this pipeline without inventing a
-        // meaningless AI_VENDOR_API_KEY__LocalEmbedding.
-        const apiKey = GetAIAPIKey(driverClass);
-        const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseEmbeddings, driverClass, apiKey || '');
-        if (!instance)
-            throw new Error(`Failed to create embedding instance for ${driverClass}`);
-        return instance;
+    /**
+     * Backs the deprecated `ResolvedVectorInfrastructure.embedding`: builds the driver the way this
+     * engine did before AIEmbeddingRunner, on first read only. Nothing in MJ reads it, so normally
+     * nothing is built. An empty key is fine for keyless drivers such as LocalEmbedding.
+     */
+    legacyEmbeddingAccessor(driverClass) {
+        let driver;
+        return () => {
+            driver ??= MJGlobal.Instance.ClassFactory.CreateInstance(BaseEmbeddings, driverClass, GetAIAPIKey(driverClass) || '') ?? undefined;
+            return driver;
+        };
     }
     /**
      * Create a VectorDBBase instance for a given class key, wired for colocated storage where the
@@ -2898,9 +3045,9 @@ let AutotagBaseEngine = class AutotagBaseEngine extends BaseEngine {
         const text = contentItem.Text.trim();
         const truncated = text.length > 8000 ? text.substring(0, 8000) : text;
         await this.EmbeddingRateLimiter.Acquire(Math.ceil(truncated.length / 4));
-        const modelRunner = new AIModelRunner();
+        const embeddingRunner = new AIEmbeddingRunner();
         const embeddingPromptID = this.resolveEmbeddingPromptID();
-        const runResult = await modelRunner.RunEmbedding({
+        const runResult = await embeddingRunner.RunEmbedding({
             ModelID: infra.embeddingModelID,
             Texts: [truncated],
             PromptID: embeddingPromptID ?? undefined,