outlet-orm 7.0.0 → 9.0.0

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;

package/src/AI/AiBridgeManager.js

@@ -0,0 +1,287 @@
+'use strict';
+
+const OpenAIProvider = require('./Providers/OpenAIProvider');
+const OllamaProvider = require('./Providers/OllamaProvider');
+const OllamaTurboProvider = require('./Providers/OllamaTurboProvider');
+const OnnProvider = require('./Providers/OnnProvider');
+const GeminiProvider = require('./Providers/GeminiProvider');
+const GrokProvider = require('./Providers/GrokProvider');
+const ClaudeProvider = require('./Providers/ClaudeProvider');
+const MistralProvider = require('./Providers/MistralProvider');
+const CustomOpenAIProvider = require('./Providers/CustomOpenAIProvider');
+const ProviderError = require('./Support/Exceptions/ProviderError');
+const ToolRegistry = require('./Support/ToolRegistry');
+const ToolChatRunner = require('./Support/ToolChatRunner');
+
+const BEARER_PREFIX = 'Bearer ';
+
+/**
+ * AiBridgeManager
+ * Central orchestrator for all AI providers. Supports provider registration,
+ * per-call overrides, capability delegation (chat, stream, embeddings, images,
+ * audio, models), tool registration, and chatWithTools loop.
+ */
+class AiBridgeManager {
+  /**
+   * @param {Object} config
+   */
+  constructor(config = {}) {
+    this._providers = {};
+    this._toolRegistry = new ToolRegistry();
+    this._options = config.options || {};
+
+    // Auto-register providers from config
+    if (config.openai?.api_key) {
+      this._providers.openai = new OpenAIProvider(config.openai.api_key);
+    }
+    if (config.ollama?.endpoint) {
+      this._providers.ollama = new OllamaProvider(config.ollama.endpoint);
+    }
+    if (config.ollama_turbo?.api_key) {
+      const ep = config.ollama_turbo.endpoint || 'https://ollama.com';
+      this._providers.ollama_turbo = new OllamaTurboProvider(config.ollama_turbo.api_key, ep);
+    }
+    if (config.onn?.api_key) {
+      this._providers.onn = new OnnProvider(config.onn.api_key);
+    }
+    if (config.gemini?.api_key) {
+      this._providers.gemini = new GeminiProvider(config.gemini.api_key);
+    }
+    if (config.grok?.api_key) {
+      this._providers.grok = new GrokProvider(config.grok.api_key);
+    }
+    if (config.claude?.api_key) {
+      this._providers.claude = new ClaudeProvider(config.claude.api_key);
+    }
+    if (config.mistral?.api_key) {
+      const ep = config.mistral.endpoint || 'https://api.mistral.ai/v1/chat/completions';
+      this._providers.mistral = new MistralProvider(config.mistral.api_key, ep);
+    }
+    if (config.openai_custom?.api_key && config.openai_custom?.base_url) {
+      const c = config.openai_custom;
+      this._providers.openai_custom = new CustomOpenAIProvider(
+        c.api_key, c.base_url, c.paths || {},
+        c.auth_header || 'Authorization', c.auth_prefix || BEARER_PREFIX,
+        c.extra_headers || {}
+      );
+    }
+    // OpenRouter (OpenAI-compatible)
+    if (config.openrouter?.api_key) {
+      const base = config.openrouter.base_url || 'https://openrouter.ai/api/v1';
+      const hdrs = {};
+      if (config.openrouter.referer) hdrs['HTTP-Referer'] = config.openrouter.referer;
+      if (config.openrouter.title) hdrs['X-Title'] = config.openrouter.title;
+      this._providers.openrouter = new CustomOpenAIProvider(
+        config.openrouter.api_key, base,
+        { chat: '/chat/completions', embeddings: '/embeddings', image: '/images/generations', tts: '/audio/speech', stt: '/audio/transcriptions' },
+        'Authorization', BEARER_PREFIX, hdrs
+      );
+    }
+  }
+
+  // ─── Provider resolution ───
+
+  /** @private */
+  _hasOverrides(options) {
+    const keys = ['api_key', 'endpoint', 'base_url', 'chat_endpoint', 'auth_header', 'auth_prefix', 'paths', 'extra_headers'];
+    return keys.some(k => options[k] !== undefined);
+  }
+
+  /** @private */
+  _buildProviderFromOptions(name, options) {
+    switch (name) {
+      case 'openai': {
+        const api = options.api_key;
+        if (api) return new OpenAIProvider(api, options.chat_endpoint || 'https://api.openai.com/v1/chat/completions');
+        break;
+      }
+      case 'ollama': return new OllamaProvider(options.endpoint || 'http://localhost:11434');
+      case 'ollama_turbo': {
+        const api = options.api_key;
+        if (api) return new OllamaTurboProvider(api, options.endpoint || 'https://ollama.com');
+        break;
+      }
+      case 'onn': {
+        const api = options.api_key;
+        if (api) return new OnnProvider(api, options.endpoint || 'https://api.onn.ai/v1/chat');
+        break;
+      }
+      case 'gemini': {
+        const api = options.api_key;
+        if (api) return new GeminiProvider(api, options.endpoint);
+        break;
+      }
+      case 'grok': {
+        const api = options.api_key;
+        if (api) return new GrokProvider(api, options.endpoint);
+        break;
+      }
+      case 'claude': {
+        const api = options.api_key;
+        if (api) return new ClaudeProvider(api, options.endpoint);
+        break;
+      }
+      case 'mistral': {
+        const api = options.api_key;
+        if (api) return new MistralProvider(api, options.endpoint || 'https://api.mistral.ai/v1/chat/completions');
+        break;
+      }
+      case 'openai_custom': {
+        const api = options.api_key;
+        const base = options.base_url;
+        if (api && base) {
+          return new CustomOpenAIProvider(api, base, options.paths || {},
+            options.auth_header || 'Authorization', options.auth_prefix || BEARER_PREFIX,
+            options.extra_headers || {});
+        }
+        break;
+      }
+      case 'openrouter': {
+        const api = options.api_key;
+        if (api) {
+          const base = options.base_url || 'https://openrouter.ai/api/v1';
+          const hdrs = {};
+          if (options.referer) hdrs['HTTP-Referer'] = options.referer;
+          if (options.title) hdrs['X-Title'] = options.title;
+          return new CustomOpenAIProvider(api, base,
+            { chat: '/chat/completions', embeddings: '/embeddings', image: '/images/generations', tts: '/audio/speech', stt: '/audio/transcriptions' },
+            'Authorization', BEARER_PREFIX, hdrs
+          );
+        }
+        break;
+      }
+    }
+    return null;
+  }
+
+  /** @private */
+  _resolveProvider(name, options = {}) {
+    if (this._hasOverrides(options)) {
+      const p = this._buildProviderFromOptions(name, options);
+      if (p) return p;
+    }
+    if (this._providers[name]) return this._providers[name];
+    const p = this._buildProviderFromOptions(name, options);
+    if (p) { this._providers[name] = p; }
+    return p || null;
+  }
+
+  // ─── Public API ───
+
+  /**
+   * Get a registered provider by name.
+   * @param {string} name
+   * @returns {Object|null}
+   */
+  provider(name) {
+    return this._providers[name] || null;
+  }
+
+  /**
+   * Register a provider instance.
+   * @param {string} name
+   * @param {Object} provider
+   * @returns {this}
+   */
+  registerProvider(name, provider) {
+    this._providers[name] = provider;
+    return this;
+  }
+
+  // ─── Chat ───
+  async chat(provider, messages, options = {}) {
+    const p = this._resolveProvider(provider, options);
+    if (!p || typeof p.chat !== 'function') throw ProviderError.unsupported(provider, 'chat');
+    return p.chat(messages, options);
+  }
+
+  // ─── Stream ───
+  async *stream(provider, messages, options = {}) {
+    const p = this._resolveProvider(provider, options);
+    if (!p || typeof p.stream !== 'function') throw ProviderError.unsupported(provider, 'streaming');
+    yield* p.stream(messages, options);
+  }
+
+  // ─── Stream Events ───
+  async *streamEvents(provider, messages, options = {}) {
+    const p = this._resolveProvider(provider, options);
+    if (!p || typeof p.supportsStreaming !== 'function' || !p.supportsStreaming()) {
+      throw ProviderError.unsupported(provider, 'streaming');
+    }
+    if (typeof p.streamEvents === 'function') {
+      yield* p.streamEvents(messages, options);
+      return;
+    }
+    for await (const chunk of p.stream(messages, options)) {
+      yield { type: 'delta', data: chunk };
+    }
+    yield { type: 'end', data: null };
+  }
+
+  // ─── Embeddings ───
+  async embeddings(provider, inputs, options = {}) {
+    const p = this._resolveProvider(provider, options);
+    if (!p || typeof p.embeddings !== 'function') throw ProviderError.unsupported(provider, 'embeddings');
+    return p.embeddings(inputs, options);
+  }
+
+  // ─── Models ───
+  async models(provider) {
+    const p = this._providers[provider];
+    if (!p || typeof p.listModels !== 'function') throw ProviderError.unsupported(provider, 'models');
+    return p.listModels();
+  }
+
+  async model(provider, id) {
+    const p = this._providers[provider];
+    if (!p || typeof p.getModel !== 'function') throw ProviderError.unsupported(provider, 'model');
+    return p.getModel(id);
+  }
+
+  // ─── Images ───
+  async image(provider, prompt, options = {}) {
+    const p = this._resolveProvider(provider, options);
+    if (!p || typeof p.generateImage !== 'function') throw ProviderError.unsupported(provider, 'image');
+    return p.generateImage(prompt, options);
+  }
+
+  // ─── Audio ───
+  async tts(provider, text, options = {}) {
+    const p = this._resolveProvider(provider, options);
+    if (!p || typeof p.textToSpeech !== 'function') throw ProviderError.unsupported(provider, 'tts');
+    return p.textToSpeech(text, options);
+  }
+
+  async stt(provider, filePath, options = {}) {
+    const p = this._resolveProvider(provider, options);
+    if (!p || typeof p.speechToText !== 'function') throw ProviderError.unsupported(provider, 'stt');
+    return p.speechToText(filePath, options);
+  }
+
+  // ─── Fluent builder ───
+  text() {
+    const TextBuilder = require('./Builders/TextBuilder');
+    return new TextBuilder(this);
+  }
+
+  // ─── Tools API ───
+  registerTool(tool) {
+    this._toolRegistry.register(tool);
+    return this;
+  }
+
+  tool(name) {
+    return this._toolRegistry.get(name);
+  }
+
+  tools() {
+    return this._toolRegistry.all();
+  }
+
+  async chatWithTools(provider, messages, options = {}) {
+    const runner = new ToolChatRunner(this);
+    return runner.run(provider, messages, options);
+  }
+}
+
+module.exports = AiBridgeManager;