millas 0.2.12-beta-2 → 0.2.13

package/src/ai/files.js

@@ -0,0 +1,249 @@
+'use strict';
+
+const { AIError, AIProviderError } = require('./types');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIFile — a file stored with an AI provider
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIFile {
+  constructor({ id, filename, mimeType, size, provider, createdAt }) {
+    this.id         = id;
+    this.filename   = filename;
+    this.mimeType   = mimeType;
+    this.size       = size;
+    this.provider   = provider;
+    this.createdAt  = createdAt;
+  }
+
+  mimeType() { return this.mimeType; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PendingFile — fluent builder for uploading a file to a provider
+// ─────────────────────────────────────────────────────────────────────────────
+
+class PendingFile {
+  constructor(manager, source) {
+    this._manager  = manager;
+    this._source   = source;   // { type: 'path'|'storage'|'url'|'buffer'|'id', value, mimeType, filename }
+    this._provider = null;
+    this._purpose  = 'assistants';
+  }
+
+  using(provider)  { this._provider = provider;  return this; }
+  purpose(p)       { this._purpose  = p;          return this; }
+
+  /**
+   * Upload the file to the provider.
+   * Returns AIFile with the stored file's ID.
+   *
+   *   const f = await AI.files.fromPath('/report.pdf').put();
+   *   console.log(f.id); // 'file-abc123'
+   */
+  async put(provider = null) {
+    const prov   = provider || this._provider || this._manager._default;
+    const driver = this._manager._resolveDriver(prov);
+    if (typeof driver.uploadFile !== 'function') {
+      throw new AIProviderError(prov, `Provider "${prov}" does not support file storage.`);
+    }
+
+    const fs   = require('fs');
+    const path = require('path');
+    const { resolveStoragePath } = require('../http/SafeFilePath');
+    let   buf, filename, mimeType;
+
+    if (this._source.type === 'path') {
+      // Guard: resolve within storage root to prevent path traversal.
+      // If the path is already absolute and within an allowed directory,
+      // resolveStoragePath returns it unchanged. If it escapes, it throws.
+      const safePath = resolveStoragePath(
+        this._source.value,
+        require('../http/SafeFilePath').SafeFilePath.getStorageRoot()
+      );
+      buf      = fs.readFileSync(safePath);
+      filename = this._source.filename || path.basename(safePath);
+      mimeType = this._source.mimeType || _mimeFromExt(path.extname(filename));
+    } else if (this._source.type === 'storage') {
+      const storage = this._manager._storage;
+      if (!storage) throw new Error('Storage service not available.');
+      buf      = await storage.get(this._source.value);
+      filename = this._source.filename || path.basename(this._source.value);
+      mimeType = this._source.mimeType || _mimeFromExt(path.extname(filename));
+    } else if (this._source.type === 'url') {
+      const res = await fetch(this._source.value);
+      buf       = Buffer.from(await res.arrayBuffer());
+      filename  = this._source.filename || path.basename(new URL(this._source.value).pathname) || 'file';
+      mimeType  = res.headers.get('content-type') || 'application/octet-stream';
+    } else if (this._source.type === 'buffer') {
+      buf      = this._source.value;
+      filename = this._source.filename || 'file';
+      mimeType = this._source.mimeType || 'application/octet-stream';
+    } else if (this._source.type === 'id') {
+      // Already stored — return a stub
+      return new AIFile({ id: this._source.value, filename: null, mimeType: null, size: null, provider: prov });
+    }
+
+    const result = await driver.uploadFile({ buf, filename, mimeType, purpose: this._purpose });
+    return new AIFile({ ...result, provider: prov });
+  }
+
+  /**
+   * Retrieve metadata for a previously stored file.
+   *
+   *   const f = await AI.files.fromId('file-abc').get();
+   */
+  async get(provider = null) {
+    if (this._source.type !== 'id') throw new Error('get() is only available on fromId().');
+    const prov   = provider || this._provider || this._manager._default;
+    const driver = this._manager._resolveDriver(prov);
+    if (typeof driver.getFile !== 'function') throw new AIProviderError(prov, `Provider "${prov}" does not support file retrieval.`);
+    const result = await driver.getFile(this._source.value);
+    return new AIFile({ ...result, provider: prov });
+  }
+
+  /**
+   * Delete a previously stored file.
+   *
+   *   await AI.files.fromId('file-abc').delete();
+   */
+  async delete(provider = null) {
+    if (this._source.type !== 'id') throw new Error('delete() is only available on fromId().');
+    const prov   = provider || this._provider || this._manager._default;
+    const driver = this._manager._resolveDriver(prov);
+    if (typeof driver.deleteFile !== 'function') throw new AIProviderError(prov, `Provider "${prov}" does not support file deletion.`);
+    return driver.deleteFile(this._source.value);
+  }
+
+  /** Use this file as an attachment in an agent prompt. */
+  toAttachment() { return { type: 'file', source: this._source }; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIFilesAPI — the AI.files namespace
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIFilesAPI {
+  constructor(manager) { this._manager = manager; }
+
+  fromPath(path, opts = {})     { return new PendingFile(this._manager, { type: 'path',    value: path, ...opts }); }
+  fromStorage(path, opts = {})  { return new PendingFile(this._manager, { type: 'storage', value: path, ...opts }); }
+  fromUrl(url, opts = {})       { return new PendingFile(this._manager, { type: 'url',     value: url,  ...opts }); }
+  fromBuffer(buf, filename, mimeType) { return new PendingFile(this._manager, { type: 'buffer', value: buf, filename, mimeType }); }
+  fromId(id)                    { return new PendingFile(this._manager, { type: 'id',      value: id   }); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIVectorStore — a vector store (collection of indexed files for RAG)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIVectorStore {
+  constructor({ id, name, provider, fileCounts = {}, ready = false, meta = {} }) {
+    this.id         = id;
+    this.name       = name;
+    this.provider   = provider;
+    this.fileCounts = fileCounts;
+    this.ready      = ready;
+    this.meta       = meta;
+  }
+
+  /**
+   * Add a file to this vector store.
+   * Accepts a file ID string, a PendingFile, or any uploadable source.
+   *
+   *   await store.add('file-abc123');
+   *   await store.add(AI.files.fromPath('/doc.pdf'));
+   *   await store.add(AI.files.fromStorage('manual.pdf'));
+   */
+  async add(fileOrId, metadata = {}) {
+    const driver = this._driver;
+    let   fileId;
+
+    if (typeof fileOrId === 'string') {
+      fileId = fileOrId;
+    } else if (fileOrId instanceof PendingFile) {
+      // Upload first then add
+      const uploaded = await fileOrId.using(this.provider).put();
+      fileId = uploaded.id;
+    } else {
+      throw new Error('store.add() expects a file ID string or PendingFile.');
+    }
+
+    return driver.addFileToStore(this.id, fileId, metadata);
+  }
+
+  /**
+   * Remove a file from this vector store.
+   *
+   *   await store.remove('file-abc123');
+   *   await store.remove('file-abc123', { deleteFile: true }); // also deletes from provider storage
+   */
+  async remove(fileId, { deleteFile = false } = {}) {
+    const driver = this._driver;
+    await driver.removeFileFromStore(this.id, fileId);
+    if (deleteFile) await driver.deleteFile(fileId);
+  }
+
+  /** Delete this entire vector store. */
+  async delete() {
+    return this._driver.deleteStore(this.id);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIStoresAPI — the AI.stores namespace
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIStoresAPI {
+  constructor(manager) { this._manager = manager; }
+
+  /**
+   * Create a new vector store.
+   *
+   *   const store = await AI.stores.create('Knowledge Base');
+   *   const store = await AI.stores.create('Docs', { description: '...', expiresIn: 86400 * 30 });
+   */
+  async create(name, opts = {}, provider = null) {
+    const prov   = provider || this._manager._default;
+    const driver = this._manager._resolveDriver(prov);
+    if (typeof driver.createStore !== 'function') throw new AIProviderError(prov, `Provider "${prov}" does not support vector stores.`);
+    const result = await driver.createStore({ name, ...opts });
+    const store  = new AIVectorStore({ ...result, provider: prov });
+    store._driver = driver;
+    return store;
+  }
+
+  /**
+   * Retrieve an existing vector store by ID.
+   *
+   *   const store = await AI.stores.get('vs_abc123');
+   */
+  async get(id, provider = null) {
+    const prov   = provider || this._manager._default;
+    const driver = this._manager._resolveDriver(prov);
+    if (typeof driver.getStore !== 'function') throw new AIProviderError(prov, `Provider "${prov}" does not support vector stores.`);
+    const result = await driver.getStore(id);
+    const store  = new AIVectorStore({ ...result, provider: prov });
+    store._driver = driver;
+    return store;
+  }
+
+  /**
+   * Delete a vector store by ID.
+   *
+   *   await AI.stores.delete('vs_abc123');
+   */
+  async delete(id, provider = null) {
+    const prov   = provider || this._manager._default;
+    const driver = this._manager._resolveDriver(prov);
+    if (typeof driver.deleteStore !== 'function') throw new AIProviderError(prov, `Provider "${prov}" does not support vector stores.`);
+    return driver.deleteStore(id);
+  }
+}
+
+function _mimeFromExt(ext) {
+  const map = { '.pdf': 'application/pdf', '.txt': 'text/plain', '.md': 'text/markdown', '.json': 'application/json', '.csv': 'text/csv', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.mp3': 'audio/mpeg', '.mp4': 'audio/mp4', '.wav': 'audio/wav' };
+  return map[(ext || '').toLowerCase()] || 'application/octet-stream';
+}
+
+module.exports = { AIFile, PendingFile, AIFilesAPI, AIVectorStore, AIStoresAPI };

package/src/ai/media.js

@@ -0,0 +1,303 @@
+'use strict';
+
+const { AIProviderError } = require('./types');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIImageResponse
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIImageResponse {
+  constructor({ images, urls = [], provider, model, prompt }) {
+    this._images   = images || [];   // array of Buffers (when b64 returned)
+    this._urls     = urls   || [];   // array of URLs (when url returned)
+    this.provider  = provider;
+    this.model     = model;
+    this.prompt    = prompt;
+  }
+
+  /** First image buffer (null if provider returned URLs instead). */
+  get buffer() { return this._images[0] || null; }
+
+  /** All image buffers. */
+  get buffers() { return this._images; }
+
+  /** First image URL (null if provider returned buffers instead). */
+  get url() { return this._urls[0] || null; }
+
+  /** All image URLs. */
+  get urls() { return this._urls; }
+
+  /** Store first image to a path using Millas Storage or write to local filesystem. */
+  async store(filePath, disk = null) {
+    if (!this.buffer) throw new Error('No image buffer available — provider returned a URL. Use img.url instead.');
+    const storage = AIImageResponse._storage;
+    if (storage) {
+      const d = disk ? storage.disk(disk) : storage;
+      await d.put(filePath, this.buffer);
+      return filePath;
+    }
+    // Fallback — write directly to filesystem
+    const fs   = require('fs');
+    const path = require('path');
+    const dir  = path.dirname(filePath);
+    if (dir && dir !== '.') fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(filePath, this.buffer);
+    return filePath;
+  }
+
+  /** Store with auto-generated extension. */
+  async storeAs(name, disk = null) {
+    const filePath = name.includes('.') ? name : `${name}.png`;
+    return this.store(filePath, disk);
+  }
+
+  toString() {
+    if (this._urls[0])    return this._urls[0];
+    if (this._images[0])  return `[AIImageResponse: ${this._images.length} image(s) from ${this.provider}]`;
+    return '[AIImageResponse: empty]';
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PendingImage
+// ─────────────────────────────────────────────────────────────────────────────
+
+class PendingImage {
+  constructor(manager, prompt) {
+    this._manager  = manager;
+    this._prompt   = prompt;
+    this._provider = null;
+    this._model    = null;
+    this._size     = null;
+    this._quality  = 'standard';
+    this._n        = 1;
+    this._aspect   = '1:1';
+    this._attachments = [];
+    this._queued   = false;
+    this._thenFns  = [];
+  }
+
+  /** Select a specific provider. */
+  using(provider)    { this._provider = provider;  return this; }
+  model(model)       { this._model    = model;     return this; }
+  quality(q)         { this._quality  = q;         return this; }
+  count(n)           { this._n        = n;         return this; }
+
+  /** 1:1 square aspect ratio (default). */
+  square()     { this._aspect = '1:1';   this._size = '1024x1024'; return this; }
+  /** 16:9 landscape. */
+  landscape()  { this._aspect = '16:9';  this._size = '1792x1024'; return this; }
+  /** 9:16 portrait. */
+  portrait()   { this._aspect = '9:16';  this._size = '1024x1792'; return this; }
+
+  /** Attach reference images. */
+  attachments(files) { this._attachments = files; return this; }
+
+  /** Queue the generation. Returns a QueuedResponse. */
+  queue() { this._queued = true; return this; }
+
+  then(fn) { this._thenFns.push(fn); return this; }
+
+  async generate() {
+    const provider = this._provider || this._manager._default;
+    const driver   = this._manager._resolveDriver(provider);
+    const result   = await driver.image({
+      prompt:      this._prompt,
+      model:       this._model,
+      size:        this._size,
+      quality:     this._quality,
+      n:           this._n,
+      aspectRatio: this._aspect,
+      attachments: this._attachments,
+    });
+    const response = new AIImageResponse({ ...result, prompt: this._prompt });
+    for (const fn of this._thenFns) await fn(response);
+    return response;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIAudioResponse
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIAudioResponse {
+  constructor({ audio, format, provider }) {
+    this._audio  = audio;    // Buffer
+    this.format  = format;
+    this.provider = provider;
+  }
+
+  get buffer() { return this._audio; }
+
+  async store(filePath, disk = null) {
+    const storage = AIAudioResponse._storage;
+    if (!storage) throw new Error('Storage service not available.');
+    const d = disk ? storage.disk(disk) : storage;
+    await d.put(filePath, this._audio);
+    return filePath;
+  }
+
+  async storeAs(name, disk = null) {
+    const path = name.includes('.') ? name : `${name}.${this.format || 'mp3'}`;
+    return this.store(path, disk);
+  }
+
+  toString() { return `[AIAudioResponse: ${this._audio.length} bytes, ${this.format}]`; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PendingAudio (TTS)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class PendingAudio {
+  constructor(manager, text) {
+    this._manager  = manager;
+    this._text     = text;
+    this._provider = null;
+    this._model    = null;
+    this._voice    = null;
+    this._instructions = null;
+  }
+
+  using(provider)        { this._provider      = provider;      return this; }
+  model(model)           { this._model         = model;         return this; }
+  voice(v)               { this._voice         = v;             return this; }
+  male()                 { this._voice         = 'onyx';        return this; }
+  female()               { this._voice         = 'nova';        return this; }
+  instructions(text)     { this._instructions  = text;          return this; }
+
+  async generate() {
+    const provider = this._provider || this._manager._audioProvider || this._manager._default;
+    const driver   = this._manager._resolveDriver(provider);
+    const result   = await driver.tts({ text: this._text, model: this._model, voice: this._voice, instructions: this._instructions });
+    return new AIAudioResponse(result);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AITranscriptionResponse
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AITranscriptionResponse {
+  constructor({ text, words = [], speakers = [], provider }) {
+    this.text      = text;
+    this.words     = words;      // [{ word, start, end, speaker }]
+    this.speakers  = speakers;   // [{ speaker, segments }]
+    this.provider  = provider;
+  }
+
+  toString() { return this.text; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PendingTranscription (STT)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class PendingTranscription {
+  constructor(manager, source) {
+    this._manager  = manager;
+    this._source   = source;     // { type: 'path'|'storage'|'buffer', value }
+    this._provider = null;
+    this._model    = null;
+    this._language = null;
+    this._prompt   = null;
+    this._diarize  = false;
+  }
+
+  using(provider)    { this._provider = provider;  return this; }
+  model(model)       { this._model    = model;      return this; }
+  language(lang)     { this._language = lang;       return this; }
+  prompt(p)          { this._prompt   = p;          return this; }
+  /** Include speaker diarization (who said what). */
+  diarize()          { this._diarize  = true;       return this; }
+
+  async generate() {
+    const fs     = require('fs');
+    const path   = require('path');
+    const { resolveStoragePath, SafeFilePath } = require('../http/SafeFilePath');
+    let   audio, filename, mimeType;
+
+    if (this._source.type === 'path') {
+      const safePath = resolveStoragePath(
+        this._source.value,
+        SafeFilePath.getStorageRoot()
+      );
+      audio    = fs.readFileSync(safePath);
+      filename = path.basename(safePath);
+      mimeType = _mimeFromExt(path.extname(filename));
+    } else if (this._source.type === 'storage') {
+      const storage = PendingTranscription._storage;
+      if (!storage) throw new Error('Storage not available.');
+      audio    = await storage.get(this._source.value);
+      filename = path.basename(this._source.value);
+      mimeType = _mimeFromExt(path.extname(filename));
+    } else if (this._source.type === 'buffer') {
+      audio    = this._source.value;
+      filename = this._source.filename || 'audio.mp3';
+      mimeType = this._source.mimeType || 'audio/mpeg';
+    }
+
+    const provider = this._provider || this._manager._audioProvider || 'openai';
+    const driver   = this._manager._resolveDriver(provider);
+    const result   = await driver.transcribe({ audio, filename, mimeType, model: this._model, language: this._language, prompt: this._prompt, diarize: this._diarize });
+    return new AITranscriptionResponse(result);
+  }
+}
+
+function _mimeFromExt(ext) {
+  const map = { '.mp3': 'audio/mpeg', '.mp4': 'audio/mp4', '.m4a': 'audio/mp4', '.wav': 'audio/wav', '.webm': 'audio/webm', '.ogg': 'audio/ogg', '.flac': 'audio/flac' };
+  return map[ext.toLowerCase()] || 'audio/mpeg';
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIRerankResponse
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIRerankResponse {
+  constructor(results) {
+    this._results = results;  // [{ index, score, document }] sorted by score desc
+  }
+
+  /** Top result. */
+  get first() { return this._results[0]; }
+
+  /** All results. */
+  get all()   { return this._results; }
+
+  /** Get result at position n (0-indexed). */
+  at(n)       { return this._results[n]; }
+
+  [Symbol.iterator]() { return this._results[Symbol.iterator](); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PendingReranking
+// ─────────────────────────────────────────────────────────────────────────────
+
+class PendingReranking {
+  constructor(manager, documents) {
+    this._manager   = manager;
+    this._documents = documents;
+    this._provider  = null;
+    this._model     = null;
+    this._limit     = null;
+  }
+
+  using(provider)   { this._provider = provider;  return this; }
+  model(model)      { this._model    = model;      return this; }
+  limit(n)          { this._limit    = n;          return this; }
+
+  async rerank(query) {
+    const provider = this._provider || this._manager._rerankProvider || 'cohere';
+    const driver   = this._manager._resolveDriver(provider);
+    const results  = await driver.rerank({ query, documents: this._documents, model: this._model, limit: this._limit });
+    return new AIRerankResponse(results.sort((a, b) => b.score - a.score));
+  }
+}
+
+module.exports = {
+  PendingImage, AIImageResponse,
+  PendingAudio, AIAudioResponse,
+  PendingTranscription, AITranscriptionResponse,
+  PendingReranking, AIRerankResponse,
+};