outlet-orm 7.0.0 → 9.0.1

package/src/AI/AIQueryBuilder.js

@@ -0,0 +1,234 @@
+'use strict';
+
+/**
+ * AIQueryBuilder
+ * Natural Language → SQL conversion using any AiBridge provider.
+ * Introspects the database schema, sends it with the NL prompt to an LLM,
+ * and returns a safe, parameterized SQL query.
+ *
+ * @since 8.0.0
+ */
+class AIQueryBuilder {
+  /**
+   * @param {import('./AiBridgeManager')} manager - AiBridge manager instance
+   * @param {Object} connection - DatabaseConnection instance (outlet-orm)
+   */
+  constructor(manager, connection) {
+    this._manager = manager;
+    this._connection = connection;
+    this._provider = 'openai';
+    this._model = 'gpt-4o-mini';
+    this._safeMode = true;       // Only SELECT by default
+    this._maxTokens = 1024;
+  }
+
+  /**
+   * Set the provider and model to use.
+   * @param {string} provider
+   * @param {string} model
+   * @returns {this}
+   */
+  using(provider, model) {
+    this._provider = provider;
+    this._model = model;
+    return this;
+  }
+
+  /**
+   * Enable/disable safe mode (SELECT only).
+   * @param {boolean} safe
+   * @returns {this}
+   */
+  safeMode(safe) {
+    this._safeMode = safe;
+    return this;
+  }
+
+  /**
+   * Convert a natural language question to SQL and execute it.
+   * @param {string} question
+   * @param {Object} [options={}]
+   * @returns {Promise<{sql: string, params: Array, results: Array, raw_response: Object}>}
+   */
+  async query(question, options = {}) {
+    const schema = await this._introspectSchema();
+    const systemPrompt = this._buildSystemPrompt(schema);
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: question },
+    ];
+
+    const chatOptions = {
+      model: options.model || this._model,
+      max_tokens: options.max_tokens || this._maxTokens,
+      temperature: options.temperature || 0.1, // Low temp for SQL accuracy
+      response_format: 'json',
+      json_schema: {
+        name: 'sql_response',
+        schema: {
+          type: 'object',
+          properties: {
+            sql: { type: 'string' },
+            params: { type: 'array', items: {} },
+            explanation: { type: 'string' },
+          },
+          required: ['sql'],
+        },
+      },
+    };
+
+    const res = await this._manager.chat(this._provider, messages, chatOptions);
+    const parsed = this._extractSqlFromResponse(res);
+
+    // Safety check
+    if (this._safeMode && parsed.sql) {
+      const upper = parsed.sql.trim().toUpperCase();
+      if (!upper.startsWith('SELECT') && !upper.startsWith('WITH')) {
+        throw new Error(`AIQueryBuilder safe mode: only SELECT/WITH queries are allowed. Got: ${upper.slice(0, 20)}...`);
+      }
+    }
+
+    // Execute the query
+    let results = [];
+    if (parsed.sql && this._connection) {
+      try {
+        results = await this._connection.raw(parsed.sql, parsed.params || []);
+      } catch (err) {
+        return { sql: parsed.sql, params: parsed.params || [], results: [], error: err.message, raw_response: res };
+      }
+    }
+
+    return {
+      sql: parsed.sql || '',
+      params: parsed.params || [],
+      results,
+      explanation: parsed.explanation || '',
+      raw_response: res,
+    };
+  }
+
+  /**
+   * Generate SQL without executing it.
+   * @param {string} question
+   * @param {Object} [options={}]
+   * @returns {Promise<{sql: string, params: Array, explanation: string}>}
+   */
+  async toSql(question, options = {}) {
+    const schema = await this._introspectSchema();
+    const systemPrompt = this._buildSystemPrompt(schema);
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: question },
+    ];
+
+    const chatOptions = {
+      model: options.model || this._model,
+      max_tokens: options.max_tokens || this._maxTokens,
+      temperature: 0.1,
+      response_format: 'json',
+      json_schema: {
+        name: 'sql_response',
+        schema: {
+          type: 'object',
+          properties: {
+            sql: { type: 'string' },
+            params: { type: 'array', items: {} },
+            explanation: { type: 'string' },
+          },
+          required: ['sql'],
+        },
+      },
+    };
+
+    const res = await this._manager.chat(this._provider, messages, chatOptions);
+    const parsed = this._extractSqlFromResponse(res);
+    return { sql: parsed.sql || '', params: parsed.params || [], explanation: parsed.explanation || '' };
+  }
+
+  /** @private */
+  async _introspectSchema() {
+    if (!this._connection) return 'No database connection available.';
+    try {
+      const dialect = this._connection.config?.client || 'mysql';
+      let tables = [];
+      if (dialect === 'pg' || dialect === 'postgresql') {
+        const res = await this._connection.raw(
+          "SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_type = 'BASE TABLE'"
+        );
+        tables = (res.rows || res).map(r => r.table_name);
+      } else if (dialect === 'sqlite' || dialect === 'sqlite3') {
+        const res = await this._connection.raw(
+          "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"
+        );
+        tables = (Array.isArray(res) ? res : (res.rows || [])).map(r => r.name);
+      } else {
+        // MySQL
+        const res = await this._connection.raw('SHOW TABLES');
+        tables = (Array.isArray(res) ? res[0] || res : res).map(r => Object.values(r)[0]);
+      }
+
+      const schemaInfo = {};
+      for (const table of tables) {
+        try {
+          let cols;
+          if (dialect === 'pg' || dialect === 'postgresql') {
+            const cRes = await this._connection.raw(
+              `SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = '${table}'`
+            );
+            cols = (cRes.rows || cRes).map(c => `${c.column_name} ${c.data_type}${c.is_nullable === 'YES' ? ' NULL' : ''}`);
+          } else if (dialect === 'sqlite' || dialect === 'sqlite3') {
+            const cRes = await this._connection.raw(`PRAGMA table_info("${table}")`);
+            cols = (Array.isArray(cRes) ? cRes : []).map(c => `${c.name} ${c.type}${c.notnull ? '' : ' NULL'}`);
+          } else {
+            const cRes = await this._connection.raw(`DESCRIBE \`${table}\``);
+            cols = (Array.isArray(cRes) ? cRes[0] || cRes : cRes).map(c => `${c.Field} ${c.Type}${c.Null === 'YES' ? ' NULL' : ''}`);
+          }
+          schemaInfo[table] = cols;
+        } catch { schemaInfo[table] = ['(unable to read columns)']; }
+      }
+
+      return Object.entries(schemaInfo)
+        .map(([t, cols]) => `TABLE ${t}:\n  ${cols.join('\n  ')}`)
+        .join('\n\n');
+    } catch (err) {
+      return `Schema introspection error: ${err.message}`;
+    }
+  }
+
+  /** @private */
+  _buildSystemPrompt(schema) {
+    let prompt = `You are a SQL assistant. Given a natural language question and a database schema, generate a single SQL query that answers the question.
+
+DATABASE SCHEMA:
+${schema}
+
+RULES:
+- Return ONLY a JSON object with keys: "sql" (the query), "params" (array of parameterized values, can be empty), "explanation" (brief explanation).
+- Use parameterized queries (? placeholders) when appropriate for safety.
+- Do NOT use DROP, TRUNCATE, or ALTER statements.`;
+
+    if (this._safeMode) {
+      prompt += '\n- ONLY generate SELECT or WITH (CTE) queries. No INSERT, UPDATE, DELETE.';
+    }
+
+    return prompt;
+  }
+
+  /** @private */
+  _extractSqlFromResponse(res) {
+    // Try various response formats
+    let content = res?.output_text || res?.choices?.[0]?.message?.content || res?.content?.[0]?.text || res?.message?.content || '';
+    if (typeof content !== 'string') content = JSON.stringify(content);
+
+    try {
+      const parsed = JSON.parse(content);
+      return { sql: parsed.sql || '', params: parsed.params || [], explanation: parsed.explanation || '' };
+    } catch {
+      // Try to extract SQL from plain text
+      const sqlMatch = content.match(/```sql\s*([\s\S]*?)```/i) || content.match(/SELECT[\s\S]+?;/i);
+      return { sql: sqlMatch ? (sqlMatch[1] || sqlMatch[0]).trim() : content.trim(), params: [], explanation: '' };
+    }
+  }
+}
+
+module.exports = AIQueryBuilder;

package/src/AI/AIQueryOptimizer.js

@@ -0,0 +1,185 @@
+'use strict';
+
+/**
+ * AIQueryOptimizer
+ * Uses LLM to analyze and optimize SQL queries.
+ * Sends the query + schema to an AI provider and returns optimization suggestions.
+ *
+ * @since 8.0.0
+ */
+class AIQueryOptimizer {
+  /**
+   * @param {import('./AiBridgeManager')} manager
+   * @param {Object} [connection] - DatabaseConnection instance (optional, for schema introspection)
+   */
+  constructor(manager, connection = null) {
+    this._manager = manager;
+    this._connection = connection;
+    this._provider = 'openai';
+    this._model = 'gpt-4o-mini';
+  }
+
+  /**
+   * Set the provider and model to use.
+   * @param {string} provider
+   * @param {string} model
+   * @returns {this}
+   */
+  using(provider, model) {
+    this._provider = provider;
+    this._model = model;
+    return this;
+  }
+
+  /**
+   * Analyze a SQL query and return optimization suggestions.
+   * @param {string} sql - The SQL query to optimize
+   * @param {Object} [options={}]
+   * @returns {Promise<{original: string, optimized: string, suggestions: Array, explanation: string}>}
+   */
+  async optimize(sql, options = {}) {
+    const schema = options.schema || await this._introspectSchema();
+    const dialect = options.dialect || this._connection?.config?.client || 'mysql';
+
+    const systemPrompt = `You are a senior database performance engineer. Analyze SQL queries and provide optimizations.
+
+DATABASE DIALECT: ${dialect}
+${schema ? `\nDATABASE SCHEMA:\n${schema}` : ''}
+
+RULES:
+- Return a JSON object with keys:
+  "optimized" (the optimized SQL query),
+  "suggestions" (array of optimization suggestions, each with "type", "description", "impact"),
+  "explanation" (brief overall explanation),
+  "indexes" (array of recommended CREATE INDEX statements, if any).
+- Preserve query semantics — the optimized query must return the same results.
+- Consider: indexes, query rewriting, subquery elimination, JOIN optimization, proper use of LIMIT/OFFSET.
+- Rate impact as "high", "medium", or "low".`;
+
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: `Optimize this SQL query:\n\n${sql}` },
+    ];
+
+    const res = await this._manager.chat(this._provider, messages, {
+      model: options.model || this._model,
+      temperature: 0.2,
+      max_tokens: 2048,
+      response_format: 'json',
+      json_schema: {
+        name: 'optimization_result',
+        schema: {
+          type: 'object',
+          properties: {
+            optimized: { type: 'string' },
+            suggestions: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  type: { type: 'string' },
+                  description: { type: 'string' },
+                  impact: { type: 'string' },
+                },
+              },
+            },
+            explanation: { type: 'string' },
+            indexes: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['optimized', 'suggestions'],
+        },
+      },
+    });
+
+    const parsed = this._extractResult(res);
+    return {
+      original: sql,
+      optimized: parsed.optimized || sql,
+      suggestions: parsed.suggestions || [],
+      explanation: parsed.explanation || '',
+      indexes: parsed.indexes || [],
+      raw_response: res,
+    };
+  }
+
+  /**
+   * Analyze query execution plan using EXPLAIN.
+   * @param {string} sql
+   * @returns {Promise<{plan: Array, analysis: string}>}
+   */
+  async explain(sql) {
+    if (!this._connection) throw new Error('Database connection required for EXPLAIN.');
+    const dialect = this._connection.config?.client || 'mysql';
+
+    let plan;
+    if (dialect === 'pg' || dialect === 'postgresql') {
+      plan = await this._connection.raw(`EXPLAIN (FORMAT JSON) ${sql}`);
+    } else if (dialect === 'sqlite' || dialect === 'sqlite3') {
+      plan = await this._connection.raw(`EXPLAIN QUERY PLAN ${sql}`);
+    } else {
+      plan = await this._connection.raw(`EXPLAIN ${sql}`);
+    }
+
+    // Ask LLM to analyze the execution plan
+    const messages = [
+      { role: 'system', content: 'You are a database performance expert. Analyze this EXPLAIN plan and provide actionable insights.' },
+      { role: 'user', content: `EXPLAIN output for query "${sql}":\n\n${JSON.stringify(plan, null, 2)}` },
+    ];
+
+    const res = await this._manager.chat(this._provider, messages, {
+      model: this._model,
+      temperature: 0.2,
+      max_tokens: 1024,
+    });
+
+    const analysis = res?.output_text || res?.choices?.[0]?.message?.content || res?.content?.[0]?.text || '';
+    return { plan: Array.isArray(plan) ? plan : [plan], analysis };
+  }
+
+  /** @private */
+  async _introspectSchema() {
+    if (!this._connection) return '';
+    try {
+      const dialect = this._connection.config?.client || 'mysql';
+      let tables = [];
+      if (dialect === 'pg' || dialect === 'postgresql') {
+        const res = await this._connection.raw("SELECT table_name FROM information_schema.tables WHERE table_schema = 'public'");
+        tables = (res.rows || res).map(r => r.table_name);
+      } else if (dialect === 'sqlite' || dialect === 'sqlite3') {
+        const res = await this._connection.raw("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'");
+        tables = (Array.isArray(res) ? res : []).map(r => r.name);
+      } else {
+        const res = await this._connection.raw('SHOW TABLES');
+        tables = (Array.isArray(res) ? res[0] || res : res).map(r => Object.values(r)[0]);
+      }
+
+      const parts = [];
+      for (const table of tables.slice(0, 30)) { // Limit to 30 tables
+        try {
+          let cols;
+          if (dialect === 'pg' || dialect === 'postgresql') {
+            const cRes = await this._connection.raw(`SELECT column_name, data_type FROM information_schema.columns WHERE table_name = '${table}'`);
+            cols = (cRes.rows || cRes).map(c => `${c.column_name} ${c.data_type}`);
+          } else if (dialect === 'sqlite' || dialect === 'sqlite3') {
+            const cRes = await this._connection.raw(`PRAGMA table_info("${table}")`);
+            cols = (Array.isArray(cRes) ? cRes : []).map(c => `${c.name} ${c.type}`);
+          } else {
+            const cRes = await this._connection.raw(`DESCRIBE \`${table}\``);
+            cols = (Array.isArray(cRes) ? cRes[0] || cRes : cRes).map(c => `${c.Field} ${c.Type}`);
+          }
+          parts.push(`TABLE ${table}: ${cols.join(', ')}`);
+        } catch { /* skip */ }
+      }
+      return parts.join('\n');
+    } catch { return ''; }
+  }
+
+  /** @private */
+  _extractResult(res) {
+    let content = res?.output_text || res?.choices?.[0]?.message?.content || res?.content?.[0]?.text || res?.message?.content || '';
+    if (typeof content !== 'string') content = JSON.stringify(content);
+    try { return JSON.parse(content); } catch { return {}; }
+  }
+}
+
+module.exports = AIQueryOptimizer;

package/src/AI/AISeeder.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * AISeeder
+ * AI-powered data seeding that uses LLM to generate realistic, contextual seed data.
+ * Instead of hard-coded Faker data, asks the LLM to produce domain-specific records.
+ *
+ * @since 8.0.0
+ */
+class AISeeder {
+  /**
+   * @param {import('./AiBridgeManager')} manager
+   * @param {Object} connection - DatabaseConnection instance
+   */
+  constructor(manager, connection) {
+    this._manager = manager;
+    this._connection = connection;
+    this._provider = 'openai';
+    this._model = 'gpt-4o-mini';
+  }
+
+  /**
+   * Set the provider and model to use.
+   * @param {string} provider
+   * @param {string} model
+   * @returns {this}
+   */
+  using(provider, model) {
+    this._provider = provider;
+    this._model = model;
+    return this;
+  }
+
+  /**
+   * Generate and insert seed data for a table.
+   * @param {string} table - Table name
+   * @param {number} [count=10] - Number of records to generate
+   * @param {Object} [context={}] - Additional context (e.g., domain, constraints)
+   * @returns {Promise<{records: Array, inserted: number}>}
+   */
+  async seed(table, count = 10, context = {}) {
+    const schema = await this._getTableSchema(table);
+    const systemPrompt = this._buildSystemPrompt(table, schema, count, context);
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: `Generate ${count} realistic seed records for the "${table}" table.${context.description ? ' Context: ' + context.description : ''}` },
+    ];
+
+    const res = await this._manager.chat(this._provider, messages, {
+      model: this._model,
+      temperature: 0.8, // Higher temp for creative data
+      max_tokens: 4096,
+      response_format: 'json',
+      json_schema: {
+        name: 'seed_data',
+        schema: {
+          type: 'object',
+          properties: {
+            records: {
+              type: 'array',
+              items: { type: 'object' },
+            },
+          },
+          required: ['records'],
+        },
+      },
+    });
+
+    const records = this._extractRecords(res);
+
+    // Insert records
+    let inserted = 0;
+    if (records.length > 0 && this._connection) {
+      for (const record of records) {
+        try {
+          const columns = Object.keys(record);
+          const values = Object.values(record);
+          const placeholders = columns.map(() => '?').join(', ');
+          const sql = `INSERT INTO \`${table}\` (${columns.map(c => `\`${c}\``).join(', ')}) VALUES (${placeholders})`;
+          await this._connection.raw(sql, values);
+          inserted++;
+        } catch (err) {
+          // Skip records that fail (FK violations, etc.)
+          continue;
+        }
+      }
+    }
+
+    return { records, inserted };
+  }
+
+  /**
+   * Generate seed records without inserting them.
+   * @param {string} table
+   * @param {number} [count=10]
+   * @param {Object} [context={}]
+   * @returns {Promise<Array>}
+   */
+  async generate(table, count = 10, context = {}) {
+    const schema = await this._getTableSchema(table);
+    const systemPrompt = this._buildSystemPrompt(table, schema, count, context);
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: `Generate ${count} realistic seed records for the "${table}" table.${context.description ? ' Context: ' + context.description : ''}` },
+    ];
+
+    const res = await this._manager.chat(this._provider, messages, {
+      model: this._model,
+      temperature: 0.8,
+      max_tokens: 4096,
+      response_format: 'json',
+      json_schema: {
+        name: 'seed_data',
+        schema: {
+          type: 'object',
+          properties: {
+            records: { type: 'array', items: { type: 'object' } },
+          },
+          required: ['records'],
+        },
+      },
+    });
+
+    return this._extractRecords(res);
+  }
+
+  /** @private */
+  async _getTableSchema(table) {
+    if (!this._connection) return '(no connection)';
+    try {
+      const dialect = this._connection.config?.client || 'mysql';
+      if (dialect === 'pg' || dialect === 'postgresql') {
+        const res = await this._connection.raw(
+          `SELECT column_name, data_type, is_nullable, column_default FROM information_schema.columns WHERE table_name = '${table}' ORDER BY ordinal_position`
+        );
+        return (res.rows || res).map(c => `${c.column_name} ${c.data_type}${c.is_nullable === 'YES' ? ' NULL' : ' NOT NULL'}${c.column_default ? ' DEFAULT ' + c.column_default : ''}`).join('\n');
+      } else if (dialect === 'sqlite' || dialect === 'sqlite3') {
+        const res = await this._connection.raw(`PRAGMA table_info("${table}")`);
+        return (Array.isArray(res) ? res : []).map(c => `${c.name} ${c.type}${c.notnull ? ' NOT NULL' : ' NULL'}${c.dflt_value ? ' DEFAULT ' + c.dflt_value : ''}`).join('\n');
+      } else {
+        const res = await this._connection.raw(`DESCRIBE \`${table}\``);
+        return (Array.isArray(res) ? res[0] || res : res).map(c => `${c.Field} ${c.Type}${c.Null === 'YES' ? ' NULL' : ' NOT NULL'}${c.Default ? ' DEFAULT ' + c.Default : ''}${c.Extra ? ' ' + c.Extra : ''}`).join('\n');
+      }
+    } catch (err) {
+      return `(error: ${err.message})`;
+    }
+  }
+
+  /** @private */
+  _buildSystemPrompt(table, schema, count, context) {
+    return `You are a database seed data generator. Generate realistic, diverse, and contextually appropriate test data.
+
+TABLE: ${table}
+SCHEMA:
+${schema}
+
+RULES:
+- Return a JSON object with a "records" key containing an array of ${count} objects.
+- Each object should have keys matching the column names (exclude auto-increment id columns).
+- Use realistic names, emails, dates, etc. — not lorem ipsum.
+- Respect data types and constraints (NOT NULL, defaults).
+- Foreign key values should use integers 1-${Math.max(5, count)}.
+- Dates should be in ISO format (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS).
+${context.locale ? `- Use locale: ${context.locale}` : ''}
+${context.domain ? `- Domain context: ${context.domain}` : ''}`;
+  }
+
+  /** @private */
+  _extractRecords(res) {
+    let content = res?.output_text || res?.choices?.[0]?.message?.content || res?.content?.[0]?.text || res?.message?.content || '';
+    if (typeof content !== 'string') content = JSON.stringify(content);
+    try {
+      const parsed = JSON.parse(content);
+      return Array.isArray(parsed.records) ? parsed.records : (Array.isArray(parsed) ? parsed : []);
+    } catch {
+      return [];
+    }
+  }
+}
+
+module.exports = AISeeder;