@memberjunction/query-gen 0.0.1 → 2.126.1

package/src/utils/graph-helpers.ts

@@ -0,0 +1,99 @@
+/**
+ * Graph visualization and entity metadata formatting utilities
+ */
+
+import { EntityInfo } from '@memberjunction/core';
+
+/**
+ * Entity metadata formatted for LLM prompts (concise version)
+ */
+export interface EntityMetadataForPrompt {
+  Name: string;
+  Description: string;
+  SchemaName: string;
+  FieldCount: number;
+  RelatedEntities: Array<{ name: string; type: string }>;
+}
+
+/**
+ * Generates a simple text-based relationship graph for LLM prompts
+ *
+ * Output format:
+ * ```
+ * Customers: → Orders, → Addresses
+ * Orders: → OrderDetails, → Customers
+ * Products: → OrderDetails, → Categories
+ * ```
+ */
+export function generateRelationshipGraph(entities: EntityInfo[]): string {
+  const lines: string[] = [];
+
+  for (const entity of entities) {
+    if (entity.RelatedEntities.length === 0) {
+      lines.push(`${entity.Name}: (no relationships)`);
+      continue;
+    }
+
+    const relations = entity.RelatedEntities
+      .map(rel => `→ ${rel.RelatedEntity}`)
+      .join(', ');
+
+    lines.push(`${entity.Name}: ${relations}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generates a Mermaid diagram for richer visualization
+ *
+ * This can be used in prompts that support Mermaid syntax.
+ * Output format:
+ * ```mermaid
+ * graph LR
+ *   Customers[Customers] --> Orders[Orders]
+ *   Orders[Orders] --> OrderDetails[OrderDetails]
+ * ```
+ */
+export function generateMermaidDiagram(entities: EntityInfo[]): string {
+  const lines = ['graph LR'];
+  const processedPairs = new Set<string>();
+
+  for (const entity of entities) {
+    const safeEntityName = entity.Name.replace(/\s/g, '_');
+
+    for (const rel of entity.RelatedEntities) {
+      const safeRelatedName = rel.RelatedEntity.replace(/\s/g, '_');
+      const pairKey = [safeEntityName, safeRelatedName].sort().join('|');
+
+      if (!processedPairs.has(pairKey)) {
+        lines.push(`  ${safeEntityName}[${entity.Name}] --> ${safeRelatedName}[${rel.RelatedEntity}]`);
+        processedPairs.add(pairKey);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Formats entity metadata for LLM prompt (concise version with key info)
+ *
+ * Extracts only the essential information needed for entity grouping:
+ * - Entity name and description
+ * - Schema name
+ * - Field count (as a proxy for data richness)
+ * - Related entities with relationship types
+ */
+export function formatEntitiesForPrompt(entities: EntityInfo[]): EntityMetadataForPrompt[] {
+  return entities.map(entity => ({
+    Name: entity.Name,
+    Description: entity.Description || 'No description available',
+    SchemaName: entity.SchemaName || 'dbo',
+    FieldCount: entity.Fields.length,
+    RelatedEntities: entity.RelatedEntities.map(rel => ({
+      name: rel.RelatedEntity,
+      type: rel.Type
+    }))
+  }));
+}

package/src/utils/prompt-helpers.ts

@@ -0,0 +1,79 @@
+/**
+ * Prompt execution helpers with model/vendor override support
+ */
+
+import { AIPromptParams } from '@memberjunction/ai-core-plus';
+import { AIPromptRunner } from '@memberjunction/ai-prompts';
+import { UserInfo } from '@memberjunction/core';
+import { AIPromptEntityExtended } from '@memberjunction/core-entities';
+import { AIEngine } from '@memberjunction/aiengine';
+import { QueryGenConfig } from '../cli/config';
+
+/**
+ * Execute a prompt with optional model/vendor overrides from QueryGenConfig
+ *
+ * Uses AIPromptParams.override parameter to apply runtime model/vendor overrides.
+ * If config specifies modelOverride or vendorOverride, looks up their IDs from
+ * the AIEngine cache and passes them to the prompt execution.
+ *
+ * @param prompt - The AI prompt to execute (from AIEngine.Instance.Prompts)
+ * @param data - Data to pass to the prompt template
+ * @param contextUser - User context for server-side operations
+ * @param config - QueryGen configuration (for model/vendor overrides)
+ * @returns Promise resolving to the prompt result
+ */
+export async function executePromptWithOverrides<T>(
+  prompt: AIPromptEntityExtended,
+  data: Record<string, unknown>,
+  contextUser: UserInfo,
+  config: QueryGenConfig
+): Promise<{ success: boolean; result?: T; errorMessage?: string }> {
+  const promptParams = new AIPromptParams();
+  promptParams.prompt = prompt;
+  promptParams.data = data;
+  promptParams.contextUser = contextUser;
+  promptParams.skipValidation = false;
+
+  // Apply model/vendor overrides using built-in AIPromptParams.override
+  if (config.modelOverride || config.vendorOverride) {
+    const overrideIds = resolveModelVendorOverrides(config);
+    if (overrideIds.modelId || overrideIds.vendorId) {
+      promptParams.override = overrideIds;
+    }
+  }
+
+  const runner = new AIPromptRunner();
+  return await runner.ExecutePrompt<T>(promptParams);
+}
+
+/**
+ * Resolve model/vendor names to IDs for AIPromptParams.override
+ *
+ * Looks up model and vendor by name in the AIEngine cache (already loaded).
+ *
+ * @param config - QueryGen configuration with modelOverride/vendorOverride names
+ * @returns Object with modelId and/or vendorId, or empty object if none found
+ */
+function resolveModelVendorOverrides(
+  config: QueryGenConfig
+): { modelId?: string; vendorId?: string } {
+  const result: { modelId?: string; vendorId?: string } = {};
+
+  // Look up model ID from AIEngine cache if modelOverride is set
+  if (config.modelOverride) {
+    const model = AIEngine.Instance.Models.find(m => m.Name === config.modelOverride);
+    if (model && model.ID) {
+      result.modelId = model.ID;
+    }
+  }
+
+  // Look up vendor ID from AIEngine cache if vendorOverride is set
+  if (config.vendorOverride) {
+    const vendor = AIEngine.Instance.Vendors.find(v => v.Name === config.vendorOverride);
+    if (vendor && vendor.ID) {
+      result.vendorId = vendor.ID;
+    }
+  }
+
+  return result;
+}

package/src/utils/query-helpers.ts

@@ -0,0 +1,32 @@
+/**
+ * Query generation utility functions
+ */
+
+import { BusinessQuestion } from '../data/schema';
+
+/**
+ * Generate a query name from a business question
+ *
+ * Removes question marks, filters short words, capitalizes each word,
+ * and limits to 5 words for a concise query name.
+ *
+ * @param question - The business question to convert
+ * @returns A formatted query name
+ *
+ * @example
+ * generateQueryName({ userQuestion: "What are the top customers by revenue?" })
+ * // Returns: "What Are Top Customers Revenue"
+ *
+ * @example
+ * generateQueryName({ userQuestion: "Show me all active users" })
+ * // Returns: "Show All Active Users"
+ */
+export function generateQueryName(question: BusinessQuestion): string {
+  return question.userQuestion
+    .replace(/\?/g, '')
+    .split(' ')
+    .filter(word => word.length > 2)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .slice(0, 5)
+    .join(' ');
+}

package/src/utils/user-helpers.ts

@@ -0,0 +1,39 @@
+/**
+ * User helper utilities for QueryGen CLI operations
+ */
+
+import { UserInfo } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/sqlserver-dataprovider';
+
+/**
+ * Get the system user from UserCache
+ *
+ * The System user is populated in the UserCache when the database provider is initialized.
+ * This user is used for CLI operations where no specific user context exists.
+ *
+ * @returns The System UserInfo object from the cache
+ * @throws Error if System user is not found in cache or doesn't have Developer role
+ */
+export function getSystemUser(): UserInfo {
+  const sysUser = UserCache.Instance.UserByName("System", false);
+  if (!sysUser) {
+    throw new Error(
+      "System user not found in cache. Ensure the database provider is initialized " +
+      "before running QueryGen commands (e.g., via 'mj querygen' which initializes the provider)."
+    );
+  }
+
+  // Check if the System user has the Developer role
+  const hasDeveloperRole = sysUser.UserRoles && sysUser.UserRoles.some(
+    userRole => userRole.Role.trim().toLowerCase() === 'developer'
+  );
+
+  if (!hasDeveloperRole) {
+    throw new Error(
+      "System user does not have the 'Developer' role. " +
+      "The System user must have the Developer role to perform QueryGen operations."
+    );
+  }
+
+  return sysUser;
+}

package/src/vectors/EmbeddingService.ts

@@ -0,0 +1,109 @@
+/**
+ * EmbeddingService - Generates embeddings for queries and golden queries
+ *
+ * Wraps AIEngine embedding functionality for QueryGen use cases.
+ * Generates embeddings for multiple fields (name, userQuestion, description, technicalDescription).
+ */
+
+import { AIEngine } from '@memberjunction/aiengine';
+import { QueryEmbeddings, GoldenQuery, EmbeddedGoldenQuery } from '../data/schema';
+
+/**
+ * Service for generating embeddings using AI Engine
+ */
+export class EmbeddingService {
+  private readonly modelName: string;
+
+  /**
+   * Create an EmbeddingService with the specified embedding model
+   *
+   * @param modelName - Name of the embedding model to use (default: 'text-embedding-3-small')
+   */
+  constructor(modelName: string = 'text-embedding-3-small') {
+    this.modelName = modelName;
+  }
+
+  /**
+   * Embed a single query by generating embeddings for all its fields
+   *
+   * Generates separate embeddings for:
+   * - userQuestion: Natural language question
+   * - description: High-level description
+   * - technicalDescription: Technical implementation details
+   *
+   * @param query - Query to embed (partial structure with text fields)
+   * @returns Embeddings for all fields
+   */
+  async embedQuery(query: {
+    userQuestion: string;
+    description: string;
+    technicalDescription: string;
+  }): Promise<QueryEmbeddings> {
+    const aiEngine = AIEngine.Instance;
+
+    // Generate embeddings for each field in parallel
+    const [userQuestionResult, descResult, techDescResult] = await Promise.all([
+      aiEngine.EmbedTextLocal(query.userQuestion),
+      aiEngine.EmbedTextLocal(query.description),
+      aiEngine.EmbedTextLocal(query.technicalDescription),
+    ]);
+
+    return {
+      userQuestion: userQuestionResult.result.vector,
+      description: descResult.result.vector,
+      technicalDescription: techDescResult.result.vector,
+    };
+  }
+
+  /**
+   * Embed all golden queries for few-shot learning
+   *
+   * Golden queries are example queries that serve as few-shot learning examples.
+   * This method embeds all fields of all golden queries for similarity search.
+   * Note: name field is excluded from embeddings as it's not available during query generation.
+   *
+   * @param goldenQueries - Array of golden queries to embed
+   * @returns Array of golden queries with their embeddings
+   */
+  async embedGoldenQueries(goldenQueries: GoldenQuery[]): Promise<EmbeddedGoldenQuery[]> {
+    const embedded: EmbeddedGoldenQuery[] = [];
+
+    for (const query of goldenQueries) {
+      const embeddings = await this.embedQuery({
+        userQuestion: query.userQuestion,
+        description: query.description,
+        technicalDescription: query.technicalDescription,
+      });
+
+      embedded.push({
+        query,
+        embeddings,
+      });
+    }
+
+    return embedded;
+  }
+
+  /**
+   * Embed multiple queries in batch
+   *
+   * @param queries - Array of queries to embed
+   * @returns Array of embeddings corresponding to input queries
+   */
+  async embedQueries(
+    queries: Array<{
+      userQuestion: string;
+      description: string;
+      technicalDescription: string;
+    }>
+  ): Promise<QueryEmbeddings[]> {
+    const embeddings: QueryEmbeddings[] = [];
+
+    for (const query of queries) {
+      const embedding = await this.embedQuery(query);
+      embeddings.push(embedding);
+    }
+
+    return embeddings;
+  }
+}

package/src/vectors/SimilaritySearch.ts

@@ -0,0 +1,108 @@
+/**
+ * SimilaritySearch - Finds similar golden queries using weighted cosine similarity
+ *
+ * Implements weighted similarity search across multiple fields (name, userQuestion,
+ * description, technicalDescription) to find the most relevant few-shot examples.
+ */
+
+import { QueryEmbeddings, EmbeddedGoldenQuery, SimilarQuery } from '../data/schema';
+import { SimpleVectorService } from '@memberjunction/ai-vectors-memory';
+
+/**
+ * Field weights for weighted similarity calculation
+ * Note: name is excluded since queries don't have names until after generation
+ */
+interface FieldWeights {
+  userQuestion: number;
+  description: number;
+  technicalDescription: number;
+}
+
+/**
+ * SimilaritySearch class
+ * Finds most similar golden queries using weighted cosine similarity across multiple fields
+ */
+export class SimilaritySearch extends SimpleVectorService {
+  /**
+   * Weights for each field in similarity calculation
+   * Total weights sum to 1.0
+   *
+   * Weight distribution prioritizes technical specifications:
+   * - userQuestion: 0.20 (less important - natural language is variable)
+   * - description: 0.40 (high-level business logic matching)
+   * - technicalDescription: 0.40 (technical implementation details)
+   */
+  private readonly weights: FieldWeights = {
+    userQuestion: 0.20,
+    description: 0.40,
+    technicalDescription: 0.40
+  };
+
+  /**
+   * Find similar golden queries using weighted cosine similarity
+   *
+   * Calculates similarity for each field separately, then combines with weights.
+   * ALWAYS returns topK results, even if below threshold (threshold is informational).
+   *
+   * @param queryEmbeddings - Embeddings for the user's query (one per field)
+   * @param goldenEmbeddings - Array of golden queries with their embeddings
+   * @param topK - Number of most similar queries to return (default: 5)
+   * @returns Array of top-K most similar golden queries with scores
+   */
+  async findSimilarQueries(
+    queryEmbeddings: QueryEmbeddings,
+    goldenEmbeddings: EmbeddedGoldenQuery[],
+    topK: number = 5
+  ): Promise<SimilarQuery[]> {
+    // Calculate weighted similarity for each golden query
+    const similarities = goldenEmbeddings.map(golden => {
+      const fieldScores = this.calculateFieldSimilarities(queryEmbeddings, golden.embeddings);
+      const weightedScore = this.calculateWeightedScore(fieldScores);
+
+      return {
+        query: golden.query,
+        similarity: weightedScore,
+        fieldScores
+      };
+    });
+
+    // Sort by similarity (highest first) and return top K
+    return this.selectTopK(similarities, topK);
+  }
+
+  /**
+   * Calculate cosine similarity for each field separately
+   * Note: name field excluded as queries don't have names during generation
+   */
+  private calculateFieldSimilarities(
+    queryEmbeddings: QueryEmbeddings,
+    goldenEmbeddings: QueryEmbeddings
+  ): SimilarQuery['fieldScores'] {
+    return {
+      userQuestionSim: this.CosineSimilarity(queryEmbeddings.userQuestion, goldenEmbeddings.userQuestion),
+      descSim: this.CosineSimilarity(queryEmbeddings.description, goldenEmbeddings.description),
+      techDescSim: this.CosineSimilarity(queryEmbeddings.technicalDescription, goldenEmbeddings.technicalDescription)
+    };
+  }
+
+  /**
+   * Calculate weighted sum of field similarities
+   * Note: name field excluded, weights adjusted accordingly
+   */
+  private calculateWeightedScore(fieldScores: SimilarQuery['fieldScores']): number {
+    return (
+      fieldScores.userQuestionSim * this.weights.userQuestion +
+      fieldScores.descSim * this.weights.description +
+      fieldScores.techDescSim * this.weights.technicalDescription
+    );
+  }
+
+  /**
+   * Select top K results sorted by similarity
+   */
+  private selectTopK(similarities: SimilarQuery[], topK: number): SimilarQuery[] {
+    return similarities
+      .sort((a, b) => b.similarity - a.similarity)
+      .slice(0, topK);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node",
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "strictFunctionTypes": true,
+    "strictBindCallApply": true,
+    "strictPropertyInitialization": true,
+    "noImplicitThis": true,
+    "alwaysStrict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.spec.ts",
+    "**/*.test.ts"
+  ]
+}