@memberjunction/core-actions 5.24.0 → 5.26.0

package/dist/custom/search/search.action.js

@@ -0,0 +1,211 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseAction } from "@memberjunction/actions";
+import { RegisterClass } from "@memberjunction/global";
+import { LogError, LogStatus } from "@memberjunction/core";
+import { SearchEngine } from "@memberjunction/search-engine";
+/**
+ * Action that executes a universal search across the organization's knowledge base.
+ *
+ * This action delegates to the `@memberjunction/search-engine` singleton which
+ * orchestrates vector similarity search, full-text search, entity LIKE-based search,
+ * and (optionally) storage file search. Results are fused via Reciprocal Rank Fusion (RRF),
+ * deduplicated, and enriched with entity icons, record names, and tags.
+ *
+ * Designed for use by AI agents (Sage, etc.), MCP connectors, A2A connectors,
+ * and workflow orchestration.
+ *
+ * @example
+ * ```typescript
+ * // Simple search
+ * await runAction({
+ *   ActionName: 'Search',
+ *   Params: [{ Name: 'Query', Value: 'quarterly revenue by region' }]
+ * });
+ *
+ * // Advanced search with filters
+ * await runAction({
+ *   ActionName: 'Search',
+ *   Params: [
+ *     { Name: 'Query',          Value: 'customer onboarding process' },
+ *     { Name: 'MaxResults',     Value: 10 },
+ *     { Name: 'MinScore',       Value: 0.3 },
+ *     { Name: 'EntityNames',    Value: 'Documents,Knowledge Articles' },
+ *     { Name: 'IncludeSources', Value: 'vector,fulltext' }
+ *   ]
+ * });
+ * ```
+ */
+let SearchAction = class SearchAction extends BaseAction {
+    async InternalRunAction(params) {
+        try {
+            // --- Extract and validate input parameters ---
+            const query = this.getStringParam(params, "query");
+            if (!query) {
+                return this.createErrorResult("Query parameter is required", "MISSING_QUERY");
+            }
+            if (!params.ContextUser) {
+                return this.createErrorResult("User context is required", "MISSING_USER_CONTEXT");
+            }
+            const maxResults = this.getNumericParam(params, "maxresults", 25);
+            const minScore = this.getNumericParam(params, "minscore", 0);
+            const includeSources = this.parseIncludeSources(params);
+            const entityNames = this.parseEntityNames(params);
+            const tags = this.parseTags(params);
+            // --- Ensure SearchEngine is configured ---
+            await SearchEngine.Instance.Config({}, params.ContextUser);
+            // --- Build SearchParams ---
+            const searchParams = this.buildSearchParams(query, maxResults, minScore, entityNames, includeSources, tags);
+            LogStatus(`SearchAction: Searching for "${query}" (max ${maxResults}, minScore ${minScore})`);
+            // --- Execute search ---
+            const result = await SearchEngine.Instance.Search(searchParams, params.ContextUser);
+            if (!result.Success) {
+                return this.createErrorResult(result.ErrorMessage || "Search failed with no error message", "SEARCH_FAILED");
+            }
+            // --- Format results for output ---
+            const formattedResults = this.formatResults(result.Results);
+            // --- Build output parameters ---
+            const outputParams = [
+                { Name: "Results", Value: formattedResults, Type: "Output" },
+                { Name: "TotalCount", Value: result.TotalCount, Type: "Output" },
+                { Name: "ElapsedMs", Value: result.ElapsedMs, Type: "Output" },
+                { Name: "SourceCounts", Value: result.SourceCounts, Type: "Output" }
+            ];
+            return {
+                Success: true,
+                ResultCode: "SUCCESS",
+                Message: `Found ${result.TotalCount} result(s) for "${query}" in ${result.ElapsedMs}ms`,
+                Params: outputParams
+            };
+        }
+        catch (error) {
+            LogError(`SearchAction error: ${error instanceof Error ? error.message : String(error)}`);
+            return this.createErrorResult(`Unexpected error during search: ${error instanceof Error ? error.message : String(error)}`, "UNEXPECTED_ERROR");
+        }
+    }
+    // ─── Private helpers ──────────────────────────────────────────────
+    /**
+     * Parse the IncludeSources parameter into a SearchSource array.
+     * Accepts a comma-separated string.
+     */
+    parseIncludeSources(params) {
+        const raw = this.getStringParam(params, "includesources");
+        if (!raw)
+            return undefined;
+        const validSources = ["vector", "fulltext", "entity"];
+        return raw
+            .split(",")
+            .map(s => s.trim().toLowerCase())
+            .filter((s) => validSources.includes(s));
+    }
+    /**
+     * Parse the EntityNames filter parameter into a string array.
+     */
+    parseEntityNames(params) {
+        const raw = this.getStringParam(params, "entitynames");
+        if (!raw)
+            return undefined;
+        return raw.split(",").map(s => s.trim()).filter(s => s.length > 0);
+    }
+    /**
+     * Parse the Tags filter parameter into a string array.
+     */
+    parseTags(params) {
+        const raw = this.getStringParam(params, "tags");
+        if (!raw)
+            return undefined;
+        return raw.split(",").map(s => s.trim()).filter(s => s.length > 0);
+    }
+    /**
+     * Build a SearchParams object from the extracted and validated parameters.
+     */
+    buildSearchParams(query, maxResults, minScore, entityNames, includeSources, tags) {
+        const searchParams = {
+            Query: query,
+            MaxResults: maxResults,
+            MinScore: minScore
+        };
+        const filters = this.buildFilters(entityNames, includeSources, tags);
+        if (filters) {
+            searchParams.Filters = filters;
+        }
+        return searchParams;
+    }
+    /**
+     * Build a SearchFilters object from the parsed filter parameters.
+     * Returns undefined if no filters are specified.
+     */
+    buildFilters(entityNames, includeSources, tags) {
+        if (!entityNames && !includeSources && !tags) {
+            return undefined;
+        }
+        const filters = {};
+        if (entityNames && entityNames.length > 0) {
+            filters.EntityNames = entityNames;
+        }
+        if (includeSources && includeSources.length > 0) {
+            filters.SourceTypes = includeSources;
+        }
+        if (tags && tags.length > 0) {
+            filters.Tags = tags;
+        }
+        return filters;
+    }
+    /**
+     * Convert SearchResultItem objects into serialization-safe formatted results.
+     */
+    formatResults(items) {
+        return items.map(item => ({
+            ID: item.ID,
+            EntityName: item.EntityName,
+            RecordID: item.RecordID,
+            SourceType: item.SourceType,
+            ResultType: item.ResultType,
+            Title: item.Title,
+            Snippet: item.Snippet,
+            Score: item.Score,
+            ScoreBreakdown: {
+                Vector: item.ScoreBreakdown.Vector,
+                FullText: item.ScoreBreakdown.FullText,
+                Entity: item.ScoreBreakdown.Entity,
+                Storage: item.ScoreBreakdown.Storage
+            },
+            Tags: item.Tags,
+            EntityIcon: item.EntityIcon,
+            RecordName: item.RecordName,
+            MatchedAt: item.MatchedAt instanceof Date ? item.MatchedAt.toISOString() : String(item.MatchedAt),
+            RawMetadata: item.RawMetadata
+        }));
+    }
+    // ─── Parameter extraction helpers ─────────────────────────────────
+    getStringParam(params, paramName) {
+        const param = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        if (!param || param.Value === undefined || param.Value === null)
+            return undefined;
+        const value = String(param.Value).trim();
+        return value.length > 0 ? value : undefined;
+    }
+    getNumericParam(params, paramName, defaultValue) {
+        const param = params.Params.find(p => p.Name.trim().toLowerCase() === paramName.toLowerCase());
+        if (!param || param.Value === undefined || param.Value === null)
+            return defaultValue;
+        const parsed = Number(param.Value);
+        return isNaN(parsed) ? defaultValue : parsed;
+    }
+    createErrorResult(message, code) {
+        return {
+            Success: false,
+            Message: message,
+            ResultCode: code
+        };
+    }
+};
+SearchAction = __decorate([
+    RegisterClass(BaseAction, "__Internal_Search")
+], SearchAction);
+export { SearchAction };
+//# sourceMappingURL=search.action.js.map

package/dist/custom/search/search.action.js.map

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

package/dist/custom/utilities/artifact-builder-service.d.ts

@@ -0,0 +1,139 @@
+import { PDFOptions } from './pdf-renderer.js';
+import { WordOptions } from './docx-renderer.js';
+import { ExcelOptions } from './xlsx-renderer.js';
+export type DocumentType = 'pdf' | 'docx' | 'xlsx';
+export interface DocumentOptions {
+    pdf?: Partial<PDFOptions>;
+    word?: Partial<WordOptions>;
+    excel?: Partial<ExcelOptions>;
+}
+/**
+ * A single content operation that can be added to a document.
+ * This is the union type that the LLM sends in the Operations parameter.
+ */
+export type DocumentOperation = {
+    type: 'heading';
+    level: 1 | 2 | 3 | 4 | 5 | 6;
+    text: string;
+} | {
+    type: 'paragraph';
+    text: string;
+    bold?: boolean;
+    italic?: boolean;
+    align?: string;
+} | {
+    type: 'table';
+    headers: string[];
+    rows: string[][];
+} | {
+    type: 'list';
+    items: string[];
+    ordered?: boolean;
+} | {
+    type: 'image';
+    src: string;
+    width?: number;
+    height?: number;
+    caption?: string;
+} | {
+    type: 'pageBreak';
+} | {
+    type: 'hr';
+} | {
+    type: 'sheet';
+    name: string;
+    data: Record<string, unknown>[];
+    headers?: string[];
+    columnWidths?: number[];
+} | {
+    type: 'formula';
+    sheet: string;
+    cell: string;
+    formula: string;
+};
+export interface DocumentSectionInfo {
+    id: string;
+    operations: DocumentOperation[];
+}
+export interface InProgressDocument {
+    handle: string;
+    documentType: DocumentType;
+    fileName: string;
+    options: DocumentOptions;
+    sections: DocumentSectionInfo[];
+    createdAt: Date;
+    lastModifiedAt: Date;
+}
+export interface DocumentPreview {
+    handle: string;
+    documentType: DocumentType;
+    fileName: string;
+    sectionCount: number;
+    sections: Array<{
+        id: string;
+        operationCount: number;
+        summary: string;
+    }>;
+    totalOperations: number;
+}
+/**
+ * Singleton service managing in-progress documents.
+ * Each document is identified by a UUID handle and persists across agent turns
+ * within the same Node.js process.
+ */
+export declare class ArtifactBuilderService {
+    private static _instance;
+    private documents;
+    private cleanupTimer;
+    private constructor();
+    static get Instance(): ArtifactBuilderService;
+    /**
+     * Create a new in-progress document and return its handle.
+     */
+    CreateDocument(documentType: DocumentType, fileName?: string, options?: DocumentOptions): string;
+    /**
+     * Add content operations as a new section to an existing document.
+     * Returns the section ID(s) created.
+     */
+    AddContent(handle: string, operations: DocumentOperation[]): string[];
+    /**
+     * Get a preview of the document's current state.
+     */
+    GetPreview(handle: string): DocumentPreview;
+    /**
+     * Replace a section's content by ID.
+     */
+    ReplaceSection(handle: string, sectionId: string, operations: DocumentOperation[]): void;
+    /**
+     * Remove a section by ID.
+     */
+    RemoveSection(handle: string, sectionId: string): void;
+    /**
+     * Render the accumulated document to a binary buffer.
+     * The handle is disposed after finalization.
+     */
+    Finalize(handle: string): Promise<{
+        buffer: Buffer;
+        fileName: string;
+        mimeType: string;
+    }>;
+    /**
+     * Dispose a document handle without finalizing.
+     */
+    Dispose(handle: string): void;
+    /**
+     * Check if a handle exists.
+     */
+    HasDocument(handle: string): boolean;
+    private finalizePDF;
+    private finalizeDocx;
+    private finalizeXlsx;
+    private operationsToPDFNodes;
+    private operationsToDocxSections;
+    private operationsToSheets;
+    private getDocument;
+    private defaultFileName;
+    private summarizeSection;
+    private startCleanupTimer;
+}
+//# sourceMappingURL=artifact-builder-service.d.ts.map

package/dist/custom/utilities/artifact-builder-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-builder-service.d.ts","sourceRoot":"","sources":["../../../src/custom/utilities/artifact-builder-service.ts"],"names":[],"mappings":"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"}