outlet-orm 9.0.0 → 9.0.1

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

@@ -1,31 +1,416 @@
 ---
 name: outlet-orm-ai-integration
-description: Guide for AI agents to use Outlet ORM's MCP Server, AI Safety Guardrails, and prompt-based project initialization. Use this skill when an AI agent needs to interact with Outlet ORM databases, run migrations, create projects, or execute queries safely.
+description: Guide for AI agents to use Outlet ORM's AiBridge multi-provider LLM, AI Query Builder, AI Seeder, AI Optimizer, AI Prompt Enhancer, MCP Server, and AI Safety Guardrails. Use this skill when an AI agent needs to interact with LLMs, databases, run migrations, generate data, optimize queries, or create projects safely.
 license: MIT
 metadata:
   author: omgbwa-yasse
-  version: "7.0.0"
+  version: "9.0.0"
   source: https://github.com/omgbwa-yasse/outlet-orm
   npm: https://www.npmjs.com/package/outlet-orm
 ---
 
 # Outlet ORM — AI Integration Guide
 
-This skill covers Outlet ORM's AI-oriented features introduced in v7.0.0:
+This skill covers Outlet ORM's complete AI feature set (v7.0.0 – v9.0.0):
 
-- **MCP Server** — Model Context Protocol server for AI agents
+- **AiBridge** — Multi-provider LLM abstraction (9 providers, chat, stream, embeddings, images, TTS, STT, tool calling)
+- **AI Query Builder** — Natural language to SQL
+- **AI Seeder** — LLM-powered realistic data generation
+- **AI Query Optimizer** — SQL optimization and EXPLAIN analysis
+- **AI Prompt Enhancer** — Schema/model/migration code generation from natural language
+- **MCP Server** — Model Context Protocol server for AI agents (13 tools)
 - **AI Safety Guardrails** — Protection against destructive operations
-- **Prompt-based Init** — Generate projects from natural language descriptions
+
+---
+
+## AiBridge — Multi-Provider LLM Abstraction
+
+> Since v8.0.0
+
+AiBridge provides a unified API to interact with 9+ LLM providers. Zero production dependencies (Node 18+ native `fetch`).
+
+### Configuration
+
+```javascript
+// config/aibridge.js
+module.exports = {
+  default: process.env.AI_DEFAULT_PROVIDER || 'openai',
+  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' },
+    gemini:       { api_key: process.env.GEMINI_API_KEY,     model: 'gemini-2.0-flash' },
+    ollama:       { endpoint: 'http://localhost:11434',      model: 'llama3' },
+    ollama_turbo: { api_key: process.env.OLLAMA_TURBO_API_KEY, endpoint: 'https://api.ollama.ai', model: 'llama3' },
+    grok:         { api_key: process.env.GROK_API_KEY,       model: 'grok-1' },
+    mistral:      { api_key: process.env.MISTRAL_API_KEY,    model: 'mistral-large-latest' },
+    onn:          { api_key: process.env.ONN_API_KEY,        model: 'onn-default' },
+    openai_custom: {
+      api_key: process.env.CUSTOM_OPENAI_API_KEY,
+      base_url: process.env.CUSTOM_OPENAI_BASE_URL || 'http://localhost:1234/v1',
+      model: 'local-model'
+    },
+    openrouter: {
+      api_key: process.env.OPENROUTER_API_KEY,
+      base_url: 'https://openrouter.ai/api/v1',
+      model: 'openai/gpt-4o'
+    }
+  },
+  settings: {
+    max_file_bytes: 10485760,
+    default_max_tokens: 2048,
+    default_temperature: 0.7,
+    max_tool_iterations: 5
+  }
+};
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AI_DEFAULT_PROVIDER` | Default provider name | `openai` |
+| `OPENAI_API_KEY` | OpenAI API key | — |
+| `ANTHROPIC_API_KEY` | Claude API key | — |
+| `GEMINI_API_KEY` | Google Gemini API key | — |
+| `OLLAMA_ENDPOINT` | Ollama local URL | `http://localhost:11434` |
+| `GROK_API_KEY` | xAI Grok API key | — |
+| `MISTRAL_API_KEY` | Mistral AI API key | — |
+| `ONN_API_KEY` | Onn.ai API key | — |
+| `OPENROUTER_API_KEY` | OpenRouter API key | — |
+| `CUSTOM_OPENAI_BASE_URL` | Custom OpenAI-compatible URL | — |
+| `AI_MAX_TOKENS` | Default max tokens | `2048` |
+| `AI_TEMPERATURE` | Default temperature | `0.7` |
+
+### Chat
+
+```javascript
+const { AiBridgeManager } = require('outlet-orm');
+
+const ai = new AiBridgeManager(config);
+
+const response = await ai.chat('openai', [
+  { role: 'system', content: 'You are a helpful assistant.' },
+  { role: 'user', content: 'Explain closures in JavaScript.' }
+], { model: 'gpt-4o-mini', max_tokens: 500 });
+
+console.log(response.text);
+```
+
+### Streaming
+
+```javascript
+for await (const chunk of ai.stream('openai', messages)) {
+  process.stdout.write(chunk.text || '');
+}
+```
+
+### Embeddings
+
+```javascript
+const result = await ai.embeddings('openai', ['The quick brown fox'], {
+  model: 'text-embedding-3-small'
+});
+console.log(result.vectors);
+```
+
+### Image Generation
+
+```javascript
+const image = await ai.image('openai', 'A sunset over mountains', {
+  model: 'dall-e-3', size: '1024x1024'
+});
+```
+
+### TTS / STT
+
+```javascript
+const { audio, mime } = await ai.tts('openai', 'Hello!', { voice: 'alloy' });
+const { text } = await ai.stt('openai', '/path/to/audio.mp3');
+```
+
+### TextBuilder (Fluent API)
+
+```javascript
+const { text } = await ai.text()
+  .using('openai', 'gpt-4o')
+  .withSystemPrompt('You are a poet.')
+  .withPrompt('Write a haiku about coding.')
+  .withMaxTokens(100)
+  .usingTemperature(0.9)
+  .asText();
+```
+
+| Method | Description |
+|--------|-------------|
+| `.using(provider, model)` | Set provider and model |
+| `.withPrompt(text, attachments?)` | Add user message |
+| `.withSystemPrompt(text)` | Set system prompt |
+| `.withMaxTokens(n)` | Max tokens limit |
+| `.usingTemperature(t)` | Temperature (0–2) |
+| `.withApiKey(key)` | Override API key |
+| `.withBaseUrl(url)` | Override base URL |
+| `.asText()` | Returns `{ text, raw, usage }` |
+| `.asStream()` | Returns `AsyncGenerator<StreamChunk>` |
+| `.asRaw()` | Returns raw provider response |
+
+### Tool Calling (Function Calling)
+
+```javascript
+const { ToolContract } = require('outlet-orm');
+
+class WeatherTool extends ToolContract {
+  name() { return 'get_weather'; }
+  description() { return 'Get current weather for a city'; }
+  schema() {
+    return {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city']
+    };
+  }
+  async execute({ city }) {
+    return JSON.stringify({ city, temperature: 22, unit: 'celsius' });
+  }
+}
+
+ai.registerTool(new WeatherTool());
+const response = await ai.chatWithTools('openai', [
+  { role: 'user', content: "What's the weather in Paris?" }
+]);
+```
+
+### AiBridge Facade
+
+```javascript
+const { AiBridge, AiBridgeManager } = require('outlet-orm');
+
+AiBridge.setManager(new AiBridgeManager(config));
+
+const { text } = await AiBridge.text()
+  .using('openai', 'gpt-4o')
+  .withPrompt('Hello!')
+  .asText();
+```
+
+### Support Classes
+
+| Class | Purpose |
+|-------|---------|
+| `Message` | Value object: `Message.system()`, `.user()`, `.assistant()` |
+| `Document` | Attachments: `.fromLocalPath()`, `.fromUrl()`, `.fromBase64()`, `.fromChunks()` |
+| `StreamChunk` | Streaming DTO: `.text`, `.usage`, `.finishReason`, `.toolCalls` |
+| `ProviderError` | Error handling: `.notFound(name)`, `.unsupported(name, feature)` |
+| `FileSecurity` | File attachment validation (size, type) |
+| `JsonSchemaValidator` | Validates structured LLM outputs |
+
+### Providers
+
+| Provider | Class | Capabilities |
+|----------|-------|-------------|
+| **OpenAI** | `OpenAIProvider` | Chat, SSE streaming, embeddings, images, TTS, STT, function calling |
+| **Claude** | `ClaudeProvider` | Chat, simulated streaming |
+| **Gemini** | `GeminiProvider` | Chat, simulated streaming, embeddings |
+| **Ollama** | `OllamaProvider` | Chat, NDJSON streaming, embeddings, images, multimodal |
+| **Ollama Turbo** | `OllamaTurboProvider` | Ollama + Bearer token auth |
+| **Grok** | `GrokProvider` | Chat, simulated streaming |
+| **Mistral** | `MistralProvider` | OpenAI-compatible |
+| **ONN** | `OnnProvider` | Chat, simulated streaming |
+| **Custom OpenAI** | `CustomOpenAIProvider` | Any OpenAI-compatible endpoint (LM Studio, vLLM, Azure, OpenRouter) |
+
+---
+
+## AI Query Builder — Natural Language to SQL
+
+> Since v8.0.0
+
+Convert natural language questions into SQL queries using any LLM.
+
+```javascript
+const { AiBridgeManager, AIQueryBuilder, DatabaseConnection } = require('outlet-orm');
+
+const ai = new AiBridgeManager(config);
+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');
+```
+
+### API
+
+| 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 }` | Convert + execute |
+| `toSql(question)` | `{ sql, params, explanation }` | Convert only |
+
+### Schema Introspection
+
+| Driver | Method |
+|--------|--------|
+| SQLite | `PRAGMA table_list` + `PRAGMA table_info` |
+| PostgreSQL | `information_schema.tables` + `columns` |
+| MySQL | `SHOW TABLES` + `DESCRIBE` |
+
+---
+
+## AI Seeder — LLM-Powered Data Generation
+
+> Since v8.0.0
+
+Generate realistic, domain-specific seed data using AI.
+
+```javascript
+const { AiBridgeManager, AISeeder, DatabaseConnection } = require('outlet-orm');
+
+const seeder = new AISeeder(new AiBridgeManager(config), new DatabaseConnection());
+
+// Generate and insert
+const { records, inserted } = await seeder.seed('users', 10, {
+  domain: 'e-commerce',
+  locale: 'fr_FR',
+  description: 'An online fashion store'
+});
+
+// Generate without inserting (preview)
+const records = await seeder.generate('products', 20, {
+  domain: 'electronics'
+});
+```
+
+### 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'`, etc.) |
+| `locale` | `string` | Name/address locale (`'fr_FR'`, `'ja_JP'`, `'pt_BR'`, etc.) |
+| `description` | `string` | Detailed domain description for better data quality |
+
+---
+
+## AI Query Optimizer
+
+> Since v8.0.0
+
+Analyze and optimize SQL queries using AI with index recommendations.
+
+```javascript
+const { AiBridgeManager, AIQueryOptimizer, DatabaseConnection } = require('outlet-orm');
+
+const optimizer = new AIQueryOptimizer(new AiBridgeManager(config), new DatabaseConnection());
+
+// Optimize
+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, description, impact }]
+console.log(result.indexes);     // ['CREATE INDEX ...']
+
+// Explain
+const { plan, analysis } = await optimizer.explain('SELECT ...');
+```
+
+### API
+
+| 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 interpretation |
+
+### Common Optimizations Detected
+
+| Issue | Impact | Suggestion |
+|-------|--------|------------|
+| `SELECT *` | Medium | Specify explicit columns |
+| Missing index on JOIN column | High | `CREATE INDEX` on foreign keys |
+| `IN` subquery | High | Rewrite as `JOIN` |
+| Leading wildcard `LIKE '%...'` | High | Use full-text search |
+| Large `OFFSET` pagination | Medium | Use keyset pagination |
+
+---
+
+## AI Prompt Enhancer — Schema & Code Generation
+
+> Since v8.0.0
+
+Generate complete schemas, models, and migrations from natural language.
+
+```javascript
+const { AiBridgeManager, AIPromptEnhancer } = require('outlet-orm');
+
+const enhancer = new AIPromptEnhancer(new AiBridgeManager(config));
+
+// Generate full schema
+const schema = await enhancer.generateSchema(
+  'A veterinary clinic with pets, owners, appointments, and medical records'
+);
+// schema.tables, schema.relations, schema.seedHints
+
+// Generate model code
+const code = await enhancer.generateModelCode('pets', schema.tables.pets, relations);
+
+// Generate migration code
+const migration = await enhancer.generateMigrationCode('pets', schema.tables.pets);
+```
+
+### API
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `using(provider, model)` | `this` | Set LLM provider |
+| `generateSchema(description)` | `{ tables, relations, seedHints }` | Full schema from description |
+| `generateModelCode(table, schema, rels)` | `string` | outlet-orm Model class code |
+| `generateMigrationCode(table, schema)` | `string` | outlet-orm Migration class code |
+
+### PromptGenerator (Regex-Based, Offline)
+
+For offline scaffolding without an LLM:
+
+```javascript
+const { PromptGenerator } = require('outlet-orm');
+
+const blueprint = PromptGenerator.parse('Create a blog with comments and tags');
+PromptGenerator.generateModels(blueprint, './src/models');
+PromptGenerator.generateMigrations(blueprint, './database/migrations');
+PromptGenerator.generateSeeder(blueprint, './database/seeds');
+```
+
+Built-in templates: E-commerce, Blog/CMS, Task/Project, Social Network, SaaS, Habit Tracker, API/Auth.
+
+### CLI
+
+```bash
+outlet-init --prompt "Create a blog with posts, comments, and tags"
+outlet-init --prompt "E-commerce store" --driver sqlite
+```
 
 ---
 
 ## MCP Server
 
+> Since v7.0.0
+
 The MCP server exposes Outlet ORM's full capabilities to AI agents via JSON-RPC 2.0 over stdio.
 
 ### Configuration
 
-Add to your AI editor's MCP config (e.g. `.cursor/mcp.json`, `.vscode/mcp.json`, `claude_desktop_config.json`):
+Add to your AI editor's MCP config (`.cursor/mcp.json`, `.vscode/mcp.json`, `claude_desktop_config.json`):
 
 ```json
 {
@@ -48,36 +433,32 @@ Add to your AI editor's MCP config (e.g. `.cursor/mcp.json`, `.vscode/mcp.json`,
 |------|-------------|:-----------:|
 | `migrate_status` | Show pending and executed migrations | No |
 | `migrate_run` | Run all pending migrations | No |
-| `migrate_rollback` | Rollback last batch (supports `steps` param) | No |
+| `migrate_rollback` | Rollback last batch | No |
 | `migrate_reset` | Rollback ALL migrations | **Yes** |
 | `migrate_make` | Create a new migration file | No |
 | `seed_run` | Run database seeders | No |
-| `schema_introspect` | Introspect database schema (all tables or specific) | No |
-| `query_execute` | Execute raw SQL (write queries need consent) | Conditional |
-| `model_list` | List all model files in the project | No |
-| `backup_create` | Create a database backup (full/partial/journal) | No |
-| `backup_restore` | Restore from a backup file | **Yes** |
+| `schema_introspect` | Introspect database schema | No |
+| `query_execute` | Execute raw SQL | Conditional |
+| `model_list` | List all model files | No |
+| `backup_create` | Create database backup | No |
+| `backup_restore` | Restore from backup | **Yes** |
+| `ai_query` | AI natural language to SQL | No |
+| `query_optimize` | AI query optimization | No |
 
 ### Tool Usage Examples
 
-**Introspect the schema:**
 ```json
+// Introspect schema
 { "method": "tools/call", "params": { "name": "schema_introspect", "arguments": {} } }
-```
 
-**Run a SELECT query:**
-```json
+// Run a SELECT query
 { "method": "tools/call", "params": { "name": "query_execute", "arguments": { "sql": "SELECT * FROM users LIMIT 10" } } }
-```
 
-**Create a migration:**
-```json
-{ "method": "tools/call", "params": { "name": "migrate_make", "arguments": { "name": "create_products_table" } } }
-```
+// AI query
+{ "method": "tools/call", "params": { "name": "ai_query", "arguments": { "question": "How many users signed up this month?" } } }
 
-**Destructive operation (requires consent):**
-```json
-{ "method": "tools/call", "params": { "name": "migrate_reset", "arguments": { "consent": "User confirmed: reset all migrations in dev environment" } } }
+// Destructive operation (requires consent)
+{ "method": "tools/call", "params": { "name": "migrate_reset", "arguments": { "consent": "User confirmed: reset dev migrations" } } }
 ```
 
 ### Programmatic Usage
@@ -90,11 +471,9 @@ const server = new MCPServer({
   safetyGuardrails: true
 });
 
-// Programmatic handler (for testing or embedding)
 const handler = server.handler();
 const response = await handler({
-  jsonrpc: '2.0',
-  id: 1,
+  jsonrpc: '2.0', id: 1,
   method: 'tools/call',
   params: { name: 'schema_introspect', arguments: {} }
 });
@@ -104,108 +483,62 @@ const response = await handler({
 
 ## AI Safety Guardrails
 
-Outlet ORM automatically detects AI agent invocations and blocks destructive operations without explicit user consent.
+> Since v7.0.0
+
+Automatic AI agent detection and protection against destructive operations.
 
 ### Detected Agents
 
-- **Cursor** (CURSOR_TRACE_ID, CURSOR_SESSION_ID)
-- **Claude Code** (CLAUDE_CODE)
-- **GitHub Copilot** (COPILOT_AGENT_MODE)
-- **Windsurf** (WINDSURF_SESSION_ID, CODEIUM_SESSION)
-- **Gemini CLI** (GEMINI_API_KEY + process title)
-- **Aider** (AIDER_SESSION)
-- **Replit** (REPLIT_DB_URL, REPLIT_AI_ENABLED)
-- **Qwen Code** (QWEN_SESSION)
-- **MCP Clients** (MCP_SERVER_NAME, MCP_SESSION_ID)
+| Agent | Detection |
+|-------|-----------|
+| **Cursor** | `CURSOR_*` env variables |
+| **Claude Code** | `CLAUDE_*` env variables |
+| **GitHub Copilot** | `GITHUB_COPILOT_*` or `VSCODE_*` with Copilot |
+| **Windsurf** | `WINDSURF_*` env variables |
+| **Gemini CLI** | `GEMINI_*` env variables |
+| **Aider** | `AIDER_*` env variables |
+| **Replit** | `REPL_*` env variables |
+| **Qwen Code** | `QWEN_*` env variables |
+| **Generic MCP** | `MCP_*` env variables |
 
 ### Destructive Commands
 
-These commands are blocked when an AI agent is detected without consent:
-`reset`, `fresh`, `migrate:reset`, `migrate:fresh`, `drop`, `truncate`, `restore`
+Blocked without consent: `reset`, `fresh`, `drop`, `truncate`, `restore`
 
 ### Consent Mechanism
 
-To allow a destructive operation, the AI agent must either:
-
-1. **Set the environment variable:**
-   ```bash
-   OUTLET_USER_CONSENT_FOR_DANGEROUS_AI_ACTION="User confirmed: reset dev database"
-   ```
+```bash
+# Via environment variable
+export OUTLET_USER_CONSENT_FOR_DANGEROUS_AI_ACTION="User approved: reset dev database"
+```
 
-2. **Pass the `consent` flag** in MCP tool arguments:
-   ```json
-   { "consent": "User explicitly approved resetting the development database" }
-   ```
+```json
+// Via MCP tool argument
+{ "consent": "User confirmed: reset the development database" }
+```
 
 ### Programmatic Usage
 
 ```javascript
 const { AISafetyGuardrails } = require('outlet-orm');
 
-// Detect if running under an AI agent
 const { detected, agentName } = AISafetyGuardrails.detectAgent();
-console.log(detected, agentName); // true, 'GitHub Copilot'
-
-// Validate a destructive action
 const result = AISafetyGuardrails.validateDestructiveAction('reset', { consent: 'User approved' });
 console.log(result.allowed); // true
 ```
 
 ---
 
-## Prompt-based Initialization
-
-Generate an entire project from a natural language description.
-
-### CLI Usage
-
-```bash
-outlet-init --prompt "Create a blog application with posts, comments, and tags"
-outlet-init --prompt "E-commerce store with products, orders, and payments" --driver sqlite
-```
-
-### Supported Domains
-
-| Domain | Keywords | Generated Tables |
-|--------|----------|-----------------|
-| **E-commerce** | shop, store, product, cart, order, payment | users, products, categories, orders, order_items, payments |
-| **Blog/CMS** | blog, article, post, cms, comment, tag | users, posts, categories, tags, post_tag, comments |
-| **Task/Project** | task, project, todo, kanban, sprint | users, projects, tasks, labels, task_label |
-| **Social Network** | social, friend, follow, like, feed, message | users, posts, comments, likes, follows, messages |
-| **SaaS** | saas, tenant, subscription, plan, billing | organizations, users, plans, subscriptions, invoices |
-| **Habit Tracker** | habit, tracker, health, fitness, goal | users, habits, logs, goals |
-| **API/Auth** | api, auth, rest, user | users, tokens, password_resets |
-
-### Programmatic Usage
-
-```javascript
-const { PromptGenerator } = require('outlet-orm');
-
-// Parse a prompt
-const blueprint = PromptGenerator.parse('Create a blog with comments and tags');
-console.log(blueprint.domain);  // 'blog'
-console.log(blueprint.tables);  // { users: {...}, posts: {...}, ... }
-
-// Generate models
-const modelFiles = PromptGenerator.generateModels(blueprint, './models');
-
-// Generate migrations
-const migrationFiles = PromptGenerator.generateMigrations(blueprint, './database/migrations');
-
-// Generate seeder
-const seederFile = PromptGenerator.generateSeeder(blueprint, './database/seeds');
-```
-
----
-
 ## Best Practices for AI Agents
 
 1. **Always introspect first** — Use `schema_introspect` before modifying the database.
 2. **Never bypass safety guardrails** — Always obtain explicit user consent for destructive operations.
-3. **Use migrations, not raw DDL** — Prefer `migrate_make` + `migrate_run` over raw `CREATE TABLE` queries.
+3. **Use migrations, not raw DDL** — Prefer `migrate_make` + `migrate_run` over raw `CREATE TABLE`.
 4. **Check migration status** — Use `migrate_status` before running migrations.
-5. **Explain write queries** — When using `query_execute` for writes, explain what the query does to the user.
+5. **Explain write queries** — When using `query_execute` for writes, explain what the query does.
 6. **Prefer backups before destructive operations** — Use `backup_create` before `migrate_reset`.
+7. **Use AI Query Builder for natural language** — Use `ai_query` tool instead of crafting SQL manually.
+8. **Preview before seeding** — Use `generate()` to preview AI-generated data before `seed()`.
 
 ---
 
@@ -213,8 +546,25 @@ const seederFile = PromptGenerator.generateSeeder(blueprint, './database/seeds')
 
 ```javascript
 const {
-  MCPServer,             // MCP server for AI agents
+  // AiBridge — Multi-Provider LLM
+  AiBridgeManager,       // Main manager (chat, stream, embeddings, images, TTS, STT, tools)
+  AiBridge,              // Static facade
+  // AiBridge Support
+  Message,               // Chat message value object
+  Document,              // File/URL/base64 attachment
+  StreamChunk,           // Streaming DTO
+  ToolContract,          // Base class for function calling tools
+  ProviderError,         // Error handling
+  FileSecurity,          // Attachment validation
+  JsonSchemaValidator,   // Structured output validation
+  // ORM AI Features
+  AIQueryBuilder,        // Natural language → SQL
+  AISeeder,              // AI-powered data seeding
+  AIQueryOptimizer,      // SQL optimization
+  AIPromptEnhancer,      // Schema/code generation from descriptions
+  PromptGenerator,       // Regex-based offline scaffolding
+  // AI Agent Integration
+  MCPServer,             // MCP server for AI agents (13 tools)
   AISafetyGuardrails,    // AI agent detection & safety
-  PromptGenerator        // Natural language project generation
 } = require('outlet-orm');
 ```

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": "9.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",