outlet-orm 7.0.0 → 9.0.1

package/docs/skills/outlet-orm/API.md

@@ -515,6 +515,114 @@ const db = new DatabaseConnection({
 
 ---
 
+## AiBridgeManager
+
+> Since v8.0.0
+
+### Constructor
+
+```javascript
+const { AiBridgeManager } = require('outlet-orm');
+const ai = new AiBridgeManager(config); // From config/aibridge.js or inline
+```
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`chat(provider, messages, opts?)`| `{ text, tool_calls, raw }` | Send chat request |
+|`stream(provider, messages, opts?)`| `AsyncGenerator<StreamChunk>` | SSE/NDJSON stream |
+|`streamEvents(provider, messages, opts?)`| `AsyncGenerator<{type, data}>` | Structured stream events |
+|`embeddings(provider, inputs, opts?)`| `{ vectors, usage, raw }` | Generate embeddings |
+|`image(provider, prompt, opts?)`| `{ url, b64_json, raw }` | Generate image |
+|`tts(provider, text, opts?)`| `{ audio, mime }` | Text-to-speech |
+|`stt(provider, filePath, opts?)`| `{ text }` | Speech-to-text |
+|`models(provider)`| `Array<{id, ...}>` | List available models |
+|`model(provider, id)`| `Object` | Get single model info |
+|`text()`| `TextBuilder` | Fluent text builder |
+|`chatWithTools(provider, messages, opts?)`| `{ text, raw }` | Chat with tool calling loop |
+|`registerTool(tool)`| `void` | Register a custom tool |
+|`registerProvider(name, provider)`| `void` | Register a custom provider |
+|`provider(name)`| `Provider` | Get registered provider |
+|`tool(name)`| `ToolContract` | Get registered tool |
+|`tools()`| `Array<ToolContract>` | Get all tools |
+
+---
+
+## TextBuilder
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`.using(provider, model)`| `this` | Set provider and model |
+|`.withPrompt(text, attachments?)`| `this` | Add user message |
+|`.withSystemPrompt(text)`| `this` | Set system prompt |
+|`.withMaxTokens(n)`| `this` | Max tokens limit |
+|`.usingTemperature(t)`| `this` | Temperature (0–2) |
+|`.usingTopP(p)`| `this` | Top-p sampling |
+|`.withApiKey(key)`| `this` | Override API key |
+|`.withEndpoint(url)`| `this` | Override endpoint |
+|`.withBaseUrl(url)`| `this` | Override base URL |
+|`.withAuthHeader(header, prefix?)`| `this` | Override auth header |
+|`.withExtraHeaders(headers)`| `this` | Extra HTTP headers |
+|`.asText()`| `{ text, raw, usage, finish_reason }` | Text response |
+|`.asStream()`| `AsyncGenerator<StreamChunk>` | Streaming response |
+|`.asRaw()`| `Object` | Raw provider response |
+
+---
+
+## AIQueryBuilder
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`using(provider, model)`| `this` | Set LLM provider |
+|`safeMode(bool)`| `this` | Restrict to SELECT/WITH |
+|`query(question)`| `{ sql, params, results, explanation }` | NL → SQL + execute |
+|`toSql(question)`| `{ sql, params, explanation }` | NL → SQL only |
+
+---
+
+## AISeeder
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`using(provider, model)`| `this` | Set LLM provider |
+|`seed(table, count, ctx)`| `{ records, inserted }` | Generate + insert |
+|`generate(table, count, ctx)`| `Array<Object>` | Preview only |
+
+---
+
+## AIQueryOptimizer
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`using(provider, model)`| `this` | Set LLM provider |
+|`optimize(sql)`| `{ original, optimized, suggestions, indexes, explanation }` | Analyze + rewrite |
+|`explain(sql)`| `{ plan, analysis }` | EXPLAIN + LLM analysis |
+
+---
+
+## AIPromptEnhancer
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`using(provider, model)`| `this` | Set LLM provider |
+|`generateSchema(description)`| `{ tables, relations, seedHints }` | Schema from description |
+|`generateModelCode(table, schema, rels)`| `string` | Model class code |
+|`generateMigrationCode(table, schema)`| `string` | Migration class code |
+
+---
+
+## AISafetyGuardrails (Static)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`detectAgent()`| `{ detected, agentName }` | Detect AI agent |
+|`isDestructiveCommand(cmd)`| `boolean` | Check if destructive |
+|`validateDestructiveAction(cmd, flags)`| `{ allowed, message }` | Validate with consent |
+|`CONSENT_ENV_VAR`| `string` | Consent env var name |
+
+---
+
 ## References
 
 - <https://github.com/omgbwa-yasse/outlet-orm>

package/docs/skills/outlet-orm/QUERIES.md

@@ -300,6 +300,70 @@ const native = await db.execute(
 
 ---
 
+## AI Query Builder — Natural Language to SQL
+
+> Since v8.0.0
+
+Convert natural language into SQL queries using any LLM provider via AiBridge.
+
+```javascript
+const { AiBridgeManager, AIQueryBuilder, DatabaseConnection } = require('outlet-orm');
+
+const ai = new AiBridgeManager({ providers: { openai: { api_key: process.env.OPENAI_API_KEY, model: 'gpt-4o-mini' } } });
+const db = new DatabaseConnection();
+const qb = new AIQueryBuilder(ai, db);
+
+// Convert and execute
+const result = await qb.query('How many users signed up last month?');
+console.log(result.sql);     // SELECT COUNT(*) ...
+console.log(result.results); // [{ count: 42 }]
+
+// Generate SQL without executing
+const { sql } = await qb.toSql('Find duplicate emails');
+
+// Use a specific provider
+const r = await qb.using('claude', 'claude-sonnet-4-20250514')
+  .query('List users without orders');
+
+// Disable safe mode (allow writes)
+qb.safeMode(false);
+```
+
+### AI Query Builder Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`using(provider, model)`| `this` | Set LLM provider |
+|`safeMode(bool)`| `this` | Restrict to SELECT/WITH (default: `true`) |
+|`query(question)`| `{ sql, params, results, explanation }` | NL → SQL + execute |
+|`toSql(question)`| `{ sql, params, explanation }` | NL → SQL only |
+
+See [AI.md](AI.md) for full details.
+
+---
+
+## AI Query Optimizer
+
+> Since v8.0.0
+
+Analyze and optimize SQL queries with AI.
+
+```javascript
+const { AIQueryOptimizer } = require('outlet-orm');
+
+const optimizer = new AIQueryOptimizer(ai, db);
+const result = await optimizer.optimize('SELECT * FROM orders WHERE ...');
+console.log(result.optimized);   // Rewritten SQL
+console.log(result.suggestions); // [{ type, description, impact }]
+console.log(result.indexes);     // ['CREATE INDEX ...']
+
+const { plan, analysis } = await optimizer.explain('SELECT ...');
+```
+
+See [AI.md](AI.md) for full details.
+
+---
+
 ## Query Builder Methods Summary
 
 | Method | Description |

package/docs/skills/outlet-orm/SEEDS.md

@@ -96,3 +96,50 @@ outlet-migrate seed
 - Control FK order explicitly in`DatabaseSeeder`.
 - Keep heavy bulk data in dedicated import scripts.
 - Prefer unique constraints to prevent duplicate seed data.
+
+---
+
+## AI Seeder — LLM-Powered Data Generation
+
+> Since v8.0.0
+
+Generate realistic domain-specific seed data using AI instead of generic lorem ipsum.
+
+```javascript
+const { AiBridgeManager, AISeeder, DatabaseConnection } = require('outlet-orm');
+
+const ai = new AiBridgeManager({
+  providers: { openai: { api_key: process.env.OPENAI_API_KEY, model: 'gpt-4o-mini' } }
+});
+const seeder = new AISeeder(ai, new DatabaseConnection());
+
+// Generate and insert 10 realistic user records
+const { records, inserted } = await seeder.seed('users', 10, {
+  domain: 'e-commerce',
+  locale: 'fr_FR',
+  description: 'An online fashion store'
+});
+
+// Preview without inserting
+const preview = await seeder.generate('products', 5, {
+  domain: 'electronics'
+});
+```
+
+### AI Seeder API
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+|`using(provider, model)`| `this` | Set LLM provider |
+|`seed(table, count, context)`| `{ records, inserted }` | Generate + insert |
+|`generate(table, count, context)`| `Array<Object>` | Generate only (preview) |
+
+### Context Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `domain` | `string` | Business domain (`'e-commerce'`, `'healthcare'`, `'finance'`) |
+| `locale` | `string` | Locale for names/addresses (`'fr_FR'`, `'ja_JP'`, `'pt_BR'`) |
+| `description` | `string` | Detailed description for better data quality |
+
+See [AI.md](AI.md) for full details.

package/docs/skills/outlet-orm/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: outlet-orm-best-practices
-description: Outlet ORM is a Laravel Eloquent-inspired ORM for Node.js with MySQL, PostgreSQL, and SQLite support. Use this skill when working with Outlet ORM models, queries, relationships, migrations, backup, and database operations. v6.0.0 adds a full Backup module (BackupManager, BackupScheduler, AES-256-GCM encryption, TCP daemon).
+description: Outlet ORM is a Laravel Eloquent-inspired ORM for Node.js with MySQL, PostgreSQL, and SQLite support. Use this skill when working with Outlet ORM models, queries, relationships, migrations, backup, AI integration (AiBridge multi-provider LLM, AI Query Builder, AI Seeder, AI Optimizer, MCP Server) and database operations.
 license: MIT
 metadata:
 author: omgbwa-yasse
-version: "6.0.0"
+version: "9.0.0"
 source: https://github.com/omgbwa-yasse/outlet-orm
 npm: https://www.npmjs.com/package/outlet-orm
 ---
@@ -13,11 +13,15 @@ npm: https://www.npmjs.com/package/outlet-orm
 
 Comprehensive guide for using Outlet ORM - a Laravel Eloquent-inspired ORM for Node.js/TypeScript with support for MySQL, PostgreSQL, and SQLite.
 
-> 🆕 **v7.0.0**: AI Integration — MCP Server (Model Context Protocol), AI Safety Guardrails, Prompt-based project initialization. See [AI.md](AI.md).
+> 🆕 **v9.0.0**: Complete AI documentation — AiBridge multi-provider LLM, AI Query Builder, AI Seeder, AI Optimizer, AI Prompt Enhancer, AI Safety Guardrails. See [AI.md](AI.md).
+>
+> 🔖 **v8.0.0**: AiBridge multi-provider LLM abstraction (9 providers), AI Query Builder, AI Seeder, AI Query Optimizer, AI Prompt Enhancer.
+>
+> 🔖 **v7.0.0**: AI Integration — MCP Server (Model Context Protocol), AI Safety Guardrails, Prompt-based project initialization.
 >
 > 🔖 **v6.5.0**: Accessors & Mutators, firstOrCreate/firstOrNew/updateOrCreate, upsert, Observer pattern, cursor/stream.
 >
-> 🔖 **v6.0.0**: Full Backup module — `BackupManager`, `BackupScheduler`, AES-256-GCM `BackupEncryption`, `BackupSocketServer` TCP daemon, `BackupSocketClient` with remote restore. See [BACKUP.md](BACKUP.md).
+> 🔖 **v6.0.0**: Full Backup module — `BackupManager`, `BackupScheduler`, AES-256-GCM `BackupEncryption`, `BackupSocketServer` TCP daemon. See [BACKUP.md](BACKUP.md).
 >
 > 🔖 **v5.0.0**: Full TypeScript support with Generic Model, typed Schema Builder, MigrationInterface and Copilot Skills integration.
 
@@ -33,7 +37,7 @@ Comprehensive guide for using Outlet ORM - a Laravel Eloquent-inspired ORM for N
 | **[TYPESCRIPT.md](TYPESCRIPT.md)** | TypeScript types, generics, typed models, migrations |
 | **[SECURITY.md](SECURITY.md)** | 🔐 Security best practices, authentication, authorisation |
 | **[BACKUP.md](BACKUP.md)** | 🗄️ Backups, scheduling, AES-256-GCM encryption, TCP daemon, restore |
-| **[AI.md](AI.md)** | 🤖 MCP Server, AI Safety Guardrails, Prompt-based Init |
+| **[AI.md](AI.md)** | 🤖 AiBridge (9 LLM providers), AI Query Builder, AI Seeder, AI Optimizer, AI Prompt Enhancer, MCP Server, AI Safety Guardrails |
 | **[API.md](API.md)** | Complete API Reference |
 
 ---
@@ -52,8 +56,12 @@ Reference these guidelines when:
 - Scheduling or encrypting database backups  [BACKUP.md](BACKUP.md)
 - Restoring a database from a backup file  [BACKUP.md](BACKUP.md)
 - Running a long-lived backup daemon over TCP  [BACKUP.md](BACKUP.md)
+- Configuring LLM providers (AiBridge)  [AI.md](AI.md)
+- Converting natural language to SQL (AI Query Builder)  [AI.md](AI.md)
+- Generating realistic seed data with AI  [AI.md](AI.md)
+- Optimizing SQL queries with AI  [AI.md](AI.md)
+- Generating schemas/models/migrations from descriptions  [AI.md](AI.md)
 - Exposing the ORM to AI agents via MCP  [AI.md](AI.md)
-- Generating projects from natural language prompts  [AI.md](AI.md)
 - Protecting against AI-initiated destructive operations  [AI.md](AI.md)
 
 ---
@@ -194,7 +202,7 @@ outlet-migrate migrate
 | 7 | Validation & Events | MEDIUM | [ADVANCED.md](ADVANCED.md) |
 | 8 | Migrations & CLI | LOW-MEDIUM | [MIGRATIONS.md](MIGRATIONS.md) |
 | 9 | Backup & Restore | MEDIUM | [BACKUP.md](BACKUP.md) |
-| 10 | AI / MCP Integration | MEDIUM | [AI.md](AI.md) |
+| 10 | AI / MCP Integration | MEDIUM-HIGH | [AI.md](AI.md) |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outlet-orm",
-  "version": "7.0.0",
+  "version": "9.0.1",
   "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;