@memberjunction/query-gen 0.0.1 → 2.126.1

package/dist/core/EntityGrouper.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * LLM-based Entity Grouper
+ *
+ * Uses AI to generate semantically meaningful entity groupings based on
+ * business context and schema understanding, replacing the deterministic
+ * hub-and-spoke algorithm with intelligent semantic analysis.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityGrouper = void 0;
+const core_1 = require("@memberjunction/core");
+const aiengine_1 = require("@memberjunction/aiengine");
+const graph_helpers_1 = require("../utils/graph-helpers");
+const error_handlers_1 = require("../utils/error-handlers");
+const prompt_helpers_1 = require("../utils/prompt-helpers");
+/**
+ * Generates entity groups using LLM-based semantic analysis
+ *
+ * This class replaces the deterministic hub-and-spoke algorithm with an
+ * intelligent approach that understands business context and generates
+ * meaningful entity combinations for query generation.
+ */
+class EntityGrouper {
+    promptName = 'Entity Group Generator';
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Generate semantically meaningful entity groups using LLM analysis
+     *
+     * Note: The LLM determines the optimal number and size of entity groups based on
+     * business domain understanding. Makes separate LLM calls for each schema to
+     * avoid mixing entities from different databases.
+     *
+     * @param entities - All entities to analyze
+     * @param contextUser - User context for server-side operations
+     * @returns Array of validated entity groups with business context
+     */
+    async generateEntityGroups(entities, contextUser) {
+        try {
+            // 1. Group entities by schema
+            const entitiesBySchema = this.groupEntitiesBySchema(entities);
+            // 2. Process each schema separately
+            const allGroups = [];
+            let schemaIndex = 0;
+            const totalSchemas = entitiesBySchema.size;
+            for (const [schemaName, schemaEntities] of entitiesBySchema.entries()) {
+                schemaIndex++;
+                if (this.config.verbose && totalSchemas > 1) {
+                    (0, core_1.LogStatus)(`[${schemaIndex}/${totalSchemas}] Processing schema: ${schemaName} (${schemaEntities.length} entities)`);
+                }
+                // 2a. Prepare schema data for LLM
+                const schemaData = this.prepareSchemaData(schemaEntities, schemaName);
+                // 2b. Call LLM to generate groups for this schema
+                const llmResponse = await this.callLLMForGrouping(schemaData, contextUser);
+                // 2c. Validate and convert to EntityGroup objects
+                const validatedGroups = this.validateAndConvertGroups(llmResponse, schemaEntities);
+                if (this.config.verbose && totalSchemas > 1) {
+                    (0, core_1.LogStatus)(`[${schemaIndex}/${totalSchemas}] Generated ${validatedGroups.length} groups for schema: ${schemaName}`);
+                }
+                allGroups.push(...validatedGroups);
+            }
+            // 3. Deduplicate any similar groups across all schemas
+            const deduplicatedGroups = this.deduplicateGroups(allGroups);
+            return deduplicatedGroups;
+        }
+        catch (error) {
+            throw new Error((0, error_handlers_1.extractErrorMessage)(error, 'EntityGrouper.generateEntityGroups'));
+        }
+    }
+    /**
+     * Group entities by schema name
+     */
+    groupEntitiesBySchema(entities) {
+        const schemaMap = new Map();
+        for (const entity of entities) {
+            const schemaName = entity.SchemaName || 'Unknown';
+            const schemaEntities = schemaMap.get(schemaName) || [];
+            schemaEntities.push(entity);
+            schemaMap.set(schemaName, schemaEntities);
+        }
+        return schemaMap;
+    }
+    /**
+     * Prepare schema data for LLM prompt
+     *
+     * Note: The LLM will determine appropriate group count based on business
+     * domain understanding and schema complexity. We provide the full entity
+     * schema and relationship graph for intelligent analysis.
+     *
+     * @param entities - Entities within a single schema
+     * @param schemaName - Name of the schema being processed
+     */
+    prepareSchemaData(entities, schemaName) {
+        const formattedEntities = (0, graph_helpers_1.formatEntitiesForPrompt)(entities);
+        const relationshipGraph = (0, graph_helpers_1.generateRelationshipGraph)(entities);
+        return {
+            schemaName,
+            entities: formattedEntities,
+            relationshipGraph,
+            minGroupSize: this.config.minGroupSize,
+            maxGroupSize: this.config.maxGroupSize
+        };
+    }
+    /**
+     * Call LLM via AIPromptRunner to generate entity groups
+     */
+    async callLLMForGrouping(schemaData, contextUser) {
+        // Get prompt entity from AIEngine
+        const prompt = aiengine_1.AIEngine.Instance.Prompts.find(p => p.Name === this.promptName);
+        if (!prompt) {
+            throw new Error(`Prompt "${this.promptName}" not found. Ensure metadata has been synced to database.`);
+        }
+        // Execute with model/vendor overrides if specified in config
+        const result = await (0, prompt_helpers_1.executePromptWithOverrides)(prompt, schemaData, contextUser, this.config);
+        if (!result.success) {
+            throw new Error(`LLM grouping failed: ${result.errorMessage || 'Unknown error'}`);
+        }
+        if (!result.result) {
+            throw new Error('LLM did not return structured data');
+        }
+        return result.result;
+    }
+    /**
+     * Validate LLM output and convert to EntityGroup objects
+     */
+    validateAndConvertGroups(llmResponse, entities) {
+        const entityMap = new Map(entities.map(e => [e.Name, e]));
+        const validGroups = [];
+        for (const llmGroup of llmResponse.groups) {
+            try {
+                // Validate all entity names exist
+                const groupEntities = llmGroup.entities
+                    .map(name => entityMap.get(name))
+                    .filter((e) => e !== undefined);
+                if (groupEntities.length !== llmGroup.entities.length) {
+                    // Skip logging - verbose debug info that clutters output
+                    continue;
+                }
+                // Validate primary entity exists
+                const primaryEntity = entityMap.get(llmGroup.primaryEntity);
+                if (!primaryEntity) {
+                    // Skip logging - verbose debug info that clutters output
+                    continue;
+                }
+                // Build relationships array (collect all relationships between entities in the group)
+                const relationships = this.extractRelationships(groupEntities);
+                // Validate connectivity (all entities must be reachable from primary)
+                if (groupEntities.length > 1 && !this.isConnected(groupEntities, relationships)) {
+                    // Skip logging - verbose debug info that clutters output
+                    continue;
+                }
+                // Create EntityGroup with LLM metadata
+                validGroups.push({
+                    entities: groupEntities,
+                    relationships,
+                    primaryEntity,
+                    relationshipType: llmGroup.relationshipType,
+                    businessDomain: llmGroup.businessDomain,
+                    businessRationale: llmGroup.businessRationale,
+                    expectedQuestionTypes: llmGroup.expectedQuestionTypes
+                });
+            }
+            catch (error) {
+                // Skip logging - verbose debug info that clutters output
+            }
+        }
+        if (validGroups.length === 0) {
+            throw new Error('No valid entity groups generated by LLM');
+        }
+        return validGroups;
+    }
+    /**
+     * Extract relationships between entities in a group
+     */
+    extractRelationships(entities) {
+        const entityNames = new Set(entities.map(e => e.Name));
+        const relationships = [];
+        for (const entity of entities) {
+            for (const rel of entity.RelatedEntities) {
+                if (entityNames.has(rel.RelatedEntity)) {
+                    relationships.push(rel);
+                }
+            }
+        }
+        return relationships;
+    }
+    /**
+     * Check if all entities in a group are connected by relationships
+     *
+     * Uses BFS to verify all entities are reachable from the first entity
+     */
+    isConnected(entities, relationships) {
+        if (entities.length <= 1)
+            return true;
+        // Build adjacency map
+        const adjacency = new Map();
+        for (const entity of entities) {
+            adjacency.set(entity.Name, new Set());
+        }
+        for (const rel of relationships) {
+            const entityName = entities.find(e => e.RelatedEntities.includes(rel))?.Name;
+            if (entityName) {
+                adjacency.get(entityName)?.add(rel.RelatedEntity);
+                adjacency.get(rel.RelatedEntity)?.add(entityName); // Bidirectional
+            }
+        }
+        // BFS from first entity
+        const visited = new Set();
+        const queue = [entities[0].Name];
+        visited.add(entities[0].Name);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            const neighbors = adjacency.get(current) || new Set();
+            for (const neighbor of neighbors) {
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    queue.push(neighbor);
+                }
+            }
+        }
+        // All entities should be visited
+        return visited.size === entities.length;
+    }
+    /**
+     * Remove duplicate or highly similar groups
+     *
+     * Groups are considered duplicates if they contain the exact same set of entities
+     */
+    deduplicateGroups(groups) {
+        const seen = new Set();
+        const unique = [];
+        for (const group of groups) {
+            // Create normalized key (sorted entity names)
+            const key = group.entities.map(e => e.Name).sort().join('|');
+            if (!seen.has(key)) {
+                seen.add(key);
+                unique.push(group);
+            }
+        }
+        return unique;
+    }
+}
+exports.EntityGrouper = EntityGrouper;
+//# sourceMappingURL=EntityGrouper.js.map

package/dist/core/EntityGrouper.js.map

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

package/dist/core/MetadataExporter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * MetadataExporter - Exports validated queries to MJ metadata format
+ *
+ * Transforms validated queries into MemberJunction metadata JSON files
+ * that can be synced to the database using mj-sync.
+ */
+import { ValidatedQuery, ExportResult, QueryCategoryInfo } from '../data/schema';
+/**
+ * MetadataExporter class
+ * Exports validated queries to MJ metadata JSON format
+ */
+export declare class MetadataExporter {
+    /**
+     * Export queries to metadata JSON files
+     *
+     * Transforms validated queries into MemberJunction metadata format
+     * and writes them to timestamped JSON files:
+     * - .query-categories-{timestamp}.json for the categories
+     * - .queries-{timestamp}.json for the queries
+     *
+     * @param validatedQueries - Array of validated queries to export
+     * @param uniqueCategories - Pre-built unique categories for all queries
+     * @param outputDirectory - Directory to write the queries file
+     * @param outputCategoryDirectory - Optional directory for categories file (defaults to outputDirectory)
+     * @returns Export result with file path and query count
+     */
+    exportQueries(validatedQueries: ValidatedQuery[], uniqueCategories: QueryCategoryInfo[], outputDirectory: string, outputCategoryDirectory?: string): Promise<ExportResult>;
+    /**
+     * Transform a validated query into MJ metadata format
+     *
+     * Note: This method only creates the Query record.
+     * QueryFields and QueryParameters are automatically extracted
+     * by QueryEntity.server.ts using AI analysis of the SQL template.
+     * This happens asynchronously during the Save() operation.
+     *
+     * @param query - Validated query to transform
+     * @returns Query metadata record
+     */
+    private toQueryMetadata;
+    /**
+     * Transform a QueryCategoryInfo into MJ metadata format
+     *
+     * @param category - Category information
+     * @returns Category metadata record
+     */
+    private toCategoryMetadata;
+    /**
+     * Build category lookup string for metadata
+     * Uses multi-field lookup to uniquely identify categories in hierarchies
+     *
+     * For root categories: Name=X&ParentID=null
+     * For child categories: Name=X&Parent=Y (where Parent is the parent category name)
+     *
+     * @param category - Category information
+     * @returns Lookup string for CategoryID field
+     */
+    private buildCategoryLookup;
+}
+//# sourceMappingURL=MetadataExporter.d.ts.map

package/dist/core/MetadataExporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetadataExporter.d.ts","sourceRoot":"","sources":["../../src/core/MetadataExporter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,cAAc,EAAE,YAAY,EAAuB,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGtG;;;GAGG;AACH,qBAAa,gBAAgB;IAC3B;;;;;;;;;;;;;OAaG;IACG,aAAa,CACjB,gBAAgB,EAAE,cAAc,EAAE,EAClC,gBAAgB,EAAE,iBAAiB,EAAE,EACrC,eAAe,EAAE,MAAM,EACvB,uBAAuB,CAAC,EAAE,MAAM,GAC/B,OAAO,CAAC,YAAY,CAAC;IA0CxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,eAAe;IAoBvB;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAa1B;;;;;;;;;OASG;IACH,OAAO,CAAC,mBAAmB;CAS5B"}

package/dist/core/MetadataExporter.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * MetadataExporter - Exports validated queries to MJ metadata format
+ *
+ * Transforms validated queries into MemberJunction metadata JSON files
+ * that can be synced to the database using mj-sync.
+ */
+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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataExporter = void 0;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const query_helpers_1 = require("../utils/query-helpers");
+/**
+ * MetadataExporter class
+ * Exports validated queries to MJ metadata JSON format
+ */
+class MetadataExporter {
+    /**
+     * Export queries to metadata JSON files
+     *
+     * Transforms validated queries into MemberJunction metadata format
+     * and writes them to timestamped JSON files:
+     * - .query-categories-{timestamp}.json for the categories
+     * - .queries-{timestamp}.json for the queries
+     *
+     * @param validatedQueries - Array of validated queries to export
+     * @param uniqueCategories - Pre-built unique categories for all queries
+     * @param outputDirectory - Directory to write the queries file
+     * @param outputCategoryDirectory - Optional directory for categories file (defaults to outputDirectory)
+     * @returns Export result with file path and query count
+     */
+    async exportQueries(validatedQueries, uniqueCategories, outputDirectory, outputCategoryDirectory) {
+        // Generate shared timestamp for both files
+        const timestamp = Date.now();
+        // Use category directory if provided, otherwise use queries directory
+        const categoryDir = outputCategoryDirectory || outputDirectory;
+        // 1. Transform to MJ metadata format
+        const queryMetadata = validatedQueries.map(q => this.toQueryMetadata(q));
+        const categoryMetadata = uniqueCategories.map(c => this.toCategoryMetadata(c));
+        // 2. Ensure output directories exist
+        await fs_1.promises.mkdir(outputDirectory, { recursive: true });
+        if (categoryDir !== outputDirectory) {
+            await fs_1.promises.mkdir(categoryDir, { recursive: true });
+        }
+        // 3. Write categories file (if categories exist)
+        if (categoryMetadata.length > 0) {
+            const categoriesPath = path.join(categoryDir, `.query-categories-${timestamp}.json`);
+            await fs_1.promises.writeFile(categoriesPath, JSON.stringify(categoryMetadata, null, 2), 'utf-8');
+        }
+        // 4. Write queries file
+        const outputPath = path.join(outputDirectory, `.queries-${timestamp}.json`);
+        await fs_1.promises.writeFile(outputPath, JSON.stringify(queryMetadata, null, 2), 'utf-8');
+        return {
+            success: true,
+            outputPath,
+            queryCount: queryMetadata.length
+        };
+    }
+    /**
+     * Transform a validated query into MJ metadata format
+     *
+     * Note: This method only creates the Query record.
+     * QueryFields and QueryParameters are automatically extracted
+     * by QueryEntity.server.ts using AI analysis of the SQL template.
+     * This happens asynchronously during the Save() operation.
+     *
+     * @param query - Validated query to transform
+     * @returns Query metadata record
+     */
+    toQueryMetadata(query) {
+        // Build category lookup path (e.g., "Golden-Queries/Members" becomes lookup filter)
+        const categoryLookup = this.buildCategoryLookup(query.category);
+        return {
+            fields: {
+                Name: (0, query_helpers_1.generateQueryName)(query.businessQuestion),
+                CategoryID: categoryLookup,
+                UserQuestion: query.businessQuestion.userQuestion,
+                Description: query.businessQuestion.description,
+                TechnicalDescription: query.businessQuestion.technicalDescription,
+                SQL: query.query.sql,
+                OriginalSQL: query.query.sql,
+                UsesTemplate: true,
+                Status: 'Pending'
+            }
+            // relatedEntities removed - QueryEntity.server.ts handles extraction automatically
+        };
+    }
+    /**
+     * Transform a QueryCategoryInfo into MJ metadata format
+     *
+     * @param category - Category information
+     * @returns Category metadata record
+     */
+    toCategoryMetadata(category) {
+        return {
+            fields: {
+                Name: category.name,
+                ParentID: category.parentName
+                    ? `@lookup:Query Categories.Name=${category.parentName}`
+                    : null,
+                Description: category.description,
+                UserID: '@lookup:Users.Name=System'
+            }
+        };
+    }
+    /**
+     * Build category lookup string for metadata
+     * Uses multi-field lookup to uniquely identify categories in hierarchies
+     *
+     * For root categories: Name=X&ParentID=null
+     * For child categories: Name=X&Parent=Y (where Parent is the parent category name)
+     *
+     * @param category - Category information
+     * @returns Lookup string for CategoryID field
+     */
+    buildCategoryLookup(category) {
+        if (category.parentName) {
+            // Child category - use Name and Parent field (view field showing parent name)
+            return `@lookup:Query Categories.Name=${category.name}&Parent=${category.parentName}`;
+        }
+        else {
+            // Root category - use Name and ParentID=null
+            return `@lookup:Query Categories.Name=${category.name}&ParentID=null`;
+        }
+    }
+}
+exports.MetadataExporter = MetadataExporter;
+//# sourceMappingURL=MetadataExporter.js.map

package/dist/core/MetadataExporter.js.map

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

package/dist/core/QueryDatabaseWriter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * QueryDatabaseWriter - Write validated queries directly to the database
+ *
+ * Creates Query entities in the database. QueryFields and QueryParameters
+ * are automatically extracted by QueryEntity.server.ts using AI analysis
+ * of the SQL template during the Save() operation.
+ */
+import { UserInfo } from '@memberjunction/core';
+import { ValidatedQuery, WriteResult } from '../data/schema';
+/**
+ * QueryDatabaseWriter class
+ * Writes validated queries directly to the database
+ */
+export declare class QueryDatabaseWriter {
+    private categoryCache;
+    constructor();
+    /**
+     * Write validated queries to the database
+     *
+     * Creates Query entities. QueryFields and QueryParameters are automatically
+     * extracted by QueryEntity.server.ts using AI analysis of the SQL template.
+     * This happens asynchronously during the Save() operation.
+     *
+     * Errors for individual queries are logged but don't stop the batch process.
+     *
+     * @param validatedQueries - Array of validated queries to write
+     * @param contextUser - User context for entity operations
+     * @returns Write result with success status and per-query results
+     */
+    writeQueriesToDatabase(validatedQueries: ValidatedQuery[], contextUser: UserInfo): Promise<WriteResult>;
+    /**
+     * Get or create category ID from QueryCategoryInfo
+     * Uses caching to avoid repeated lookups/creations
+     * Ensures parent categories exist before creating children
+     */
+    private getCategoryId;
+    /**
+     * Find or create a query category
+     *
+     * Searches for an existing category with the given name and parent, or creates it if not found.
+     *
+     * @param categoryName - Name of the category to find or create
+     * @param parentCategoryId - Parent category ID (null for root categories)
+     * @param description - Description for new categories
+     * @param contextUser - User context for entity operations
+     * @returns Category ID
+     */
+    private findOrCreateCategory;
+}
+//# sourceMappingURL=QueryDatabaseWriter.d.ts.map

package/dist/core/QueryDatabaseWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryDatabaseWriter.d.ts","sourceRoot":"","sources":["../../src/core/QueryDatabaseWriter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAqB,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAKnE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI7D;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,aAAa,CAAkC;;IAKvD;;;;;;;;;;;;OAYG;IACG,sBAAsB,CAC1B,gBAAgB,EAAE,cAAc,EAAE,EAClC,WAAW,EAAE,QAAQ,GACpB,OAAO,CAAC,WAAW,CAAC;IA8CvB;;;;OAIG;YACW,aAAa;IAmC3B;;;;;;;;;;OAUG;YACW,oBAAoB;CA8CnC"}