@memberjunction/server 5.22.0 → 5.24.0

package/src/generic/RunViewResolver.ts

@@ -765,6 +765,7 @@ export class RunViewResolver extends ResolverBase {
       for (const [index, data] of rawData.entries()) {
         // EntityName is backfilled by RunViewsGeneric when ViewID/ViewName was used
         const entity = input[index].EntityName ? provider.Entities.find((e) => e.Name === input[index].EntityName) : null;
+
         const returnData: any[] = this.processRawData(data.Results, entity ? entity.ID : null, entity);
 
         results.push({

package/src/index.ts

@@ -42,6 +42,7 @@ import { GetAPIKeyEngine } from '@memberjunction/api-keys';
 import { RedisLocalStorageProvider } from '@memberjunction/redis-provider';
 import { GenericDatabaseProvider } from '@memberjunction/generic-database-provider';
 import { PubSubManager } from './generic/PubSubManager.js';
+import { ClientToolRequestManager } from '@memberjunction/ai-agents';
 import { CACHE_INVALIDATION_TOPIC } from './generic/CacheInvalidationResolver.js';
 import { ConnectorFactory, IntegrationEngine, IntegrationSyncOptions } from '@memberjunction/integration-engine';
 import { CronExpressionHelper } from '@memberjunction/scheduling-engine';
@@ -95,7 +96,10 @@ export * from './resolvers/RunAIPromptResolver.js';
 export * from './resolvers/RunAIAgentResolver.js';
 export * from './resolvers/VectorizeEntityResolver.js';
 export * from './resolvers/SearchKnowledgeResolver.js';
+export * from './resolvers/FetchEntityVectorsResolver.js';
 export * from './resolvers/PipelineProgressResolver.js';
+export * from './resolvers/ClientToolRequestResolver.js';
+export * from './resolvers/AutotagPipelineResolver.js';
 export * from './resolvers/TaskResolver.js';
 export * from './generic/KeyValuePairInput.js';
 export * from './generic/KeyInputOutputTypes.js';
@@ -582,6 +586,12 @@ export const serve = async (resolverPaths: Array<string>, app: Application = cre
   }
   PubSubManager.Instance.SetPubSubEngine(pubSub as unknown as PubSubEngine);
 
+  // Wire the ClientToolRequestManager so BaseAgent can publish client tool requests
+  // via the same PubSub infrastructure used for pipeline progress and cache invalidation.
+  ClientToolRequestManager.Instance.SetPublishFunction(
+    (topic: string, payload: Record<string, unknown>) => PubSubManager.Instance.Publish(topic, payload)
+  );
+
   // Global listener: broadcast CACHE_INVALIDATION to all browser clients whenever
   // ANY BaseEntity save/delete occurs on this server — regardless of whether it
   // originated from a GraphQL mutation or internal server-side code (agents, actions,

package/src/resolvers/AutotagPipelineResolver.ts

@@ -0,0 +1,235 @@
+import { Resolver, Mutation, Ctx, Arg, ObjectType, Field } from 'type-graphql';
+import { AppContext } from '../types.js';
+import { LogError, LogStatus, Metadata } from '@memberjunction/core';
+import { MJContentProcessRunEntity } from '@memberjunction/core-entities';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { ActionEngineServer } from '@memberjunction/actions';
+import { PubSubManager } from '../generic/PubSubManager.js';
+import { PipelineProgressNotification } from './PipelineProgressResolver.js';
+import { v4 as uuidv4 } from 'uuid';
+
+const PIPELINE_PROGRESS_TOPIC = 'PIPELINE_PROGRESS';
+
+@ObjectType()
+export class AutotagPipelineResult {
+    @Field()
+    Success: boolean;
+
+    @Field({ nullable: true })
+    Status?: string;
+
+    @Field({ nullable: true })
+    ErrorMessage?: string;
+
+    @Field({ nullable: true })
+    PipelineRunID?: string;
+}
+
+@Resolver()
+export class AutotagPipelineResolver extends ResolverBase {
+    @Mutation(() => AutotagPipelineResult)
+    async RunAutotagPipeline(
+        @Arg('contentSourceIDs', () => [String], { nullable: true }) contentSourceIDs: string[] | undefined,
+        @Arg('forceReprocess', { nullable: true }) forceReprocess: boolean | undefined,
+        @Ctx() { userPayload }: AppContext = {} as AppContext
+    ): Promise<AutotagPipelineResult> {
+        try {
+            const currentUser = this.GetUserFromPayload(userPayload);
+            if (!currentUser) {
+                return { Success: false, Status: 'Error', ErrorMessage: 'Unable to determine current user' };
+            }
+
+            const pipelineRunID = uuidv4();
+            LogStatus(`RunAutotagPipeline: starting pipeline ${pipelineRunID}`);
+
+            // Fire-and-forget: start the pipeline in the background and return immediately
+            this.runPipelineInBackground(pipelineRunID, currentUser, contentSourceIDs, forceReprocess);
+
+            return {
+                Success: true,
+                Status: 'Started',
+                PipelineRunID: pipelineRunID,
+            };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`RunAutotagPipeline mutation failed: ${msg}`);
+            return {
+                Success: false,
+                Status: 'Error',
+                ErrorMessage: msg
+            };
+        }
+    }
+
+    /**
+     * Runs the autotag + vectorize pipeline in the background, publishing progress
+     * updates via PubSub so the client can subscribe via PipelineProgress.
+     */
+    private async runPipelineInBackground(
+        pipelineRunID: string,
+        currentUser: import('@memberjunction/core').UserInfo,
+        contentSourceIDs?: string[],
+        forceReprocess?: boolean
+    ): Promise<void> {
+        const startTime = Date.now();
+        try {
+            this.publishProgress(pipelineRunID, 'autotag', 0, 0, startTime, 'Initializing pipeline...');
+
+            await ActionEngineServer.Instance.Config(false, currentUser);
+            const action = ActionEngineServer.Instance.Actions.find(
+                a => a.Name === 'Autotag and Vectorize Content'
+            );
+
+            if (!action) {
+                LogError(`RunAutotagPipeline: Action 'Autotag and Vectorize Content' not found`);
+                this.publishProgress(pipelineRunID, 'error', 0, 0, startTime, 'Autotag action not found');
+                return;
+            }
+
+            // Stage: autotagging — provide a progress callback that publishes per-item updates
+            this.publishProgress(pipelineRunID, 'autotag', 0, 0, startTime, 'Running autotaggers...');
+
+            const progressCallback = (processed: number, total: number, currentItem?: string) => {
+                const pct = total > 0 ? Math.round((processed / total) * 80) : 0; // 0-80% for tagging
+                this.publishProgress(pipelineRunID, 'autotag', total, pct, startTime, currentItem || `${processed}/${total} items`);
+            };
+
+            // Build action params
+            const actionParams: Array<{ Name: string; Value: unknown; Type: 'Input' | 'Output' | 'Both' }> = [
+                { Name: 'Autotag', Value: 1, Type: 'Input' },
+                { Name: 'Vectorize', Value: 1, Type: 'Input' },
+                { Name: '__progressCallback', Value: progressCallback, Type: 'Input' }
+            ];
+            if (contentSourceIDs && contentSourceIDs.length > 0) {
+                actionParams.push({ Name: 'ContentSourceIDs', Value: contentSourceIDs, Type: 'Input' });
+            }
+            if (forceReprocess) {
+                actionParams.push({ Name: 'ForceReprocess', Value: 1, Type: 'Input' });
+            }
+
+            const result = await ActionEngineServer.Instance.RunAction({
+                Action: action,
+                ContextUser: currentUser,
+                Filters: [],
+                Params: actionParams
+            });
+
+            // Stage: vectorize complete
+            this.publishProgress(pipelineRunID, 'vectorize', 100, 90, startTime, 'Vectorizing content...');
+
+            if (result.Success) {
+                LogStatus(`RunAutotagPipeline: pipeline ${pipelineRunID} completed successfully`);
+                this.publishProgress(pipelineRunID, 'complete', 100, 100, startTime);
+            } else {
+                LogError(`RunAutotagPipeline: pipeline ${pipelineRunID} failed: ${result.Message}`);
+                this.publishProgress(pipelineRunID, 'error', 0, 0, startTime, String(result.Message));
+            }
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`RunAutotagPipeline pipeline ${pipelineRunID} failed: ${msg}`);
+            this.publishProgress(pipelineRunID, 'error', 0, 0, startTime, msg);
+        }
+    }
+
+    /**
+     * Pause a running classification pipeline by setting CancellationRequested on the process run.
+     * The engine checks this flag between batches and pauses gracefully.
+     */
+    @Mutation(() => AutotagPipelineResult)
+    async PauseClassificationPipeline(
+        @Arg('processRunID') processRunID: string,
+        @Ctx() { userPayload }: AppContext = {} as AppContext
+    ): Promise<AutotagPipelineResult> {
+        try {
+            const currentUser = this.GetUserFromPayload(userPayload);
+            if (!currentUser) {
+                return { Success: false, Status: 'Error', ErrorMessage: 'Unable to determine current user' };
+            }
+
+            const md = new Metadata();
+            const run = await md.GetEntityObject<MJContentProcessRunEntity>('MJ: Content Process Runs', currentUser);
+            const loaded = await run.Load(processRunID);
+            if (!loaded) {
+                return { Success: false, Status: 'Error', ErrorMessage: `Process run ${processRunID} not found` };
+            }
+
+            run.CancellationRequested = true;
+            await run.Save();
+
+            LogStatus(`PauseClassificationPipeline: Pause requested for run ${processRunID}`);
+            return { Success: true, Status: 'PauseRequested' };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { Success: false, Status: 'Error', ErrorMessage: msg };
+        }
+    }
+
+    /**
+     * Resume a paused classification pipeline from its last completed offset.
+     */
+    @Mutation(() => AutotagPipelineResult)
+    async ResumeClassificationPipeline(
+        @Arg('processRunID') processRunID: string,
+        @Ctx() { userPayload }: AppContext = {} as AppContext
+    ): Promise<AutotagPipelineResult> {
+        try {
+            const currentUser = this.GetUserFromPayload(userPayload);
+            if (!currentUser) {
+                return { Success: false, Status: 'Error', ErrorMessage: 'Unable to determine current user' };
+            }
+
+            const md = new Metadata();
+            const run = await md.GetEntityObject<MJContentProcessRunEntity>('MJ: Content Process Runs', currentUser);
+            const loaded = await run.Load(processRunID);
+            if (!loaded) {
+                return { Success: false, Status: 'Error', ErrorMessage: `Process run ${processRunID} not found` };
+            }
+
+            if (run.Status !== 'Paused') {
+                return { Success: false, Status: 'Error', ErrorMessage: `Run is not paused (Status: ${run.Status})` };
+            }
+
+            // Reset cancellation flag and set status back to Running
+            run.CancellationRequested = false;
+            run.Status = 'Running';
+            await run.Save();
+
+            // Fire-and-forget: resume pipeline in background from the last offset
+            const pipelineRunID = uuidv4();
+            LogStatus(`ResumeClassificationPipeline: Resuming run ${processRunID} from offset ${run.LastProcessedOffset}`);
+
+            this.runPipelineInBackground(pipelineRunID, currentUser, undefined, undefined);
+
+            return { Success: true, Status: 'Resumed', PipelineRunID: pipelineRunID };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { Success: false, Status: 'Error', ErrorMessage: msg };
+        }
+    }
+
+    /**
+     * Publish a progress update to the PipelineProgress subscription topic.
+     */
+    private publishProgress(
+        pipelineRunID: string,
+        stage: string,
+        totalItems: number,
+        processedItems: number,
+        startTime: number,
+        currentItem?: string
+    ): void {
+        const elapsedMs = Date.now() - startTime;
+        const percentComplete = totalItems > 0 ? Math.round((processedItems / totalItems) * 100) : 0;
+
+        const notification: PipelineProgressNotification = {
+            PipelineRunID: pipelineRunID,
+            Stage: stage,
+            TotalItems: totalItems,
+            ProcessedItems: processedItems,
+            CurrentItem: currentItem,
+            ElapsedMs: elapsedMs,
+            PercentComplete: percentComplete,
+        };
+        PubSubManager.Instance.Publish(PIPELINE_PROGRESS_TOPIC, { ...notification });
+    }
+}

package/src/resolvers/ClientToolRequestResolver.ts

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview GraphQL resolver for client tool request/response communication.
+ *
+ * Provides:
+ * - Subscription: Client subscribes to receive tool requests for a session
+ * - Mutation: Client sends tool execution responses back to the server
+ * - Mutation: Client sends enriched tool definitions after decoration
+ *
+ * @module @memberjunction/server
+ */
+
+import { Resolver, Subscription, Root, ObjectType, Field, Float, Mutation, Arg, Ctx } from 'type-graphql';
+import { AppContext } from '../types.js';
+import { LogStatus, LogError } from '@memberjunction/core';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { ClientToolRequestManager, CLIENT_TOOL_REQUEST_TOPIC, ClientToolRequestNotificationPayload } from '@memberjunction/ai-agents';
+
+@ObjectType()
+export class ClientToolRequestNotification {
+    @Field()
+    AgentRunID: string;
+
+    @Field()
+    SessionID: string;
+
+    @Field()
+    RequestID: string;
+
+    @Field()
+    ToolName: string;
+
+    /** JSON-encoded parameters */
+    @Field()
+    Params: string;
+
+    @Field(() => Float)
+    TimeoutMs: number;
+
+    @Field({ nullable: true })
+    Description?: string;
+}
+
+@Resolver()
+export class ClientToolRequestResolver extends ResolverBase {
+    /**
+     * Subscribe to client tool requests for a specific session.
+     * The client listens on this subscription to know when an agent
+     * wants to invoke a browser-side tool.
+     */
+    @Subscription(() => ClientToolRequestNotification, {
+        topics: CLIENT_TOOL_REQUEST_TOPIC,
+        filter: ({ payload, args }: { payload: ClientToolRequestNotificationPayload; args: { sessionID: string } }) => {
+            return payload.SessionID === args.sessionID;
+        },
+    })
+    ClientToolRequest(
+        @Root() notification: ClientToolRequestNotificationPayload,
+        @Arg('sessionID') _sessionID: string
+    ): ClientToolRequestNotification {
+        return {
+            AgentRunID: notification.AgentRunID,
+            SessionID: notification.SessionID,
+            RequestID: notification.RequestID,
+            ToolName: notification.ToolName,
+            Params: notification.Params,
+            TimeoutMs: notification.TimeoutMs,
+            Description: notification.Description
+        };
+    }
+
+    /**
+     * Client sends the result of executing a client tool back to the server.
+     * This resolves the pending Promise in ClientToolRequestManager so the
+     * agent loop can continue.
+     */
+    @Mutation(() => Boolean)
+    async RespondToClientToolRequest(
+        @Arg('requestID') requestID: string,
+        @Arg('success') success: boolean,
+        @Arg('result', { nullable: true }) result: string | undefined,
+        @Arg('errorMessage', { nullable: true }) errorMessage: string | undefined,
+        @Ctx() _context: AppContext = {} as AppContext
+    ): Promise<boolean> {
+        try {
+            const found = ClientToolRequestManager.Instance.ReceiveResponse({
+                RequestID: requestID,
+                Success: success,
+                Result: result ? JSON.parse(result) : undefined,
+                ErrorMessage: errorMessage
+            });
+
+            if (!found) {
+                LogError(`RespondToClientToolRequest: no pending request for ${requestID} (may have timed out)`);
+            }
+            return found;
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`RespondToClientToolRequest error: ${msg}`);
+            return false;
+        }
+    }
+
+    /**
+     * Client sends enriched tool definitions after running decorators.
+     * The server stores them per session for LLM prompt injection.
+     */
+    @Mutation(() => Boolean)
+    async UpdateClientToolDefinitions(
+        @Arg('sessionID') sessionID: string,
+        @Arg('tools') toolsJson: string,
+        @Ctx() _context: AppContext = {} as AppContext
+    ): Promise<boolean> {
+        try {
+            const tools = JSON.parse(toolsJson);
+            if (!Array.isArray(tools)) {
+                LogError('UpdateClientToolDefinitions: tools must be a JSON array');
+                return false;
+            }
+            ClientToolRequestManager.Instance.SetSessionTools(sessionID, tools);
+            LogStatus(`UpdateClientToolDefinitions: stored ${tools.length} tools for session ${sessionID}`);
+            return true;
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`UpdateClientToolDefinitions error: ${msg}`);
+            return false;
+        }
+    }
+}

package/src/resolvers/FetchEntityVectorsResolver.ts

@@ -0,0 +1,238 @@
+import { Resolver, Query, Arg, Ctx, ObjectType, Field, Float, Int } from 'type-graphql';
+import { AppContext } from '../types.js';
+import { LogError, LogStatus, Metadata, RunView, UserInfo } from '@memberjunction/core';
+import { MJEntityDocumentEntity, MJVectorIndexEntity, MJVectorDatabaseEntity } from '@memberjunction/core-entities';
+import { ResolverBase } from '../generic/ResolverBase.js';
+import { GetAIAPIKey } from '@memberjunction/ai';
+import { VectorDBBase } from '@memberjunction/ai-vectordb';
+import { MJGlobal, UUIDsEqual } from '@memberjunction/global';
+
+/* ───── GraphQL types ───── */
+
+@ObjectType()
+export class EntityVectorItem {
+    @Field()
+    ID: string;
+
+    @Field(() => [Float])
+    Values: number[];
+
+    @Field(() => String)
+    Metadata: string;
+}
+
+@ObjectType()
+export class FetchEntityVectorsResult {
+    @Field()
+    Success: boolean;
+
+    @Field(() => [EntityVectorItem])
+    Results: EntityVectorItem[];
+
+    @Field()
+    TotalCount: number;
+
+    @Field()
+    ElapsedMs: number;
+
+    @Field({ nullable: true })
+    ErrorMessage?: string;
+}
+
+/* ───── Resolver ───── */
+
+@Resolver()
+export class FetchEntityVectorsResolver extends ResolverBase {
+
+    @Query(() => FetchEntityVectorsResult)
+    async FetchEntityVectors(
+        @Arg('entityDocumentID') entityDocumentID: string,
+        @Arg('maxRecords', () => Int, { nullable: true }) maxRecords: number | undefined,
+        @Arg('filter', { nullable: true }) filter: string | undefined,
+        @Ctx() { userPayload }: AppContext = {} as AppContext
+    ): Promise<FetchEntityVectorsResult> {
+        const startTime = Date.now();
+        try {
+            const currentUser = this.GetUserFromPayload(userPayload);
+            if (!currentUser) {
+                return this.errorResult('Unable to determine current user', startTime);
+            }
+
+            const limit = maxRecords ?? 1000;
+
+            // Step 1: Load the EntityDocument
+            const entityDoc = await this.loadEntityDocument(entityDocumentID, currentUser);
+            if (!entityDoc) {
+                return this.errorResult(`EntityDocument not found: ${entityDocumentID}`, startTime);
+            }
+
+            // Step 2: Resolve the VectorIndex
+            const vectorIndex = await this.resolveVectorIndex(entityDoc, currentUser);
+            if (!vectorIndex) {
+                return this.errorResult(
+                    `Could not resolve VectorIndex for EntityDocument "${entityDoc.Name}"`,
+                    startTime
+                );
+            }
+
+            // Step 3: Create VectorDB provider instance
+            const vectorDBInstance = await this.createVectorDBInstance(vectorIndex, currentUser);
+            if (!vectorDBInstance) {
+                return this.errorResult(
+                    `Could not create VectorDB provider for index "${vectorIndex.Name}"`,
+                    startTime
+                );
+            }
+
+            // Step 4: Query with zero vector + Entity metadata filter.
+            // Pinecone's list API doesn't support metadata filtering, but query does.
+            // A zero vector returns results in arbitrary order (similarity is meaningless),
+            // but the metadata filter ensures we only get vectors for this entity.
+            const entityName = entityDoc.Entity;
+            const dimensions = vectorIndex.Dimensions || 1536; // fall back to common embedding size
+            // Use a tiny uniform vector instead of zero — cosine similarity is undefined
+            // for a zero vector (division by zero), causing Pinecone to return 0 matches.
+            // A uniform vector has equal similarity to all vectors, giving us an unbiased
+            // listing that respects the metadata filter.
+            const uniformVector = new Array(dimensions).fill(1.0 / Math.sqrt(dimensions));
+
+            const metadataFilter: Record<string, unknown> = { Entity: { $eq: entityName } };
+
+            const queryResponse = await vectorDBInstance.QueryIndex({
+                id: vectorIndex.Name,  // index name (stripped before Pinecone query)
+                vector: uniformVector,
+                topK: limit,
+                includeMetadata: true,
+                includeValues: true,
+                filter: metadataFilter,
+            });
+
+            if (!queryResponse.success || !queryResponse.data) {
+                return this.errorResult(
+                    `Vector query failed for entity "${entityName}" in index "${vectorIndex.Name}"`,
+                    startTime
+                );
+            }
+
+            // Step 5: Convert query matches to result format
+            const matches = (queryResponse.data as { matches?: Array<{ id: string; values?: number[]; metadata?: Record<string, unknown>; score?: number }> }).matches ?? [];
+            const results: EntityVectorItem[] = matches.map(match => ({
+                ID: match.id,
+                Values: match.values ?? [],
+                Metadata: JSON.stringify(match.metadata ?? {}),
+            }));
+            LogStatus(`FetchEntityVectors: Queried ${results.length} vectors for entity "${entityName}" in ${Date.now() - startTime}ms`);
+
+            return {
+                Success: true,
+                Results: results,
+                TotalCount: results.length,
+                ElapsedMs: Date.now() - startTime,
+            };
+        } catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            LogError(`FetchEntityVectors query failed: ${msg}`);
+            return this.errorResult(msg, startTime);
+        }
+    }
+
+    /** Load EntityDocument by ID */
+    private async loadEntityDocument(
+        entityDocumentID: string,
+        contextUser: UserInfo
+    ): Promise<MJEntityDocumentEntity | null> {
+        const rv = new RunView();
+        const result = await rv.RunView<MJEntityDocumentEntity>({
+            EntityName: 'MJ: Entity Documents',
+            ExtraFilter: `ID='${entityDocumentID}'`,
+            ResultType: 'entity_object',
+        }, contextUser);
+
+        if (!result.Success || result.Results.length === 0) {
+            return null;
+        }
+        return result.Results[0];
+    }
+
+    /**
+     * Resolve the VectorIndex for an EntityDocument.
+     * Prefers the explicit VectorIndexID on the EntityDocument; falls back to
+     * finding a VectorIndex by matching VectorDatabaseID + EmbeddingModelID.
+     */
+    private async resolveVectorIndex(
+        entityDoc: MJEntityDocumentEntity,
+        contextUser: UserInfo
+    ): Promise<MJVectorIndexEntity | null> {
+        const rv = new RunView();
+
+        // If the EntityDocument has an explicit VectorIndexID, use it directly
+        if (entityDoc.VectorIndexID) {
+            const result = await rv.RunView<MJVectorIndexEntity>({
+                EntityName: 'MJ: Vector Indexes',
+                ExtraFilter: `ID='${entityDoc.VectorIndexID}'`,
+                ResultType: 'entity_object',
+            }, contextUser);
+
+            if (result.Success && result.Results.length > 0) {
+                return result.Results[0];
+            }
+            LogError(`FetchEntityVectors: VectorIndex ${entityDoc.VectorIndexID} referenced by EntityDocument not found`);
+        }
+
+        // Fallback: find a VectorIndex by VectorDatabaseID + matching AIModelID as EmbeddingModelID
+        const indexResult = await rv.RunView<MJVectorIndexEntity>({
+            EntityName: 'MJ: Vector Indexes',
+            ExtraFilter: `VectorDatabaseID='${entityDoc.VectorDatabaseID}'`,
+            ResultType: 'entity_object',
+        }, contextUser);
+
+        if (!indexResult.Success || indexResult.Results.length === 0) {
+            return null;
+        }
+
+        // Match on EmbeddingModelID = EntityDocument.AIModelID
+        const match = indexResult.Results.find(idx =>
+            UUIDsEqual(idx.EmbeddingModelID, entityDoc.AIModelID)
+        );
+        return match ?? indexResult.Results[0];
+    }
+
+    /** Create a VectorDBBase provider instance for a given VectorIndex */
+    private async createVectorDBInstance(
+        vectorIndex: MJVectorIndexEntity,
+        contextUser: UserInfo
+    ): Promise<VectorDBBase | null> {
+        const rv = new RunView();
+        const dbResult = await rv.RunView<MJVectorDatabaseEntity>({
+            EntityName: 'MJ: Vector Databases',
+            ExtraFilter: `ID='${vectorIndex.VectorDatabaseID}'`,
+            ResultType: 'entity_object',
+        }, contextUser);
+
+        if (!dbResult.Success || dbResult.Results.length === 0) {
+            LogError(`FetchEntityVectors: VectorDatabase not found for index "${vectorIndex.Name}"`);
+            return null;
+        }
+
+        const vectorDB = dbResult.Results[0];
+        const apiKey = GetAIAPIKey(vectorDB.ClassKey);
+        const instance = MJGlobal.Instance.ClassFactory.CreateInstance<VectorDBBase>(
+            VectorDBBase, vectorDB.ClassKey, apiKey
+        );
+
+        if (!instance) {
+            LogError(`FetchEntityVectors: Failed to create VectorDB instance for ClassKey "${vectorDB.ClassKey}"`);
+        }
+        return instance;
+    }
+
+    private errorResult(message: string, startTime: number): FetchEntityVectorsResult {
+        return {
+            Success: false,
+            Results: [],
+            TotalCount: 0,
+            ElapsedMs: Date.now() - startTime,
+            ErrorMessage: message,
+        };
+    }
+}