outlet-orm 7.0.0 → 9.0.0

package/src/AI/Builders/TextBuilder.js

@@ -0,0 +1,170 @@
+'use strict';
+
+const ChatNormalizer = require('../Support/ChatNormalizer');
+const StreamChunk = require('../Support/StreamChunk');
+
+/**
+ * TextBuilder
+ * Fluent builder for text generation over AiBridge providers.
+ * Keeps method names short and explicit, reducing array option errors.
+ *
+ * @example
+ * const result = await manager.text()
+ *   .using('openai', 'gpt-4o-mini')
+ *   .withPrompt('Explain quantum computing')
+ *   .withMaxTokens(200)
+ *   .asText();
+ */
+class TextBuilder {
+  static ERR_MISSING_USING = 'Provider and model must be set via using().';
+
+  /**
+   * @param {import('../AiBridgeManager')} manager
+   */
+  constructor(manager) {
+    this._manager = manager;
+    this._provider = null;
+    this._model = null;
+    this._providerConfig = {};
+    this._messages = [];
+    this._systemPrompt = null;
+    this._maxTokens = null;
+    this._temperature = null;
+    this._topP = null;
+  }
+
+  /**
+   * Set the provider and model (required).
+   * @param {string} provider
+   * @param {string} model
+   * @param {Object} [providerConfig={}]
+   * @returns {this}
+   */
+  using(provider, model, providerConfig = {}) {
+    this._provider = provider;
+    this._model = model;
+    this._providerConfig = providerConfig;
+    return this;
+  }
+
+  /**
+   * Add a user prompt message.
+   * @param {string} text
+   * @param {Array} [attachments=[]]
+   * @returns {this}
+   */
+  withPrompt(text, attachments = []) {
+    const msg = { role: 'user', content: text };
+    if (attachments.length > 0) msg.attachments = attachments;
+    this._messages.push(msg);
+    return this;
+  }
+
+  /** Alias for withPrompt */
+  prompt(text) { return this.withPrompt(text); }
+
+  /**
+   * Set the system prompt.
+   * @param {string} text
+   * @returns {this}
+   */
+  withSystemPrompt(text) {
+    this._systemPrompt = text;
+    return this;
+  }
+
+  /** @param {number} tokens @returns {this} */
+  withMaxTokens(tokens) { this._maxTokens = tokens; return this; }
+
+  /** @param {number} t @returns {this} */
+  usingTemperature(t) { this._temperature = t; return this; }
+
+  /** @param {number} p @returns {this} */
+  usingTopP(p) { this._topP = p; return this; }
+
+  // ─── Override helpers ───
+
+  /** @param {string} key @returns {this} */
+  withApiKey(key) { this._providerConfig.api_key = key; return this; }
+  /** @param {string} ep @returns {this} */
+  withEndpoint(ep) { this._providerConfig.endpoint = ep; return this; }
+  /** @param {string} url @returns {this} */
+  withBaseUrl(url) { this._providerConfig.base_url = url; return this; }
+  /** @param {string} url @returns {this} */
+  withChatEndpoint(url) { this._providerConfig.chat_endpoint = url; return this; }
+  /** @param {string} header @param {string} [prefix='Bearer '] @returns {this} */
+  withAuthHeader(header, prefix = 'Bearer ') { this._providerConfig.auth_header = header; this._providerConfig.auth_prefix = prefix; return this; }
+  /** @param {Object} headers @returns {this} */
+  withExtraHeaders(headers) { this._providerConfig.extra_headers = headers; return this; }
+  /** @param {Object} paths @returns {this} */
+  withPaths(paths) { this._providerConfig.paths = paths; return this; }
+
+  // ─── Private helpers ───
+
+  /** @private */
+  _buildMessages() {
+    const msgs = [...this._messages];
+    if (this._systemPrompt) {
+      msgs.unshift({ role: 'system', content: this._systemPrompt });
+    }
+    return msgs;
+  }
+
+  /** @private */
+  _callOptions() {
+    const opts = { ...this._providerConfig };
+    if (this._model) opts.model = this._model;
+    if (this._maxTokens !== null) opts.max_tokens = this._maxTokens;
+    if (this._temperature !== null) opts.temperature = this._temperature;
+    if (this._topP !== null) opts.top_p = this._topP;
+    return opts;
+  }
+
+  // ─── Terminal methods ───
+
+  /**
+   * Execute and return normalized text response.
+   * @returns {Promise<{text: string, raw: Object, usage: Object|null, finish_reason: string|null}>}
+   */
+  async asText() {
+    if (!this._provider || !this._model) throw new Error(TextBuilder.ERR_MISSING_USING);
+    const res = await this._manager.chat(this._provider, this._buildMessages(), this._callOptions());
+    const norm = ChatNormalizer.normalize(res);
+    return {
+      text: norm.text || '',
+      raw: res,
+      usage: norm.usage || null,
+      finish_reason: norm.finish_reason || null,
+    };
+  }
+
+  /**
+   * Execute and return raw provider response.
+   * @returns {Promise<Object>}
+   */
+  async asRaw() {
+    if (!this._provider || !this._model) throw new Error(TextBuilder.ERR_MISSING_USING);
+    return this._manager.chat(this._provider, this._buildMessages(), this._callOptions());
+  }
+
+  /**
+   * Execute as a streaming generator of StreamChunk objects.
+   * @returns {AsyncGenerator<StreamChunk>}
+   */
+  async *asStream() {
+    if (!this._provider || !this._model) throw new Error(TextBuilder.ERR_MISSING_USING);
+    for await (const chunk of this._manager.stream(this._provider, this._buildMessages(), this._callOptions())) {
+      if (typeof chunk === 'string') {
+        yield StreamChunk.delta(chunk);
+      } else if (chunk && typeof chunk === 'object') {
+        const text = String(chunk.delta || chunk.text || '');
+        yield new StreamChunk(text, chunk.usage || null, chunk.finish_reason || null,
+          chunk.type || 'delta', chunk.tool_calls || [], chunk.tool_results || []);
+      } else {
+        yield StreamChunk.delta(String(chunk));
+      }
+    }
+  }
+}
+
+module.exports = TextBuilder;

package/src/AI/Contracts/AudioProviderContract.js

@@ -0,0 +1,29 @@
+'use strict';
+
+/**
+ * AudioProviderContract
+ * Base class for providers that support text-to-speech and speech-to-text.
+ */
+class AudioProviderContract {
+  /**
+   * Text to speech.
+   * @param {string} text
+   * @param {Object} [options={}]
+   * @returns {Promise<{audio: string, mime: string}>} audio is base64-encoded
+   */
+  async textToSpeech(text, options = {}) {
+    throw new Error('Not implemented: textToSpeech()');
+  }
+
+  /**
+   * Speech to text.
+   * @param {string} filePath
+   * @param {Object} [options={}]
+   * @returns {Promise<{text: string, raw?: Object}>}
+   */
+  async speechToText(filePath, options = {}) {
+    throw new Error('Not implemented: speechToText()');
+  }
+}
+
+module.exports = AudioProviderContract;

package/src/AI/Contracts/ChatProviderContract.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * ChatProviderContract
+ * Base class defining the chat provider interface.
+ * All chat providers must extend this and implement its methods.
+ */
+class ChatProviderContract {
+  /**
+   * Send a chat message and return raw provider response object.
+   * @param {Array<{role: string, content: string}>} messages
+   * @param {Object} [options={}]
+   * @returns {Promise<Object>}
+   */
+  async chat(messages, options = {}) {
+    throw new Error('Not implemented: chat()');
+  }
+
+  /**
+   * Stream a chat completion (async generator yielding chunks of text or objects).
+   * @param {Array<{role: string, content: string}>} messages
+   * @param {Object} [options={}]
+   * @yields {string|Object}
+   */
+  async *stream(messages, options = {}) {
+    throw new Error('Not implemented: stream()');
+  }
+
+  /**
+   * Whether this provider supports streaming.
+   * @returns {boolean}
+   */
+  supportsStreaming() {
+    return false;
+  }
+}
+
+module.exports = ChatProviderContract;

package/src/AI/Contracts/EmbeddingsProviderContract.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * EmbeddingsProviderContract
+ * Base class for providers that support embeddings generation.
+ */
+class EmbeddingsProviderContract {
+  /**
+   * Generate embeddings for one or multiple inputs.
+   * @param {string[]} inputs
+   * @param {Object} [options={}]
+   * @returns {Promise<{embeddings: number[][], usage?: Object, raw?: Object}>}
+   */
+  async embeddings(inputs, options = {}) {
+    throw new Error('Not implemented: embeddings()');
+  }
+}
+
+module.exports = EmbeddingsProviderContract;

package/src/AI/Contracts/ImageProviderContract.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * ImageProviderContract
+ * Base class for providers that support image generation.
+ */
+class ImageProviderContract {
+  /**
+   * Generate images from a prompt.
+   * @param {string} prompt
+   * @param {Object} [options={}]
+   * @returns {Promise<{images: Array, meta?: Object, raw?: Object}>}
+   */
+  async generateImage(prompt, options = {}) {
+    throw new Error('Not implemented: generateImage()');
+  }
+}
+
+module.exports = ImageProviderContract;

package/src/AI/Contracts/ModelsProviderContract.js

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * ModelsProviderContract
+ * Base class for providers that support listing models.
+ */
+class ModelsProviderContract {
+  /**
+   * List models metadata as returned by the provider.
+   * @returns {Promise<Array>}
+   */
+  async listModels() {
+    throw new Error('Not implemented: listModels()');
+  }
+
+  /**
+   * Retrieve a single model metadata by id/name.
+   * @param {string} id
+   * @returns {Promise<Object>}
+   */
+  async getModel(id) {
+    throw new Error('Not implemented: getModel()');
+  }
+}
+
+module.exports = ModelsProviderContract;

package/src/AI/Contracts/ToolContract.js

@@ -0,0 +1,25 @@
+'use strict';
+
+/**
+ * ToolContract
+ * Base class for tools usable by AI providers (function calling).
+ */
+class ToolContract {
+  /** @returns {string} */
+  name() { throw new Error('Not implemented: name()'); }
+
+  /** @returns {string} */
+  description() { throw new Error('Not implemented: description()'); }
+
+  /** @returns {Object} JSON Schema of parameters */
+  schema() { throw new Error('Not implemented: schema()'); }
+
+  /**
+   * Execute the tool with given arguments. Must return a string result.
+   * @param {Object} args
+   * @returns {Promise<string>|string}
+   */
+  execute(args) { throw new Error('Not implemented: execute()'); }
+}
+
+module.exports = ToolContract;

package/src/AI/Facades/AiBridge.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * AiBridge Facade
+ *
+ * Convenience entry-point mirroring AiBridge\Facades\AiBridge in PHP.
+ * Provides static-like helpers that delegate to an AiBridgeManager instance.
+ */
+
+const ImageNormalizer      = require('../Support/ImageNormalizer');
+const AudioNormalizer      = require('../Support/AudioNormalizer');
+const EmbeddingsNormalizer = require('../Support/EmbeddingsNormalizer');
+
+let _manager = null;
+
+const AiBridge = {
+  /**
+   * Bind an AiBridgeManager instance so all helpers delegate to it.
+   * @param {import('../AiBridgeManager')} manager
+   */
+  setManager(manager) {
+    _manager = manager;
+  },
+
+  /**
+   * Return the bound manager (or null).
+   * @returns {import('../AiBridgeManager')|null}
+   */
+  getManager() {
+    return _manager;
+  },
+
+  /* ─── Normalization helpers (static, no manager needed) ────── */
+
+  normalizeImages(raw) {
+    return ImageNormalizer.normalize(raw);
+  },
+
+  normalizeTTSAudio(raw) {
+    return AudioNormalizer.normalizeTTS(raw);
+  },
+
+  normalizeSTTAudio(raw) {
+    return AudioNormalizer.normalizeSTT(raw);
+  },
+
+  normalizeEmbeddings(raw) {
+    return EmbeddingsNormalizer.normalize(raw);
+  },
+
+  /* ─── Delegated helpers (require bound manager) ────────────── */
+
+  /**
+   * Create a new TextBuilder via the bound manager.
+   * @returns {import('../Builders/TextBuilder')}
+   */
+  text() {
+    if (!_manager) throw new Error('AiBridge facade: no manager bound. Call AiBridge.setManager(manager) first.');
+    return _manager.text();
+  },
+
+  /**
+   * Shorthand for manager.chat()
+   */
+  async chat(messages, opts) {
+    if (!_manager) throw new Error('AiBridge facade: no manager bound.');
+    return _manager.chat(messages, opts);
+  },
+
+  /**
+   * Shorthand for manager.provider()
+   */
+  provider(name) {
+    if (!_manager) throw new Error('AiBridge facade: no manager bound.');
+    return _manager.provider(name);
+  },
+};
+
+module.exports = AiBridge;

package/src/AI/MCPServer.js

@@ -112,6 +112,33 @@ const TOOL_DEFINITIONS = [
       },
       required: ['filePath', 'consent']
     }
+  },
+  {
+    name: 'ai_query',
+    description: 'Convert a natural language question into SQL and execute it. Requires an AI provider (AiBridge).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        question: { type: 'string', description: 'Natural language question, e.g. "Show me the top 5 users by order count"' },
+        provider: { type: 'string', description: 'AI provider to use (default: openai)' },
+        model: { type: 'string', description: 'AI model to use (default: gpt-4o-mini)' },
+        safe_mode: { type: 'boolean', description: 'Only allow SELECT queries (default: true)' }
+      },
+      required: ['question']
+    }
+  },
+  {
+    name: 'query_optimize',
+    description: 'Analyze a SQL query using AI and return optimization suggestions, rewritten query, and index recommendations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sql: { type: 'string', description: 'The SQL query to optimize' },
+        provider: { type: 'string', description: 'AI provider to use (default: openai)' },
+        model: { type: 'string', description: 'AI model to use (default: gpt-4o-mini)' }
+      },
+      required: ['sql']
+    }
   }
 ];
 
@@ -313,6 +340,8 @@ class MCPServer extends EventEmitter {
     case 'model_list':        return this._toolModelList();
     case 'backup_create':     return this._toolBackupCreate(args);
     case 'backup_restore':    return this._toolBackupRestore(args);
+    case 'ai_query':          return this._toolAiQuery(args);
+    case 'query_optimize':    return this._toolQueryOptimize(args);
     default:
       throw new Error(`Unknown tool: ${name}`);
     }
@@ -610,6 +639,90 @@ class MCPServer extends EventEmitter {
     return `Backup restored from: ${args.filePath}`;
   }
 
+  // ── ai_query (NL → SQL) ───────────────────────────────────────
+
+  async _toolAiQuery(args) {
+    if (!args.question) throw new Error('A natural language question is required.');
+    const conn = await this._getConnection();
+    const manager = this._getAiBridgeManager();
+    if (!manager) throw new Error('AiBridge is not configured. Set OPENAI_API_KEY or configure a provider.');
+
+    const AIQueryBuilder = require('./AIQueryBuilder');
+    const builder = new AIQueryBuilder(manager, conn);
+
+    if (args.provider || args.model) {
+      builder.using(args.provider || 'openai', args.model || 'gpt-4o-mini');
+    }
+    if (args.safe_mode === false) {
+      builder.safeMode(false);
+    }
+
+    const result = await builder.query(args.question);
+    return {
+      sql: result.sql,
+      params: result.params,
+      explanation: result.explanation,
+      results: result.results,
+      error: result.error || null
+    };
+  }
+
+  // ── query_optimize ─────────────────────────────────────────────
+
+  async _toolQueryOptimize(args) {
+    if (!args.sql) throw new Error('SQL query is required.');
+    const conn = await this._getConnection();
+    const manager = this._getAiBridgeManager();
+    if (!manager) throw new Error('AiBridge is not configured. Set OPENAI_API_KEY or configure a provider.');
+
+    const AIQueryOptimizer = require('./AIQueryOptimizer');
+    const optimizer = new AIQueryOptimizer(manager, conn);
+
+    if (args.provider || args.model) {
+      optimizer.using(args.provider || 'openai', args.model || 'gpt-4o-mini');
+    }
+
+    const result = await optimizer.optimize(args.sql);
+    return {
+      original: result.original,
+      optimized: result.optimized,
+      suggestions: result.suggestions,
+      explanation: result.explanation,
+      indexes: result.indexes
+    };
+  }
+
+  // ── AiBridge manager helper ────────────────────────────────────
+
+  /**
+   * Lazily creates an AiBridge manager from environment variables.
+   * @returns {import('./Bridge/AiBridgeManager')|null}
+   */
+  _getAiBridgeManager() {
+    if (this._aiBridgeManager) return this._aiBridgeManager;
+
+    try {
+      const AiBridgeManager = require('./AiBridgeManager');
+      const config = {};
+
+      // Auto-detect providers from env
+      if (process.env.OPENAI_API_KEY)   config.openai   = { api_key: process.env.OPENAI_API_KEY };
+      if (process.env.OLLAMA_ENDPOINT)  config.ollama   = { endpoint: process.env.OLLAMA_ENDPOINT };
+      if (process.env.CLAUDE_API_KEY)   config.claude   = { api_key: process.env.CLAUDE_API_KEY };
+      if (process.env.GEMINI_API_KEY)   config.gemini   = { api_key: process.env.GEMINI_API_KEY };
+      if (process.env.GROK_API_KEY)     config.grok     = { api_key: process.env.GROK_API_KEY };
+      if (process.env.MISTRAL_API_KEY)  config.mistral  = { api_key: process.env.MISTRAL_API_KEY };
+      if (process.env.ONN_API_KEY)      config.onn      = { api_key: process.env.ONN_API_KEY };
+
+      if (Object.keys(config).length === 0) return null;
+
+      this._aiBridgeManager = new AiBridgeManager(config);
+      return this._aiBridgeManager;
+    } catch {
+      return null;
+    }
+  }
+
   // ─── Template helpers ──────────────────────────────────────────
 
   _extractTableName(migrationName) {

package/src/AI/Providers/ClaudeProvider.js

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * ClaudeProvider
+ * Anthropic Messages API. System messages are converted to user role.
+ * Streaming is simulated via chunk-splitting (60-char chunks).
+ */
+class ClaudeProvider {
+  /**
+   * @param {string} apiKey
+   * @param {string} [endpoint='https://api.anthropic.com/v1/messages']
+   */
+  constructor(apiKey, endpoint = 'https://api.anthropic.com/v1/messages') {
+    this.apiKey = apiKey;
+    this.endpoint = endpoint;
+  }
+
+  /** @private */
+  _headers() {
+    return {
+      'x-api-key': this.apiKey,
+      'anthropic-version': '2023-06-01',
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+    };
+  }
+
+  async chat(messages, options = {}) {
+    // Convert system messages to user role (Claude requirement)
+    const converted = messages.map(m => {
+      if ((m.role || '') === 'system') return { role: 'user', content: m.content };
+      return m;
+    });
+
+    const payload = {
+      model: options.model || 'claude-3-opus-20240229',
+      max_tokens: options.max_tokens || 512,
+      messages: converted,
+    };
+    if (options.temperature !== undefined) payload.temperature = options.temperature;
+
+    const res = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: this._headers(),
+      body: JSON.stringify(payload),
+    });
+    const data = await res.json();
+    return data || {};
+  }
+
+  async *stream(messages, options = {}) {
+    const full = await this.chat(messages, options);
+    let text = '';
+    if (full?.content?.[0]?.text) text = full.content[0].text;
+    // Simulated: yield 60-char chunks
+    for (let i = 0; i < text.length; i += 60) {
+      yield text.slice(i, i + 60);
+    }
+  }
+
+  supportsStreaming() { return true; } // simulated
+}
+
+module.exports = ClaudeProvider;