outlet-orm 7.0.0 → 9.0.0

package/README.md

@@ -197,7 +197,14 @@ async store(req, res) {
 - **Raw queries**: `executeRawQuery()` and `execute()` (native driver results)
 - **Complete Migrations** (create/alter/drop, index, foreign keys, batch tracking)
 - **Database Backup** (v6.0.0): full/partial/journal backups, recurring scheduler, AES-256-GCM encryption, TCP daemon + remote client, automatic restore
-- **Handy CLI tools**: `outlet-init`, `outlet-migrate`, `outlet-convert`
+- **🤖 AiBridge** (v8.0.0): Multi-provider LLM abstraction — chat, stream, embeddings, images, TTS, STT with 9+ providers
+- **🤖 AI Query Builder** (v8.0.0): Natural language → SQL with schema introspection
+- **🤖 AI Seeder** (v8.0.0): LLM-powered realistic, domain-specific data generation
+- **🤖 AI Query Optimizer** (v8.0.0): SQL analysis, optimization, and index recommendations
+- **🤖 AI Prompt Enhancer** (v8.0.0): Schema/model/migration generation from natural language
+- **🤖 MCP Server** (v7.0.0): Model Context Protocol for AI agent integration (13 tools)
+- **🤖 AI Safety Guardrails** (v7.0.0): Automatic AI agent detection + destructive operation protection
+- **Handy CLI tools**: `outlet-init`, `outlet-migrate`, `outlet-convert`, `outlet-mcp`
 - **`.env` configuration** (loaded automatically)
 - **Multi-database**: MySQL, PostgreSQL, and SQLite
 - **Complete TypeScript types** with Generic Model and typed Schema Builder (v4.0.0+)
@@ -1220,6 +1227,126 @@ outlet-convert
 - ✅ Automatic timestamps support
 - ✅ Class names converted to PascalCase
 
+## 🤖 AI Integration
+
+Outlet ORM includes a complete AI subsystem with multi-provider LLM support and ORM-specific AI features.
+
+📚 **[Complete AI documentation available in `/docs`](./docs/AI_BRIDGE.md)**
+
+### AiBridge — Multi-Provider LLM Abstraction
+
+```javascript
+const { AiBridgeManager } = require('outlet-orm');
+
+const ai = new AiBridgeManager({
+  providers: {
+    openai: { api_key: process.env.OPENAI_API_KEY, model: 'gpt-4o' },
+    claude: { api_key: process.env.ANTHROPIC_API_KEY, model: 'claude-sonnet-4-20250514' },
+    ollama: { endpoint: 'http://localhost:11434', model: 'llama3' }
+  }
+});
+
+// Chat with any provider
+const response = await ai.chat('openai', [
+  { role: 'user', content: 'What is Node.js?' }
+]);
+
+// Fluent TextBuilder
+const { text } = await ai.text()
+  .using('openai', 'gpt-4o')
+  .withSystemPrompt('You are a helpful assistant.')
+  .withPrompt('Explain closures in JavaScript.')
+  .asText();
+
+// Stream responses
+for await (const chunk of ai.stream('claude', messages)) {
+  process.stdout.write(chunk.text || '');
+}
+
+// Embeddings, images, TTS, STT
+const embeddings = await ai.embeddings('openai', ['Hello world']);
+const image = await ai.image('openai', 'A sunset over mountains');
+```
+
+**Supported providers**: OpenAI, Claude, Gemini, Ollama, Grok, Mistral, ONN, Custom OpenAI, OpenRouter
+
+### AI Query Builder — Natural Language → SQL
+
+```javascript
+const { AIQueryBuilder } = require('outlet-orm');
+
+const qb = new AIQueryBuilder(ai, db);
+
+// Ask in natural language, get SQL + results
+const result = await qb.query('How many users signed up last month?');
+console.log(result.sql);     // SELECT COUNT(*) FROM users WHERE ...
+console.log(result.results); // [{ count: 42 }]
+
+// Generate SQL without executing
+const { sql } = await qb.toSql('Show me the top 5 users by post count');
+```
+
+### AI Seeder — Realistic Data Generation
+
+```javascript
+const { AISeeder } = require('outlet-orm');
+
+const seeder = new AISeeder(ai, db);
+
+// Generate and insert realistic data
+await seeder.seed('products', 20, {
+  domain: 'e-commerce',
+  locale: 'fr_FR',
+  description: 'Fashion store for young adults'
+});
+```
+
+### AI Query Optimizer
+
+```javascript
+const { AIQueryOptimizer } = require('outlet-orm');
+
+const optimizer = new AIQueryOptimizer(ai, db);
+const result = await optimizer.optimize(
+  'SELECT * FROM orders WHERE user_id IN (SELECT id FROM users WHERE status = "active")'
+);
+
+console.log(result.optimized);   // Rewritten SQL
+console.log(result.suggestions); // [{ type: 'index', impact: 'high', ... }]
+console.log(result.indexes);     // ['CREATE INDEX idx_...']
+```
+
+### MCP Server — AI Agent Integration
+
+```bash
+# Start MCP server for AI editors
+npx outlet-mcp
+```
+
+Configure your AI editor:
+
+```json
+{
+  "mcpServers": {
+    "outlet-orm": {
+      "command": "npx",
+      "args": ["outlet-mcp"]
+    }
+  }
+}
+```
+
+**13 MCP tools**: migrations, schema introspection, queries, seeds, backups, AI query, query optimization
+
+📖 Full documentation:
+- [AiBridge Manager](docs/AI_BRIDGE.md) — Multi-provider LLM abstraction
+- [AI Query Builder](docs/AI_QUERY.md) — Natural language to SQL
+- [AI Seeder](docs/AI_SEEDER.md) — Realistic data generation
+- [AI Query Optimizer](docs/AI_OPTIMIZER.md) — SQL optimization
+- [AI Prompt Enhancer](docs/AI_PROMPT.md) — Schema/code generation
+- [MCP Server](docs/MCP.md) — AI agent integration
+- [AI Safety Guardrails](docs/AI_SAFETY.md) — Destructive operation protection
+
 ## 📚 Documentation
 
 - [Migrations Guide](docs/MIGRATIONS.md)
@@ -1227,7 +1354,8 @@ outlet-convert
 - [Relation Detection](docs/RELATIONS_DETECTION.md)
 - [Quick Start Guide](docs/QUICKSTART.md)
 - [Architecture](docs/ARCHITECTURE.md)
-- [**TypeScript (complet)**](docs/TYPESCRIPT.md)
+- [**TypeScript (complete)**](docs/TYPESCRIPT.md)
+- [**AI Integration (complete)**](docs/AI_BRIDGE.md)
 
 ## 📘 TypeScript Support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outlet-orm",
-  "version": "7.0.0",
+  "version": "9.0.0",
   "description": "A Laravel Eloquent-inspired ORM for Node.js with support for MySQL, PostgreSQL, and SQLite",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/AI/AIPromptEnhancer.js

@@ -0,0 +1,170 @@
+'use strict';
+
+/**
+ * AIPromptEnhancer
+ * LLM-powered enhancement of the existing regex-based PromptGenerator.
+ * Takes a natural language description and uses AI to generate richer schemas,
+ * model code, migrations, and seeders — beyond what pattern matching can do.
+ *
+ * @since 8.0.0
+ */
+class AIPromptEnhancer {
+  /**
+   * @param {import('./AiBridgeManager')} manager
+   */
+  constructor(manager) {
+    this._manager = manager;
+    this._provider = 'openai';
+    this._model = 'gpt-4o-mini';
+  }
+
+  /**
+   * @param {string} provider
+   * @param {string} model
+   * @returns {this}
+   */
+  using(provider, model) {
+    this._provider = provider;
+    this._model = model;
+    return this;
+  }
+
+  /**
+   * Generate a full project schema from a natural language description.
+   * Returns tables, columns, relations, and seed hints.
+   * @param {string} description - e.g., "A recipe sharing app with users, recipes, ingredients, and reviews"
+   * @param {Object} [options={}]
+   * @returns {Promise<{tables: Object, relations: Array, seedHints: Object}>}
+   */
+  async generateSchema(description, options = {}) {
+    const systemPrompt = `You are an expert database architect. Given an application description, design a complete relational database schema.
+
+RULES:
+- Return a JSON object with:
+  "tables" — object where each key is a table name, value is an object with "columns" (array of "name:type:modifiers" strings, using outlet-orm format like "name:string", "email:string:unique", "user_id:foreignId", "content:text:nullable", "price:decimal(10,2)", "status:string:default(active)").
+  "relations" — array of objects with "type" (hasOne, hasMany, belongsTo, belongsToMany), "from", "to", and optionally "pivot" table name.
+  "seedHints" — object where each key is a table name, value is a short description of the kind of seed data to generate.
+- Always include id, created_at, updated_at columns implicitly (don't list them).
+- Use snake_case for column/table names.
+- Include foreign keys where appropriate.
+- Design for at least 3rd normal form.`;
+
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: `Design a database schema for: ${description}` },
+    ];
+
+    const res = await this._manager.chat(this._provider, messages, {
+      model: options.model || this._model,
+      temperature: 0.5,
+      max_tokens: 4096,
+      response_format: 'json',
+      json_schema: {
+        name: 'schema_design',
+        schema: {
+          type: 'object',
+          properties: {
+            tables: { type: 'object' },
+            relations: { type: 'array', items: { type: 'object' } },
+            seedHints: { type: 'object' },
+          },
+          required: ['tables'],
+        },
+      },
+    });
+
+    return this._extractJson(res);
+  }
+
+  /**
+   * Generate model source code for a given table schema.
+   * @param {string} tableName
+   * @param {Object} tableSchema - { columns: [...] }
+   * @param {Array} [relations=[]]
+   * @returns {Promise<string>}
+   */
+  async generateModelCode(tableName, tableSchema, relations = []) {
+    const systemPrompt = `You are an expert in outlet-orm (a Node.js Eloquent-inspired ORM).
+Generate a complete model class for the given table. Use CommonJS (module.exports).
+
+Example format:
+const { Model } = require('outlet-orm');
+class User extends Model {
+  static tableName = 'users';
+  static fillable = ['name', 'email', 'password'];
+  static hidden = ['password'];
+  static casts = { created_at: 'datetime' };
+  posts() { return this.hasMany('Post', 'user_id'); }
+}
+module.exports = User;
+
+Include fillable, hidden (for sensitive fields), casts, and relation methods.`;
+
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      {
+        role: 'user',
+        content: `Generate an outlet-orm model for table "${tableName}":\nColumns: ${JSON.stringify(tableSchema.columns || [])}\nRelations: ${JSON.stringify(relations)}`,
+      },
+    ];
+
+    const res = await this._manager.chat(this._provider, messages, {
+      model: this._model,
+      temperature: 0.3,
+      max_tokens: 2048,
+    });
+
+    return res?.output_text || res?.choices?.[0]?.message?.content || res?.content?.[0]?.text || '';
+  }
+
+  /**
+   * Generate migration code for a given table schema.
+   * @param {string} tableName
+   * @param {Object} tableSchema
+   * @returns {Promise<string>}
+   */
+  async generateMigrationCode(tableName, tableSchema) {
+    const systemPrompt = `You are an expert in outlet-orm migrations. Generate a migration file.
+
+Example format:
+const { Migration, Schema } = require('outlet-orm');
+class CreateUsersTable extends Migration {
+  async up(schema) {
+    await schema.create('users', (table) => {
+      table.increments('id');
+      table.string('name');
+      table.string('email').unique();
+      table.timestamps();
+    });
+  }
+  async down(schema) {
+    await schema.dropIfExists('users');
+  }
+}
+module.exports = CreateUsersTable;
+
+Use proper column types: string, text, integer, bigInteger, decimal, boolean, date, datetime, timestamp, json, foreignId.`;
+
+    const messages = [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: `Generate a migration for table "${tableName}":\nColumns: ${JSON.stringify(tableSchema.columns || [])}` },
+    ];
+
+    const res = await this._manager.chat(this._provider, messages, {
+      model: this._model,
+      temperature: 0.2,
+      max_tokens: 2048,
+    });
+
+    return res?.output_text || res?.choices?.[0]?.message?.content || res?.content?.[0]?.text || '';
+  }
+
+  /** @private */
+  _extractJson(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 { tables: {}, relations: [], seedHints: {} }; }
+  }
+}
+
+module.exports = AIPromptEnhancer;

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;