outlet-orm 7.0.0 → 9.0.0

package/src/AI/Support/DocumentAttachmentMapper.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const Document = require('./Document');
+const FileSecurity = require('./FileSecurity');
+
+const IMAGE_PREFIX = 'image/';
+
+/**
+ * DocumentAttachmentMapper
+ * Converts Document attachments to provider-specific formats.
+ */
+class DocumentAttachmentMapper {
+  /**
+   * Split attachments into files, images, and inline texts for Ollama-compatible providers.
+   * @param {Array} attachments
+   * @returns {{files: Array, image_files: string[], inlineTexts: string[]}}
+   */
+  static toOllamaOptions(attachments) {
+    const files = [];
+    const images = [];
+    const inlineTexts = [];
+    const sec = FileSecurity.fromDefaults();
+
+    for (const att of attachments) {
+      if (att instanceof Document) {
+        switch (att.kind) {
+          case 'text':
+            if (att.text != null) inlineTexts.push(att.text);
+            break;
+          case 'local':
+            if (att.path && sec.validateFile(att.path)) {
+              const mime = att.mime || 'application/octet-stream';
+              const b64 = fs.readFileSync(att.path).toString('base64');
+              if (mime.startsWith(IMAGE_PREFIX)) {
+                images.push(b64);
+              } else {
+                files.push({ name: path.basename(att.path), type: mime, content: b64 });
+              }
+            }
+            break;
+          case 'base64':
+            if (att.base64 && att.mime) {
+              if (att.mime.startsWith(IMAGE_PREFIX)) {
+                images.push(att.base64);
+              } else {
+                files.push({ name: att.title || 'document', type: att.mime, content: att.base64 });
+              }
+            }
+            break;
+          case 'raw':
+            if (att.raw && att.mime) {
+              const b64 = Buffer.from(att.raw).toString('base64');
+              if (att.mime.startsWith(IMAGE_PREFIX)) {
+                images.push(b64);
+              } else {
+                files.push({ name: att.title || 'document', type: att.mime, content: b64 });
+              }
+            }
+            break;
+          case 'chunks':
+            for (const c of att.chunks) inlineTexts.push(String(c));
+            break;
+          case 'url':
+          case 'file_id':
+          default:
+            break;
+        }
+      } else if (typeof att === 'string' && sec.validateFile(att)) {
+        const b64 = fs.readFileSync(att).toString('base64');
+        const mime = 'application/octet-stream';
+        files.push({ name: path.basename(att), type: mime, content: b64 });
+      }
+    }
+
+    return { files, image_files: images, inlineTexts };
+  }
+
+  /**
+   * Extract inline text content from attachments (for OpenAI-style providers).
+   * @param {Array} attachments
+   * @returns {string[]}
+   */
+  static extractInlineTexts(attachments) {
+    const inline = [];
+    for (const att of attachments) {
+      if (att instanceof Document) {
+        if (att.kind === 'text' && att.text != null) inline.push(att.text);
+        if (att.kind === 'chunks') {
+          for (const c of att.chunks) inline.push(String(c));
+        }
+      } else if (typeof att === 'string') {
+        inline.push(att);
+      }
+    }
+    return inline;
+  }
+}
+
+module.exports = DocumentAttachmentMapper;

package/src/AI/Support/EmbeddingsNormalizer.js

@@ -0,0 +1,30 @@
+'use strict';
+
+/**
+ * EmbeddingsNormalizer
+ * Normalizes embeddings responses into a unified shape.
+ */
+class EmbeddingsNormalizer {
+  /**
+   * @param {Object} raw
+   * @returns {{vectors: number[][], usage: Object, raw: Object}}
+   */
+  static normalize(raw) {
+    let vectors = [];
+    let usage = {};
+
+    if (Array.isArray(raw?.data)) {
+      vectors = raw.data.map(d => d.embedding || []);
+      usage = raw.usage || {};
+    } else if (Array.isArray(raw?.embeddings)) {
+      vectors = raw.embeddings;
+    } else if (raw?.embedding?.values) {
+      // Gemini single embedding format
+      vectors = [raw.embedding.values];
+    }
+
+    return { vectors, usage, raw };
+  }
+}
+
+module.exports = EmbeddingsNormalizer;

package/src/AI/Support/Exceptions/ProviderError.js

@@ -0,0 +1,22 @@
+'use strict';
+
+/**
+ * ProviderError
+ * Custom error for provider-related issues.
+ */
+class ProviderError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ProviderError';
+  }
+
+  static notFound(name) {
+    return new ProviderError(`Provider '${name}' not found`);
+  }
+
+  static unsupported(name, feature) {
+    return new ProviderError(`Provider '${name}' does not support ${feature}`);
+  }
+}
+
+module.exports = ProviderError;

package/src/AI/Support/FileSecurity.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('fs');
+
+/**
+ * FileSecurity
+ * Enforces file size and MIME type constraints for uploads.
+ */
+class FileSecurity {
+  /**
+   * @param {Object} [config={}]
+   * @param {number} [config.max_file_bytes=10485760] - 10MB default
+   * @param {string[]} [config.allowed_mime_files]
+   * @param {string[]} [config.allowed_mime_images]
+   */
+  constructor(config = {}) {
+    this.maxBytes = config.max_file_bytes || 10 * 1024 * 1024;
+    this.allowedFiles = config.allowed_mime_files || [
+      'text/plain', 'application/pdf', 'application/json',
+      'text/csv', 'text/html', 'text/markdown',
+      'application/xml', 'text/xml'
+    ];
+    this.allowedImages = config.allowed_mime_images || [
+      'image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/svg+xml'
+    ];
+  }
+
+  /**
+   * Validate a file against size and type constraints.
+   * @param {string} filePath
+   * @param {boolean} [image=false]
+   * @returns {boolean}
+   */
+  validateFile(filePath, image = false) {
+    try {
+      if (!fs.existsSync(filePath)) return false;
+      const stats = fs.statSync(filePath);
+      if (stats.size > this.maxBytes) return false;
+      // In Node.js we don't have mime_content_type; basic extension check
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Create a FileSecurity instance with default configuration.
+   * @returns {FileSecurity}
+   */
+  static fromDefaults() {
+    const maxBytes = parseInt(process.env.AI_MAX_FILE_BYTES, 10) || 10 * 1024 * 1024;
+    return new FileSecurity({ max_file_bytes: maxBytes });
+  }
+}
+
+module.exports = FileSecurity;

package/src/AI/Support/ImageNormalizer.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const DEFAULT_MIME = 'image/png';
+
+/**
+ * ImageNormalizer
+ * Normalizes heterogeneous image responses into a common array of items.
+ */
+class ImageNormalizer {
+  /**
+   * @param {Object} raw
+   * @returns {Array<{type: string, url?: string, data?: string, mime?: string}>}
+   */
+  static normalize(raw) {
+    let items = ImageNormalizer._fromOpenAI(raw);
+    if (items.length > 0) return items;
+    items = ImageNormalizer._fromOllama(raw);
+    if (items.length > 0) return items;
+    return ImageNormalizer._fromDataUrl(raw);
+  }
+
+  /** @private */
+  static _fromOpenAI(raw) {
+    const out = [];
+    if (!Array.isArray(raw?.data)) return out;
+    for (const d of raw.data) {
+      if (d.url) {
+        out.push({ type: 'url', url: d.url });
+      } else if (d.b64_json) {
+        out.push({ type: 'b64', mime: DEFAULT_MIME, data: d.b64_json });
+      }
+    }
+    return out;
+  }
+
+  /** @private */
+  static _fromOllama(raw) {
+    const out = [];
+    if (!Array.isArray(raw?.images)) return out;
+    for (const img of raw.images) {
+      const b64 = img.b64 || img;
+      if (typeof b64 === 'string' && b64 !== '') {
+        out.push({ type: 'b64', mime: DEFAULT_MIME, data: b64 });
+      }
+    }
+    return out;
+  }
+
+  /** @private */
+  static _fromDataUrl(raw) {
+    const out = [];
+    const resp = raw?.response;
+    if (typeof resp !== 'string' || !resp.startsWith('data:image')) return out;
+    const match = resp.match(/^data:([^;]+);base64,(.*)$/);
+    if (match) {
+      out.push({ type: 'b64', mime: match[1] || DEFAULT_MIME, data: match[2] || '' });
+    }
+    return out;
+  }
+}
+
+module.exports = ImageNormalizer;

package/src/AI/Support/JsonSchemaValidator.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * JsonSchemaValidator
+ * Performs recursive JSON Schema validation on structured outputs.
+ */
+class JsonSchemaValidator {
+  /**
+   * Validate data against a JSON Schema.
+   * @param {*} data
+   * @param {Object} schema
+   * @returns {{valid: boolean, errors: string[]}}
+   */
+  static validate(data, schema) {
+    const errors = [];
+    JsonSchemaValidator._validateNode(data, schema, '$', errors);
+    return { valid: errors.length === 0, errors };
+  }
+
+  /** @private */
+  static _validateNode(value, schema, path, errors) {
+    const type = schema.type;
+    if (type) {
+      if (type === 'object' && (typeof value !== 'object' || value === null || Array.isArray(value))) {
+        errors.push(`${path}: expected object`);
+        return;
+      }
+      if (type === 'array' && !Array.isArray(value)) {
+        errors.push(`${path}: expected array`);
+        return;
+      }
+      if (type === 'string' && typeof value !== 'string') {
+        errors.push(`${path}: expected string`);
+        return;
+      }
+      if (type === 'number' && typeof value !== 'number') {
+        errors.push(`${path}: expected number`);
+        return;
+      }
+      if (type === 'boolean' && typeof value !== 'boolean') {
+        errors.push(`${path}: expected boolean`);
+        return;
+      }
+      if (type === 'integer' && (!Number.isInteger(value))) {
+        errors.push(`${path}: expected integer`);
+        return;
+      }
+    }
+
+    if (type === 'object' && typeof value === 'object' && value !== null) {
+      const props = schema.properties || {};
+      const required = schema.required || [];
+      for (const req of required) {
+        if (!(req in value)) {
+          errors.push(`${path}.${req}: required missing`);
+        }
+      }
+      for (const [k, v] of Object.entries(value)) {
+        if (props[k]) {
+          JsonSchemaValidator._validateNode(v, props[k], `${path}.${k}`, errors);
+        }
+      }
+    }
+
+    if (type === 'array' && Array.isArray(value) && schema.items) {
+      for (let i = 0; i < value.length; i++) {
+        JsonSchemaValidator._validateNode(value[i], schema.items, `${path}[${i}]`, errors);
+      }
+    }
+  }
+}
+
+module.exports = JsonSchemaValidator;

package/src/AI/Support/Message.js

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * Message
+ * Value object for chat messages with optional attachments.
+ */
+class Message {
+  /**
+   * @param {string} role
+   * @param {string} content
+   * @param {Array} [attachments=[]]
+   */
+  constructor(role, content, attachments = []) {
+    this.role = role;
+    this.content = content;
+    this.attachments = attachments;
+  }
+
+  static user(content, attachments = []) {
+    return new Message('user', content, attachments);
+  }
+
+  static system(content) {
+    return new Message('system', content);
+  }
+
+  static assistant(content) {
+    return new Message('assistant', content);
+  }
+
+  toObject() {
+    const obj = { role: this.role, content: this.content };
+    if (this.attachments.length > 0) {
+      obj.attachments = this.attachments;
+    }
+    return obj;
+  }
+}
+
+module.exports = Message;

package/src/AI/Support/StreamChunk.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * StreamChunk
+ * Structured DTO for streaming responses.
+ */
+class StreamChunk {
+  /**
+   * @param {string} [text='']
+   * @param {Object|null} [usage=null]
+   * @param {string|null} [finishReason=null]
+   * @param {string} [chunkType='delta'] - 'delta' | 'end' | 'tool_call' | 'tool_result'
+   * @param {Array} [toolCalls=[]]
+   * @param {Array} [toolResults=[]]
+   */
+  constructor(text = '', usage = null, finishReason = null, chunkType = 'delta', toolCalls = [], toolResults = []) {
+    this.text = text;
+    this.usage = usage;
+    this.finishReason = finishReason;
+    this.chunkType = chunkType;
+    this.toolCalls = toolCalls;
+    this.toolResults = toolResults;
+  }
+
+  /**
+   * Create a delta (text) chunk.
+   * @param {string} text
+   * @returns {StreamChunk}
+   */
+  static delta(text) {
+    return new StreamChunk(text, null, null, 'delta');
+  }
+
+  /**
+   * Create an end-of-stream chunk.
+   * @param {string|null} [finishReason='stop']
+   * @param {Object|null} [usage=null]
+   * @returns {StreamChunk}
+   */
+  static end(finishReason = 'stop', usage = null) {
+    return new StreamChunk('', usage, finishReason, 'end');
+  }
+}
+
+module.exports = StreamChunk;

package/src/AI/Support/ToolChatRunner.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * ToolChatRunner
+ * Provider-agnostic tool-calling loop.
+ * Injects a system prompt listing available tools, parses model JSON responses,
+ * executes tools, and iterates until model gives a normal text reply.
+ */
+class ToolChatRunner {
+  /**
+   * @param {import('../AiBridgeManager')} manager
+   */
+  constructor(manager) {
+    this.manager = manager;
+  }
+
+  /**
+   * Run a tool-aware chat loop.
+   * @param {string} provider
+   * @param {Array} messages
+   * @param {Object} [options={}]
+   * @returns {Promise<{final?: Object, tool_calls: Array, error?: string}>}
+   */
+  async run(provider, messages, options = {}) {
+    const tools = this.manager.tools();
+    if (Object.keys(tools).length === 0) {
+      const final = await this.manager.chat(provider, messages, options);
+      return { final, tool_calls: [] };
+    }
+
+    messages = this._injectToolInstructionIfMissing(messages, tools);
+
+    const state = {
+      tool_calls: [],
+      messages: [...messages],
+      iterations: 0,
+      max: options.max_tool_iterations || 5,
+      provider,
+      options,
+      final: null,
+      done: false,
+    };
+
+    while (!state.done && state.iterations < state.max) {
+      await this._iteration(state);
+    }
+
+    if (!state.final) {
+      return { error: 'tool_iteration_limit_reached', tool_calls: state.tool_calls };
+    }
+    return { final: state.final, tool_calls: state.tool_calls };
+  }
+
+  /** @private */
+  _injectToolInstructionIfMissing(messages, tools) {
+    const instruction = this._buildToolInstruction(tools);
+    for (const m of messages) {
+      if (m.role === 'system' && (m.content || '').includes('Tools:')) {
+        return messages;
+      }
+    }
+    return [{ role: 'system', content: instruction }, ...messages];
+  }
+
+  /** @private */
+  async _iteration(state) {
+    state.iterations++;
+    const response = await this.manager.chat(state.provider, state.messages, state.options);
+    const assistant = this._extractAssistantContent(response);
+
+    if (assistant === null) {
+      state.final = response;
+      state.done = true;
+      return;
+    }
+
+    const toolCalls = this._parseToolCalls(assistant);
+    if (toolCalls.length === 0) {
+      state.final = response;
+      state.done = true;
+      return;
+    }
+
+    const executed = await this._executeToolCalls(toolCalls);
+    for (const call of executed) {
+      state.tool_calls.push(call);
+      state.messages.push({ role: 'tool', name: call.name, content: call.result });
+    }
+    state.messages.push({
+      role: 'user',
+      content: 'If more tools are needed respond only with JSON tool_calls; otherwise respond normally.'
+    });
+  }
+
+  /** @private */
+  async _executeToolCalls(toolCalls) {
+    const out = [];
+    for (const call of toolCalls) {
+      const name = call.name;
+      const args = call.arguments || {};
+      if (!name) continue;
+      const tool = this.manager.tool(name);
+      if (!tool) continue;
+      let result;
+      try {
+        result = await tool.execute(typeof args === 'object' ? args : {});
+      } catch (e) {
+        result = `Tool execution error: ${e.message}`;
+      }
+      out.push({ name, arguments: args, result });
+    }
+    return out;
+  }
+
+  /** @private */
+  _buildToolInstruction(tools) {
+    const specs = Object.values(tools).map(t => ({
+      name: t.name(),
+      description: t.description(),
+      schema: t.schema(),
+    }));
+    return `You have access to the following tools. To request tool execution, respond STRICTLY with JSON of the form {"tool_calls":[{"name":"toolName","arguments":{...}}]} without additional text. Tools: ${JSON.stringify(specs)}`;
+  }
+
+  /** @private */
+  _extractAssistantContent(response) {
+    if (response?.choices?.[0]?.message?.content != null) return response.choices[0].message.content;
+    if (response?.message?.content != null) return response.message.content;
+    if (response?.content?.[0]?.text != null) return response.content[0].text;
+    if (response?.output_text != null) return response.output_text;
+    return null;
+  }
+
+  /** @private */
+  _parseToolCalls(content) {
+    let candidate = content.trim();
+    // Extract from markdown code blocks
+    const codeMatch = candidate.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (codeMatch) candidate = codeMatch[1].trim();
+
+    let decoded;
+    try {
+      decoded = JSON.parse(candidate);
+    } catch {
+      // Try to extract a JSON object from the content
+      const objMatch = candidate.match(/\{[^{}]*\}/s);
+      if (objMatch) {
+        try { decoded = JSON.parse(objMatch[0]); } catch { return []; }
+      }
+    }
+
+    if (decoded && typeof decoded === 'object') {
+      if (Array.isArray(decoded.tool_calls)) return decoded.tool_calls;
+      if (Array.isArray(decoded) && decoded[0] && 'name' in decoded[0]) return decoded;
+    }
+    return [];
+  }
+}
+
+module.exports = ToolChatRunner;

package/src/AI/Support/ToolRegistry.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * ToolRegistry
+ * Registry of named tools for function calling.
+ */
+class ToolRegistry {
+  constructor() {
+    /** @type {Map<string, import('../Contracts/ToolContract')>} */
+    this._tools = new Map();
+  }
+
+  /**
+   * Register a tool.
+   * @param {import('../Contracts/ToolContract')} tool
+   * @returns {this}
+   */
+  register(tool) {
+    this._tools.set(tool.name(), tool);
+    return this;
+  }
+
+  /**
+   * Get a tool by name.
+   * @param {string} name
+   * @returns {import('../Contracts/ToolContract')|null}
+   */
+  get(name) {
+    return this._tools.get(name) || null;
+  }
+
+  /**
+   * Get all registered tools as an object keyed by name.
+   * @returns {Object<string, import('../Contracts/ToolContract')>}
+   */
+  all() {
+    const out = {};
+    for (const [k, v] of this._tools) {
+      out[k] = v;
+    }
+    return out;
+  }
+
+  /**
+   * Check if a tool is registered.
+   * @param {string} name
+   * @returns {boolean}
+   */
+  has(name) {
+    return this._tools.has(name);
+  }
+
+  /**
+   * Number of registered tools.
+   * @returns {number}
+   */
+  get size() {
+    return this._tools.size;
+  }
+}
+
+module.exports = ToolRegistry;

package/src/AI/Tools/SystemInfoTool.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const os = require('os');
+const ToolContract = require('../Contracts/ToolContract');
+
+/**
+ * SystemInfoTool
+ * Built-in example tool returning system information.
+ */
+class SystemInfoTool extends ToolContract {
+  name() { return 'system_info'; }
+  description() { return 'Returns system information (node_version, platform, arch)'; }
+  schema() { return { type: 'object', properties: {}, required: [] }; }
+
+  execute(_args) {
+    return JSON.stringify({
+      node_version: process.version,
+      platform: os.platform(),
+      arch: os.arch(),
+      uptime: os.uptime(),
+    });
+  }
+}
+
+module.exports = SystemInfoTool;