@memberjunction/query-gen 0.0.1 → 2.126.1

package/src/core/QueryTester.ts

@@ -0,0 +1,264 @@
+/**
+ * QueryTester - Tests and validates SQL queries
+ *
+ * Renders Nunjucks templates with sample parameter values and executes
+ * queries against the database. Handles error fixing with retry loop.
+ */
+
+import * as nunjucks from 'nunjucks';
+import {
+  DatabaseProviderBase,
+  RunQuerySQLFilterManager,
+  UserInfo,
+  LogError,
+} from '@memberjunction/core';
+import { extractErrorMessage } from '../utils/error-handlers';
+import {
+  GeneratedQuery,
+  QueryTestResult,
+  EntityMetadataForPrompt,
+  BusinessQuestion,
+} from '../data/schema';
+import { QueryFixer } from './QueryFixer';
+import { QueryGenConfig } from '../cli/config';
+
+/**
+ * QueryTester class
+ * Tests SQL queries by rendering templates and executing against database
+ */
+export class QueryTester {
+  private nunjucksEnv: nunjucks.Environment;
+
+  constructor(
+    private dataProvider: DatabaseProviderBase,
+    private entityMetadata: EntityMetadataForPrompt[],
+    private businessQuestion: BusinessQuestion,
+    private contextUser: UserInfo,
+    private config: QueryGenConfig
+  ) {
+    // Initialize Nunjucks environment with SQL-safe filters
+    this.nunjucksEnv = new nunjucks.Environment(null, {
+      autoescape: false,
+      throwOnUndefined: true,
+      trimBlocks: true,
+      lstripBlocks: true,
+    });
+
+    // Add custom SQL-safe filters from RunQuerySQLFilterManager
+    const filterManager = RunQuerySQLFilterManager.Instance;
+    const filters = filterManager.getAllFilters();
+
+    for (const filter of filters) {
+      if (filter.implementation) {
+        this.nunjucksEnv.addFilter(filter.name, filter.implementation);
+      }
+    }
+  }
+
+  /**
+   * Test a query by rendering template with sample values and executing it
+   * Retries up to maxAttempts times, calling QueryFixer on failures
+   *
+   * @param query - Generated query to test
+   * @param maxAttempts - Maximum number of retry attempts (default: 5)
+   * @returns Test result with success status, SQL, and sample data
+   */
+  async testQuery(
+    query: GeneratedQuery,
+    maxAttempts: number = 5
+  ): Promise<QueryTestResult> {
+    let attempt = 0;
+    let lastError: string | undefined;
+    let currentQuery = query;
+
+    while (attempt < maxAttempts) {
+      attempt++;
+
+      try {
+        // 1. Render template with sample parameter values
+        const renderedSQL = this.renderQueryTemplate(currentQuery);
+
+        // 2. Execute SQL on database
+        const results = await this.executeSQLQuery(renderedSQL);
+
+        // 3. Success! (Empty results are valid - query executed without errors)
+        // Note: We don't validate rowCount because:
+        // - Empty results may indicate no data in database (not a query error)
+        // - Query structure can be correct even with zero rows returned
+        // - Testing should focus on SQL syntax/execution, not data presence
+        return {
+          success: true,
+          renderedSQL,
+          rowCount: results.length,
+          sampleRows: results.slice(0, 10), // Return first 10 rows
+          attempts: attempt,
+        };
+      } catch (error: unknown) {
+        lastError = extractErrorMessage(error, 'Query Testing');
+        if (this.config.verbose) {
+          LogError(`Attempt ${attempt}/${maxAttempts} failed: ${lastError}`);
+        }
+
+        // 5. If not last attempt, try to fix the query
+        if (attempt < maxAttempts) {
+          currentQuery = await this.fixQuery(currentQuery, lastError);
+        }
+      }
+    }
+
+    // Failed after max attempts
+    return {
+      success: false,
+      error: lastError,
+      attempts: maxAttempts,
+    };
+  }
+
+  /**
+   * Render query template with sample parameter values
+   * Uses QueryParameterProcessor for proper type handling
+   *
+   * @param query - Generated query with parameters
+   * @returns Rendered SQL string ready for execution
+   */
+  private renderQueryTemplate(query: GeneratedQuery): string {
+    // Build parameter values object
+    const paramValues: Record<string, unknown> = {};
+
+    for (const param of query.parameters) {
+      const rawValue = param.sampleValue;
+      if (rawValue !== undefined && rawValue !== null) {
+        paramValues[param.name] = this.processParameterValue(rawValue, param.type);
+      }
+    }
+
+    try {
+      // Render template using Nunjucks with SQL-safe filters
+      const renderedSQL = this.nunjucksEnv.renderString(query.sql, paramValues);
+      return renderedSQL;
+    } catch (error: unknown) {
+      throw new Error(
+        `Template rendering failed: ${extractErrorMessage(error, 'Nunjucks')}`
+      );
+    }
+  }
+
+  /**
+   * Processes a raw parameter value based on its type, handling special cases like arrays.
+   * Follows Skip-Brain pattern for parameter processing.
+   * For array types, this function will:
+   * - Parse JSON arrays if the value is a JSON string
+   * - Split comma-separated strings as a fallback
+   * - Return as-is for sqlIn filter to handle
+   *
+   * @param rawValue - The raw parameter value (from sampleValue)
+   * @param paramType - The parameter type ('string', 'number', 'date', 'boolean', 'array')
+   * @returns Processed value ready for use in Nunjucks template
+   */
+  private processParameterValue(rawValue: unknown, paramType: string): unknown {
+    if (rawValue === undefined || rawValue === null) {
+      return rawValue;
+    }
+
+    // For array type parameters, ensure value is compatible with sqlIn filter
+    if (paramType === 'array' && typeof rawValue === 'string') {
+      try {
+        // Try to parse as JSON array
+        const parsed = JSON.parse(rawValue);
+        if (Array.isArray(parsed)) {
+          return parsed;
+        }
+      } catch {
+        // Not valid JSON - return as-is for sqlIn filter to handle comma-separated strings
+      }
+      // Return comma-separated string as-is - sqlIn filter handles this
+      return rawValue;
+    }
+
+    // For non-array types, convert as needed
+    switch (paramType) {
+      case 'number':
+        if (typeof rawValue === 'string') {
+          const num = Number(rawValue);
+          if (isNaN(num)) {
+            throw new Error(`Invalid number sample value: ${rawValue}`);
+          }
+          return num;
+        }
+        return rawValue;
+
+      case 'boolean':
+        if (typeof rawValue === 'string') {
+          const lower = rawValue.toLowerCase();
+          if (lower !== 'true' && lower !== 'false') {
+            throw new Error(`Invalid boolean sample value: ${rawValue}`);
+          }
+          return lower === 'true';
+        }
+        return rawValue;
+
+      case 'date':
+        if (typeof rawValue === 'string') {
+          const date = new Date(rawValue);
+          if (isNaN(date.getTime())) {
+            throw new Error(`Invalid date sample value: ${rawValue}`);
+          }
+          return date;
+        }
+        return rawValue;
+
+      case 'string':
+      default:
+        return rawValue;
+    }
+  }
+
+  /**
+   * Execute SQL query against database
+   * Uses DataProvider to run query with contextUser
+   *
+   * @param sql - Rendered SQL query
+   * @returns Array of result rows
+   */
+  private async executeSQLQuery(sql: string): Promise<unknown[]> {
+    try {
+      const result = await this.dataProvider.ExecuteSQL(
+        sql,
+        undefined,
+        undefined,
+        this.contextUser
+      );
+
+      if (!result || !Array.isArray(result)) {
+        throw new Error('ExecuteSQL returned invalid result format');
+      }
+
+      return result;
+    } catch (error: unknown) {
+      throw new Error(
+        `SQL execution failed: ${extractErrorMessage(error, 'Database')}`
+      );
+    }
+  }
+
+  /**
+   * Fix a query that failed to execute
+   * Uses QueryFixer with AI to analyze error and generate correction
+   *
+   * @param query - Query that failed
+   * @param errorMessage - Error message from execution
+   * @returns Corrected query
+   */
+  private async fixQuery(
+    query: GeneratedQuery,
+    errorMessage: string
+  ): Promise<GeneratedQuery> {
+    const fixer = new QueryFixer(this.contextUser, this.config);
+    return await fixer.fixQuery(
+      query,
+      errorMessage,
+      this.entityMetadata,
+      this.businessQuestion
+    );
+  }
+}

package/src/core/QueryWriter.ts

@@ -0,0 +1,239 @@
+/**
+ * QueryWriter - Generates SQL query templates using AI with few-shot learning
+ *
+ * Uses the SQL Query Writer AI prompt to generate Nunjucks SQL templates
+ * based on business questions and similar golden query examples.
+ */
+
+import { AIEngine } from '@memberjunction/aiengine';
+import { AIPromptEntityExtended } from '@memberjunction/core-entities';
+import { UserInfo, LogStatus } from '@memberjunction/core';
+import { QueryGenConfig } from '../cli/config';
+import { extractErrorMessage } from '../utils/error-handlers';
+import { executePromptWithOverrides } from '../utils/prompt-helpers';
+import { BusinessQuestion, GeneratedQuery, EntityMetadataForPrompt, GoldenQuery } from '../data/schema';
+import { PROMPT_SQL_QUERY_WRITER } from '../prompts/PromptNames';
+
+/**
+ * QueryWriter class
+ * Generates Nunjucks SQL query templates using AI with few-shot learning
+ */
+export class QueryWriter {
+  constructor(
+    private contextUser: UserInfo,
+    private config: QueryGenConfig
+  ) {}
+
+  /**
+   * Generate SQL query template for a business question
+   * Uses few-shot learning with similar golden query examples
+   *
+   * @param businessQuestion - Business question to answer with SQL
+   * @param entityMetadata - Available entity metadata for query
+   * @param fewShotExamples - Similar golden queries for few-shot learning
+   * @returns Generated SQL query with parameters and output schema
+   */
+  async generateQuery(
+    businessQuestion: BusinessQuestion,
+    entityMetadata: EntityMetadataForPrompt[],
+    fewShotExamples: GoldenQuery[]
+  ): Promise<GeneratedQuery> {
+    try {
+      // Ensure AIEngine is configured
+      const aiEngine = AIEngine.Instance;
+      await aiEngine.Config(false, this.contextUser);
+
+      // Find the SQL Query Writer prompt
+      const prompt = this.findPromptByName(aiEngine, PROMPT_SQL_QUERY_WRITER);
+
+      // Prepare prompt data
+      const promptData = {
+        userQuestion: businessQuestion.userQuestion,
+        description: businessQuestion.description,
+        technicalDescription: businessQuestion.technicalDescription,
+        entityMetadata,
+        fewShotExamples,
+      };
+
+      // Execute AI prompt
+      const generatedQuery = await this.executePrompt(prompt, promptData);
+
+      // Validate the generated query structure
+      this.validateGeneratedQuery(generatedQuery);
+
+      return generatedQuery;
+    } catch (error: unknown) {
+      throw new Error(
+        extractErrorMessage(error, 'QueryWriter.generateQuery')
+      );
+    }
+  }
+
+  /**
+   * Find prompt by name in AIEngine cache
+   * Throws if prompt not found
+   */
+  private findPromptByName(
+    aiEngine: AIEngine,
+    promptName: string
+  ): AIPromptEntityExtended {
+    const prompt = aiEngine.Prompts.find((p) => p.Name === promptName);
+    if (!prompt) {
+      throw new Error(`Prompt '${promptName}' not found in AIEngine cache`);
+    }
+    return prompt;
+  }
+
+  /**
+   * Execute the SQL Query Writer AI prompt with retry logic for validation failures
+   * Parses JSON response and validates structure, retrying with feedback if validation fails
+   */
+  private async executePrompt(
+    prompt: AIPromptEntityExtended,
+    promptData: {
+      userQuestion: string;
+      description: string;
+      technicalDescription: string;
+      entityMetadata: EntityMetadataForPrompt[];
+      fewShotExamples: GoldenQuery[];
+    }
+  ): Promise<GeneratedQuery> {
+    const maxRetries = 3;
+    let lastError: Error | null = null;
+    let lastResult: GeneratedQuery | null = null;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        // Execute AI prompt
+        const result = await executePromptWithOverrides<GeneratedQuery>(
+          prompt,
+          promptData,
+          this.contextUser,
+          this.config
+        );
+
+        if (!result || !result.success) {
+          throw new Error(
+            `AI prompt execution failed: ${result?.errorMessage || 'Unknown error'}`
+          );
+        }
+
+        if (!result.result) {
+          throw new Error('AI prompt returned no result');
+        }
+
+        lastResult = result.result;
+
+        // Validate the generated query structure
+        // This will throw if validation fails
+        this.validateGeneratedQuery(lastResult);
+
+        // Validation passed, return the query
+        return lastResult;
+      } catch (error: unknown) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+
+        // If this is the last attempt, throw the error
+        if (attempt === maxRetries) {
+          throw new Error(
+            `Query generation failed after ${maxRetries + 1} attempts: ${lastError.message}`
+          );
+        }
+
+        // Log retry attempt
+        if (this.config.verbose) {
+          LogStatus(`⚠️ Query validation failed on attempt ${attempt + 1}/${maxRetries + 1}: ${lastError.message}`);
+          LogStatus(`   Retrying with validation feedback...`);
+        }
+
+        // Add validation feedback to the prompt data for next attempt
+        // This helps the LLM correct its mistakes
+        promptData = {
+          ...promptData,
+          // Add feedback about what went wrong
+          validationFeedback: `Previous attempt failed validation: ${lastError.message}. Please correct this issue.`,
+        } as typeof promptData & { validationFeedback: string };
+      }
+    }
+
+    // Should never reach here due to throw in loop, but TypeScript needs this
+    throw lastError || new Error('Query generation failed');
+  }
+
+  /**
+   * Validate generated query structure
+   * Ensures query has proper SQL template syntax and valid metadata
+   *
+   * @param query - Generated query to validate
+   * @throws Error if query structure is invalid
+   */
+  private validateGeneratedQuery(query: GeneratedQuery): void {
+    // Validate SQL is present
+    if (!query.sql || query.sql.trim().length === 0) {
+      throw new Error('Generated query has empty SQL');
+    }
+
+    // Validate SQL contains base view references (not raw tables)
+    if (!this.usesBaseViews(query.sql)) {
+      throw new Error('Generated SQL must use base views (vw*), not raw tables');
+    }
+
+    // Validate parameters array
+    if (!Array.isArray(query.parameters)) {
+      throw new Error('Generated query parameters must be an array');
+    }
+
+    // Validate each parameter
+    for (const param of query.parameters) {
+      this.validateParameter(param);
+    }
+  }
+
+  /**
+   * Check if SQL uses base views (vw* pattern)
+   * Basic heuristic: looks for view names in FROM and JOIN clauses
+   */
+  private usesBaseViews(sql: string): boolean {
+    // Look for view patterns like [schema].[vw...] or FROM vw...
+    const viewPattern = /\b(FROM|JOIN)\s+(\[\w+\]\.)?\[?vw\w+\]?/i;
+    return viewPattern.test(sql);
+  }
+
+  /**
+   * Validate a single query parameter
+   * Ensures all required fields are present and valid
+   */
+  private validateParameter(param: unknown): void {
+    if (!param || typeof param !== 'object') {
+      throw new Error('Query parameter must be an object');
+    }
+
+    const p = param as Record<string, unknown>;
+
+    if (!p.name || typeof p.name !== 'string') {
+      throw new Error('Query parameter must have a valid name');
+    }
+
+    if (!p.type || typeof p.type !== 'string') {
+      throw new Error(`Query parameter '${p.name}' must have a valid type`);
+    }
+
+    if (typeof p.isRequired !== 'boolean') {
+      throw new Error(`Query parameter '${p.name}' must have isRequired boolean`);
+    }
+
+    if (!p.description || typeof p.description !== 'string') {
+      throw new Error(`Query parameter '${p.name}' must have a description`);
+    }
+
+    if (!Array.isArray(p.usage)) {
+      throw new Error(`Query parameter '${p.name}' must have usage array`);
+    }
+
+    // sampleValue is required and can be string, number, boolean, or array depending on parameter type
+    if (p.sampleValue === undefined || p.sampleValue === null || p.sampleValue === '') {
+      throw new Error(`Query parameter '${p.name}' must have a sampleValue`);
+    }
+  }
+
+}

package/src/core/QuestionGenerator.ts

@@ -0,0 +1,199 @@
+/**
+ * QuestionGenerator - Generates business questions for entity groups using AI
+ *
+ * Uses the Business Question Generator AI prompt to create 1-2 meaningful
+ * business questions per entity group that can be answered with SQL.
+ */
+
+import { AIEngine } from '@memberjunction/aiengine';
+import { AIPromptEntityExtended } from '@memberjunction/core-entities';
+import { UserInfo, LogStatus } from '@memberjunction/core';
+import { QueryGenConfig } from '../cli/config';
+import { extractErrorMessage } from '../utils/error-handlers';
+import { formatEntityGroupForPrompt } from '../utils/entity-helpers';
+import { executePromptWithOverrides } from '../utils/prompt-helpers';
+import { EntityGroup, BusinessQuestion } from '../data/schema';
+import { PROMPT_BUSINESS_QUESTION_GENERATOR } from '../prompts/PromptNames';
+
+/**
+ * Result structure from Business Question Generator AI prompt
+ */
+interface QuestionGeneratorResult {
+  questions: BusinessQuestion[];
+}
+
+/**
+ * QuestionGenerator class
+ * Generates domain-specific business questions using AI
+ */
+export class QuestionGenerator {
+  constructor(
+    private contextUser: UserInfo,
+    private config: QueryGenConfig
+  ) {}
+
+  /**
+   * Generate business questions for an entity group
+   * Uses AI to create 1-2 meaningful questions per entity group
+   *
+   * @param entityGroup - Entity group to generate questions for
+   * @returns Array of validated business questions
+   */
+  async generateQuestions(entityGroup: EntityGroup): Promise<BusinessQuestion[]> {
+    try {
+      // Ensure AIEngine is configured
+      const aiEngine = AIEngine.Instance;
+      await aiEngine.Config(false, this.contextUser);
+
+      // Find the Business Question Generator prompt
+      const prompt = this.findPromptByName(aiEngine, PROMPT_BUSINESS_QUESTION_GENERATOR);
+
+      // Format entity group for prompt
+      const entityMetadata = formatEntityGroupForPrompt(entityGroup);
+
+      // Execute AI prompt
+      const result = await this.executePrompt(prompt, entityMetadata);
+
+      // Validate and filter questions
+      const totalGenerated = result.questions.length;
+      const validQuestions = this.validateQuestions(result.questions, entityGroup);
+
+      // Log if questions were filtered out
+      if (this.config.verbose && totalGenerated > validQuestions.length) {
+        LogStatus(
+          `QuestionGenerator: Filtered out ${totalGenerated - validQuestions.length} of ${totalGenerated} questions for ${entityGroup.primaryEntity.Name}`
+        );
+      }
+
+      // Warn if no valid questions generated
+      if (validQuestions.length === 0 && totalGenerated > 0) {
+        LogStatus(
+          `⚠️  QuestionGenerator: All ${totalGenerated} generated questions were filtered out for ${entityGroup.primaryEntity.Name}`
+        );
+      }
+
+      return validQuestions;
+    } catch (error: unknown) {
+      throw new Error(
+        extractErrorMessage(error, 'QuestionGenerator.generateQuestions')
+      );
+    }
+  }
+
+  /**
+   * Find prompt by name in AIEngine cache
+   * Throws if prompt not found
+   */
+  private findPromptByName(
+    aiEngine: AIEngine,
+    promptName: string
+  ): AIPromptEntityExtended {
+    const prompt = aiEngine.Prompts.find((p) => p.Name === promptName);
+    if (!prompt) {
+      throw new Error(`Prompt '${promptName}' not found in AIEngine cache`);
+    }
+    return prompt;
+  }
+
+  /**
+   * Execute the AI prompt with model/vendor overrides
+   * Parses JSON response and validates structure
+   */
+  private async executePrompt(
+    prompt: AIPromptEntityExtended,
+    entityMetadata: unknown
+  ): Promise<QuestionGeneratorResult> {
+    const result = await executePromptWithOverrides<QuestionGeneratorResult>(
+      prompt,
+      { entityGroupMetadata: entityMetadata },
+      this.contextUser,
+      this.config
+    );
+
+    if (!result || !result.success) {
+      throw new Error(`AI prompt execution failed: ${result?.errorMessage || 'Unknown error'}`);
+    }
+
+    if (!result.result) {
+      throw new Error('AI prompt returned no result');
+    }
+
+    return result.result;
+  }
+
+
+  /**
+   * Validate and filter business questions
+   * Removes low-quality or unanswerable questions
+   *
+   * @param questions - Raw questions from AI
+   * @param entityGroup - Entity group for validation context
+   * @returns Filtered array of valid questions
+   */
+  private validateQuestions(
+    questions: BusinessQuestion[],
+    entityGroup: EntityGroup
+  ): BusinessQuestion[] {
+    const entityNames = new Set(entityGroup.entities.map((e) => e.Name));
+
+    return questions.filter((q) => {
+      // Must have required fields
+      if (!this.hasRequiredFields(q)) {
+        return false;
+      }
+
+      // Must reference entities in the group
+      if (!this.referencesGroupEntities(q, entityNames)) {
+        return false;
+      }
+
+      // Must not be overly generic
+      if (this.isTooGeneric(q)) {
+        return false;
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Check if question has all required fields
+   */
+  private hasRequiredFields(question: BusinessQuestion): boolean {
+    return !!(
+      question.userQuestion &&
+      question.description &&
+      question.technicalDescription &&
+      question.complexity &&
+      Array.isArray(question.entities) &&
+      question.entities.length > 0
+    );
+  }
+
+  /**
+   * Check if question references entities in the group
+   */
+  private referencesGroupEntities(
+    question: BusinessQuestion,
+    entityNames: Set<string>
+  ): boolean {
+    return question.entities.some((entityName) => entityNames.has(entityName));
+  }
+
+  /**
+   * Check if question is too generic to be useful
+   */
+  private isTooGeneric(question: BusinessQuestion): boolean {
+    const genericPatterns = [
+      /show\s+me\s+all/i,
+      /list\s+all/i,
+      /get\s+all/i,
+      /display\s+all/i,
+      /^what\s+is/i,
+    ];
+
+    return genericPatterns.some((pattern) =>
+      pattern.test(question.userQuestion)
+    );
+  }
+}