outlet-orm 7.0.0 → 9.0.1

package/src/AI/AiBridgeManager.js

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

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;