millas 0.2.12-beta-2 → 0.2.13

package/src/container/AppInitializer.js

@@ -49,57 +49,82 @@ class AppInitializer {
      * Boot the full application and start the HTTP server.
      * Returns a Promise that resolves once the server is listening.
      */
+    /**
+     * Boot the full application and start the HTTP server.
+     * Called by millas serve — no changes to the developer API.
+     */
     async boot() {
+        await this.bootKernel();
+        await this._serve();
+    }
+
+    /**
+     * Boot the application kernel only — DI container, providers, DB, auth,
+     * cache, mail, queue. No HTTP server, no routes, no listen().
+     *
+     * Used internally by CLI commands (millas migrate, millas createsuperuser, etc.)
+     * via MILLAS_CLI_BOOT=1 environment variable. Developers never call this directly.
+     *
+     * @returns {Application} the booted kernel
+     */
+    async bootKernel() {
         const cfg = this._config;
 
-        // ── Build the HTTP adapter ───────────────────────────────────────────────
         const ExpressAdapter = require('../http/adapters/ExpressAdapter');
         const expressApp = express();
         this._adapter = new ExpressAdapter(expressApp);
         this._adapter.applyBodyParsers();
 
-        // Raw adapter middleware (helmet, compression, etc.)
+        // ── Security — applied before any routes or developer middleware ──────
+        // Reads config/app.js for overrides. All protections are on by default:
+        // security headers, CSRF, rate limiting, cookie defaults, allowed hosts.
+        const SecurityBootstrap = require('../http/SecurityBootstrap');
+        const basePath          = cfg.basePath || process.cwd();
+        const appConfig         = SecurityBootstrap.loadConfig(basePath + '/config/app');
+        SecurityBootstrap.apply(this._adapter.nativeApp || expressApp, appConfig);
+        // ─────────────────────────────────────────────────────────────────────
+
         for (const mw of (cfg.adapterMiddleware || [])) {
             this._adapter.applyMiddleware(mw);
         }
 
-        // ── Build the Application kernel ─────────────────────────────────────────
         this._kernel = new Application(this._adapter);
 
-        // Bind basePath so all providers can resolve config/model paths
-        // without calling process.cwd() at runtime.
-        const basePath = cfg.basePath || process.cwd();
         this._kernel._container.instance('basePath', basePath);
 
-        // Core providers (auto-enabled unless disabled in config)
         const coreProviders = this._buildCoreProviders(cfg);
         this._kernel.providers([...coreProviders, ...cfg.providers]);
 
-        // Named middleware aliases
         for (const {alias, handler} of (cfg.middleware || [])) {
             this._kernel.middleware(alias, handler);
         }
 
-        // Route definitions
         if (cfg.routes) {
             this._kernel.routes(cfg.routes);
         }
 
-        // ── Boot providers ───────────────────────────────────────────────────────
         await this._kernel.boot();
 
-        // ── Mount routes ─────────────────────────────────────────────────────────
+        return this._kernel;
+    }
+
+    /**
+     * Mount routes and start the HTTP server.
+     * Internal — called only by boot(). CLI commands stop after bootKernel().
+     */
+    async _serve() {
+        const cfg = this._config;
+
         if (!process.env.MILLAS_ROUTE_LIST) {
             this._kernel.mountRoutes();
 
-            // Admin panel — mounted between routes and fallbacks
             if (cfg.admin !== null) {
                 try {
                     const Admin = require('../admin/Admin');
                     if (cfg.admin && Object.keys(cfg.admin).length) {
                         Admin.configure(cfg.admin);
                     }
-                    Admin.mount(expressApp);
+                    Admin.mount(this._adapter.nativeApp);
                 } catch (err) {
                     process.stderr.write(`[millas] Admin mount failed: ${err.message}\n`);
                 }
@@ -107,9 +132,8 @@ class AppInitializer {
 
             this._kernel.mountFallbacks();
 
-            // ── Start the HTTP server ──────────────────────────────────────────────
             const server = new HttpServer(this._kernel, {
-                onStart: cfg.onStart || undefined,
+                onStart:    cfg.onStart    || undefined,
                 onShutdown: cfg.onShutdown || undefined,
             });
 

package/src/container/Application.js

@@ -98,6 +98,22 @@ class Application {
         await this._providers.boot();
         this._booted = true;
 
+        // Wire cache, db, and storage into AI manager now that providers are booted
+        try {
+          const ai = this._container.make('ai');
+          if (ai) {
+            try { const cache = this._container.make('cache'); if (cache) ai.setCache(cache); } catch {}
+            try { const db    = this._container.make('db');    if (db)    ai.setDb(db);       } catch {}
+            try { const store = this._container.make('storage'); if (store) ai.setStorage(store); } catch {}
+            // Attach files and stores API as properties
+            try {
+              const { AIFilesAPI, AIStoresAPI } = require('../ai/files');
+              if (!ai.files)  Object.defineProperty(ai, 'files',  { get: () => new AIFilesAPI(ai),  configurable: true });
+              if (!ai.stores) Object.defineProperty(ai, 'stores', { get: () => new AIStoresAPI(ai), configurable: true });
+            } catch {}
+          }
+        } catch { /* ai not registered — skip */ }
+
         this._emitSync('platform.booted', {providers: this._providers.list()});
 
         return this;
@@ -287,9 +303,23 @@ class Application {
         });
         this._container.instance('url', urlGenerator);
 
+        const { HashManager } = require('../hashing/Hash');
+        const hashManager = new HashManager({ default: 'bcrypt', bcrypt: { rounds: 12 } });
+        this._container.instance('hash', hashManager);
+
+        const ProcessManager = require('../process/Process').ProcessManager;
+        this._container.instance('process', new ProcessManager());
+
+        const { AIManager } = require('../ai/AIManager');
+        const basePath = (() => { try { return this._container.make('basePath'); } catch { return process.cwd(); } })();
+        let aiConfig = { default: process.env.AI_PROVIDER || 'anthropic', providers: {} };
+        try { aiConfig = require(basePath + '/config/ai'); } catch { /* no config — use env vars */ }
+        const aiManager = new AIManager(aiConfig);
+        this._container.instance('ai', aiManager);
+
 
         this._mwRegistry.register('cors', new CorsMiddleware());
-        this._mwRegistry.register('throttle', new ThrottleMiddleware({max: 60, window: 60}));
+        this._mwRegistry.register('throttle', ThrottleMiddleware);
         this._mwRegistry.register('log', new LogMiddleware());
         this._mwRegistry.register('auth', AuthMiddleware);
     }

package/src/core/foundation.js

@@ -41,7 +41,6 @@ const { CacheServiceProvider, StorageServiceProvider } = require('../providers/C
 // ── Storage ───────────────────────────────────────────────────────
 const Storage     = require('../storage/Storage');
 const LocalDriver = require('../storage/drivers/LocalDriver');
-
 module.exports = {
   // ── Millas HTTP layer ──────────────────────────────────────────
   MillasRequest, MillasResponse, ResponseDispatcher, RequestContext,
@@ -56,4 +55,5 @@ module.exports = {
   Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider,
   // Storage
   Storage, LocalDriver, StorageServiceProvider,
+  Log: require('../logger').Log,
 };

package/src/errors/HttpError.js

@@ -3,27 +3,43 @@
 /**
  * HttpError
  *
- * A structured error that carries an HTTP status code.
- * Thrown by Controller.abort() and the validation system.
- * Caught automatically by the Router's global error handler.
+ * A structured HTTP error with a status code, message, and optional
+ * field-level error map. Thrown by abort(), notFound(), forbidden() etc.
+ * and caught by the framework's error handler for consistent responses.
  *
- * Usage:
- *   throw new HttpError(404, 'User not found')
- *   throw new HttpError(422, 'Validation failed', { email: ['email is required'] })
+ *   throw new HttpError(404, 'User not found');
+ *   throw new HttpError(422, 'Validation failed', { email: ['Required'] });
  */
 class HttpError extends Error {
   /**
-   * @param {number} status   HTTP status code
-   * @param {string} message  Human-readable message
-   * @param {object} errors   Optional field-level errors (for validation)
+   * @param {number} status   — HTTP status code
+   * @param {string} [message]
+   * @param {object|null} [errors]  — field-level errors { field: [msg, ...] }
    */
-  constructor(status = 500, message = 'Internal Server Error', errors = null) {
-    super(message);
-    this.name       = 'HttpError';
-    this.status     = status;
-    this.statusCode = status;
-    this.errors     = errors;
+  constructor(status, message, errors = null) {
+    super(message || HttpError.defaultMessage(status));
+    this.name    = 'HttpError';
+    this.status  = status;
+    this.errors  = errors || null;
+  }
+
+  static defaultMessage(status) {
+    const messages = {
+      400: 'Bad Request',
+      401: 'Unauthorized',
+      403: 'Forbidden',
+      404: 'Not Found',
+      405: 'Method Not Allowed',
+      409: 'Conflict',
+      410: 'Gone',
+      422: 'Unprocessable Entity',
+      429: 'Too Many Requests',
+      500: 'Internal Server Error',
+      502: 'Bad Gateway',
+      503: 'Service Unavailable',
+    };
+    return messages[status] || 'Error';
   }
 }
 
-module.exports = HttpError;
+module.exports = HttpError;

package/src/facades/AI.js

@@ -0,0 +1,411 @@
+'use strict';
+
+const { createFacade } = require('./Facade');
+
+// ── Service & types re-exported for application use ───────────────────────────
+const AIService           = require('../ai/AIManager');
+const { AIManager, PendingRequest } = require('../ai/AIManager');
+const {
+  AIMessage, AIResponse, AIStreamEvent,
+  Tool, ToolBuilder, Thread, Prompt, Schema,
+  AIError, AIRateLimitError, AIStructuredOutputError, AIProviderError,
+} = require('../ai/types');
+const {
+  PendingImage, AIImageResponse,
+  PendingAudio, AIAudioResponse,
+  PendingTranscription, AITranscriptionResponse,
+  PendingReranking, AIRerankResponse,
+} = require('../ai/media');
+const { ConversationThread, AI_MIGRATIONS } = require('../ai/conversation');
+const { AIFile, PendingFile, AIFilesAPI, AIVectorStore, AIStoresAPI } = require('../ai/files');
+const { WebSearch, WebFetch, FileSearch } = require('../ai/provider_tools');
+
+/**
+ * AI facade — multi-provider LLM client for Millas.
+ *
+ * Resolved from the DI container as 'ai'.
+ * Auto-configured from config/ai.js or environment variables.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SUPPORTED PROVIDERS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   Provider    | Text | Image | TTS | STT | Embed | Rerank
+ *   ────────────┼──────┼───────┼─────┼─────┼───────┼───────
+ *   anthropic   |  ✓   |       |     |     |       |
+ *   openai      |  ✓   |   ✓   |  ✓  |  ✓  |   ✓   |
+ *   gemini      |  ✓   |   ✓   |     |     |   ✓   |
+ *   groq        |  ✓   |       |     |  ✓  |       |
+ *   mistral     |  ✓   |       |     |  ✓  |   ✓   |
+ *   xai         |  ✓   |   ✓   |     |     |       |
+ *   deepseek    |  ✓   |       |     |     |       |
+ *   azure       |  ✓   |       |  ✓  |  ✓  |   ✓   |
+ *   cohere      |  ✓   |       |     |     |   ✓   |   ✓
+ *   ollama      |  ✓   |       |     |     |   ✓   |
+ *   elevenlabs  |      |       |  ✓  |  ✓  |       |
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * CONFIGURATION (config/ai.js)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   module.exports = {
+ *     default: 'anthropic',
+ *     audioProvider:  'elevenlabs',   // default provider for TTS/STT
+ *     rerankProvider: 'cohere',       // default provider for reranking
+ *     providers: {
+ *       anthropic:  { apiKey: process.env.ANTHROPIC_API_KEY,  model: 'claude-sonnet-4-20250514' },
+ *       openai:     { apiKey: process.env.OPENAI_API_KEY,     model: 'gpt-4o', embeddingModel: 'text-embedding-3-small' },
+ *       gemini:     { apiKey: process.env.GEMINI_API_KEY,     model: 'gemini-2.0-flash' },
+ *       groq:       { apiKey: process.env.GROQ_API_KEY,       model: 'llama-3.1-70b-versatile' },
+ *       mistral:    { apiKey: process.env.MISTRAL_API_KEY,    model: 'mistral-large-latest' },
+ *       xai:        { apiKey: process.env.XAI_API_KEY,        model: 'grok-2' },
+ *       deepseek:   { apiKey: process.env.DEEPSEEK_API_KEY,   model: 'deepseek-chat' },
+ *       cohere:     { apiKey: process.env.COHERE_API_KEY },
+ *       elevenlabs: { apiKey: process.env.ELEVENLABS_API_KEY },
+ *       ollama:     { baseUrl: 'http://localhost:11434',       model: 'llama3.2' },
+ *       azure:      { apiKey: process.env.AZURE_OPENAI_KEY, endpoint: process.env.AZURE_OPENAI_ENDPOINT, deployment: 'gpt-4o', apiVersion: '2024-02-01' },
+ *     },
+ *   };
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TEXT GENERATION
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Simplest call
+ *   const res = await AI.text('What is the capital of Kenya?');
+ *   console.log(res.text);           // 'Nairobi'
+ *   console.log(res.totalTokens);    // 42
+ *
+ *   // Full builder
+ *   const res = await AI
+ *     .using('openai')
+ *     .model('gpt-4o')
+ *     .system('You are concise.')
+ *     .temperature(0.7)
+ *     .maxTokens(500)
+ *     .retry(3, 1000)
+ *     .fallback(['anthropic', { provider: 'gemini', model: 'gemini-2.0-flash' }])
+ *     .cache(600)
+ *     .tokenBudget(10000)
+ *     .generate('Explain recursion in one paragraph.');
+ *
+ *   // Extended thinking (Anthropic claude-3-7+)
+ *   const res = await AI
+ *     .using('anthropic')
+ *     .think(16000)
+ *     .generate('Prove there are infinitely many primes.');
+ *
+ *   console.log(res.thinking);  // internal reasoning chain
+ *   console.log(res.text);      // final answer
+ *
+ *   // Per-provider options
+ *   await AI.providerOptions({
+ *     openai:    { reasoning: { effort: 'low' }, frequency_penalty: 0.5 },
+ *     anthropic: { thinking: { budget_tokens: 1024 } },
+ *   }).generate('...');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * STREAMING
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Event-based
+ *   for await (const event of AI.stream('Tell me a story')) {
+ *     if (event.type === 'delta')    process.stdout.write(event.data.text);
+ *     if (event.type === 'thinking') console.log('[thinking]', event.data.text);
+ *     if (event.type === 'tool_call') console.log('Tool called:', event.data.name);
+ *     if (event.type === 'complete') console.log('Tokens:', event.data.totalTokens);
+ *   }
+ *
+ *   // Token callback shorthand
+ *   const res = await AI
+ *     .onToken(chunk => expressRes.write(chunk))
+ *     .generate('Write a poem about Kenya');
+ *
+ *   // SSE endpoint
+ *   app.get('/chat', async (req, res) => {
+ *     res.setHeader('Content-Type', 'text/event-stream');
+ *     for await (const event of AI.stream(req.query.q)) {
+ *       if (event.type === 'delta')
+ *         res.write('data: ' + JSON.stringify({ text: event.data.text }) + '\n\n');
+ *       if (event.type === 'complete')
+ *         res.write('data: [DONE]\n\n');
+ *     }
+ *     res.end();
+ *   });
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * STRUCTURED OUTPUT
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const res = await AI
+ *     .structured(Schema.define({
+ *       sentiment:  { type: 'string', enum: ['positive', 'negative', 'neutral'] },
+ *       confidence: { type: 'number', min: 0, max: 1 },
+ *       summary:    { type: 'string' },
+ *       keywords:   { type: 'array'  },
+ *     }))
+ *     .generate('Analyse: "Great product, fast shipping!"');
+ *
+ *   res.parsed.sentiment;    // 'positive'
+ *   res.parsed.confidence;   // 0.97
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TOOL CALLING & AGENTS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const weatherTool = Tool.define('get_weather')
+ *     .description('Get real-time weather for a city')
+ *     .parameters({
+ *       type: 'object',
+ *       properties: {
+ *         city:  { type: 'string' },
+ *         units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
+ *       },
+ *       required: ['city'],
+ *     })
+ *     .handle(async ({ city, units = 'celsius' }) => WeatherAPI.get(city, units))
+ *     .build();
+ *
+ *   // Agentic loop — tool calls handled automatically
+ *   const res = await AI
+ *     .tools([weatherTool, calendarTool])
+ *     .agent('Book a meeting for a sunny day in Nairobi next week');
+ *
+ *   // Provider-native tools (executed by the AI provider, not your app)
+ *   await AI.tools([new WebSearch().max(5)]).generate('What happened in AI today?');
+ *   await AI.tools([new WebFetch().allow(['docs.example.com'])]).generate('Summarise https://...');
+ *   await AI.tools([new FileSearch({ stores: ['vs_abc'] })]).generate('Find docs about...');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * CONVERSATIONS (DB-persisted)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Start a new conversation
+ *   const thread = await AI.conversation.forUser(user.id, 'SalesCoach').create('Q3 Review');
+ *   await thread.addUser('Analyse this transcript...');
+ *   const res = await AI.withThread(thread).generate();
+ *   await thread.addAssistant(res.text);
+ *
+ *   const conversationId = thread.id;  // store for later
+ *
+ *   // Continue an existing conversation
+ *   const thread = await AI.conversation.continue(conversationId);
+ *   await thread.addUser('Tell me more about that.');
+ *   const res = await AI.withThread(thread).generate();
+ *
+ *   // List a user's conversations
+ *   const history = await ConversationThread.list(user.id, 'SalesCoach', 20);
+ *
+ *   // In-memory thread (no DB)
+ *   const thread = AI.thread('You are helpful.').limit(20).summariseWith(async (old) => {
+ *     return (await AI.text('Summarise: ' + old.map(m=>m.content).join('\n'))).text;
+ *   });
+ *   thread.addUser('Hello!');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * IMAGE GENERATION
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const img = await AI.image('A donut on a counter')
+ *     .landscape()           // or .portrait() or .square()
+ *     .quality('high')       // 'high' | 'standard' | 'low'
+ *     .using('openai')
+ *     .generate();
+ *
+ *   await img.store('images/donut.png');
+ *   const buffer = img.buffer;  // raw Buffer
+ *
+ *   // With reference images
+ *   const img = await AI.image('Update this to an impressionist style')
+ *     .attachments([AI.files.fromStorage('photo.jpg')])
+ *     .generate();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * AUDIO — TEXT TO SPEECH
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const audio = await AI.speak('Welcome to Millas!')
+ *     .female()                          // or .male() or .voice('voice-id')
+ *     .instructions('Speak like a news anchor')
+ *     .using('elevenlabs')
+ *     .generate();
+ *
+ *   await audio.store('audio/welcome.mp3');
+ *   const buffer = audio.buffer;
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * AUDIO — SPEECH TO TEXT (TRANSCRIPTION)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // From file path
+ *   const t = await AI.transcribe.fromPath('/recordings/call.mp3')
+ *     .diarize()              // include who said what
+ *     .language('en')
+ *     .generate();
+ *
+ *   console.log(t.text);     // full transcript
+ *   console.log(t.speakers); // per-speaker segments
+ *
+ *   // From storage
+ *   const t = await AI.transcribe.fromStorage('uploads/meeting.mp3').generate();
+ *
+ *   // From buffer
+ *   const t = await AI.transcribe.fromBuffer(audioBuffer, 'audio.mp3').generate();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * EMBEDDINGS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Single text
+ *   const [vector] = await AI.using('openai').embed('Napa Valley has great wine.');
+ *
+ *   // Batch
+ *   const vectors = await AI.embed(['text one', 'text two'], null, 'openai');
+ *
+ *   // Local (Ollama)
+ *   const [vector] = await AI.using('ollama').embed('Hello world');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * RERANKING
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const result = await AI
+ *     .rerank(['Django is a Python framework.', 'Laravel is PHP.', 'React is JS.'])
+ *     .limit(2)
+ *     .using('cohere')
+ *     .rerank('PHP frameworks');
+ *
+ *   result.first.document;  // 'Laravel is PHP.'
+ *   result.first.score;     // 0.95
+ *   for (const r of result) console.log(r.score, r.document);
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * FILE STORAGE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Upload a file to the provider
+ *   const file = await AI.files.fromPath('/reports/q3.pdf').put();
+ *   const file = await AI.files.fromStorage('uploads/report.pdf').put();
+ *   const file = await AI.files.fromUrl('https://example.com/doc.pdf').put();
+ *
+ *   console.log(file.id);   // 'file-abc123'
+ *
+ *   // Use a stored file in a prompt
+ *   const res = await AI
+ *     .withMessage([
+ *       { type: 'text',     text: 'Summarise this document.' },
+ *       { type: 'file_ref', fileId: file.id },
+ *     ])
+ *     .generate();
+ *
+ *   // Retrieve or delete
+ *   const meta = await AI.files.fromId('file-abc').get();
+ *   await AI.files.fromId('file-abc').delete();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * VECTOR STORES (RAG)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Create a store
+ *   const store = await AI.stores.create('Knowledge Base');
+ *
+ *   // Add files
+ *   await store.add(AI.files.fromPath('/docs/manual.pdf'));
+ *   await store.add('file-abc123', { author: 'Alice', year: 2025 });
+ *
+ *   // Use it in a prompt with FileSearch tool
+ *   await AI
+ *     .tools([new FileSearch({ stores: [store.id] })])
+ *     .generate('Find docs about authentication');
+ *
+ *   // Remove a file
+ *   await store.remove('file-abc123', { deleteFile: true });
+ *
+ *   // Retrieve or delete the store
+ *   const store = await AI.stores.get('vs_abc123');
+ *   await AI.stores.delete('vs_abc123');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * MIDDLEWARE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const logUsage = async (req, next) => {
+ *     const start = Date.now();
+ *     const res   = await next(req);
+ *     Log.info(`AI [${req.provider}] ${Date.now()-start}ms — ${res.totalTokens} tokens`);
+ *     return res;
+ *   };
+ *
+ *   await AI.use(logUsage).generate('...');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PROMPT TEMPLATES
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const prompt = AI.prompt('Translate "{{text}}" to {{language}}.')
+ *     .with({ text: 'Hello', language: 'Swahili' });
+ *
+ *   await AI.text(prompt.toString());
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TESTING
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   AI.swap({
+ *     text:   async () => new AIResponse({ text: 'Mocked', provider: 'mock', model: 'mock' }),
+ *     stream: async function*() { yield AIStreamEvent.delta('Mocked'); },
+ *   });
+ *   AI.restore();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * @see src/ai/AIManager.js
+ * @see src/ai/drivers.js
+ * @see src/ai/types.js
+ * @see src/ai/media.js
+ * @see src/ai/conversation.js
+ * @see src/ai/files.js
+ * @see src/ai/provider_tools.js
+ */
+class AI extends createFacade('ai') {}
+
+module.exports = {
+  AI,
+  // Manager
+  AIManager,
+  PendingRequest,
+  // Core types
+  AIMessage,
+  AIResponse,
+  AIStreamEvent,
+  // Tool system
+  Tool,
+  ToolBuilder,
+  // Provider-native tools
+  WebSearch,
+  WebFetch,
+  FileSearch,
+  // Memory
+  Thread,
+  ConversationThread,
+  AI_MIGRATIONS,
+  // Templating & schema
+  Prompt,
+  Schema,
+  // Media
+  PendingImage,  AIImageResponse,
+  PendingAudio,  AIAudioResponse,
+  PendingTranscription, AITranscriptionResponse,
+  PendingReranking,     AIRerankResponse,
+  // Files & vector stores
+  AIFile,
+  PendingFile,
+  AIFilesAPI,
+  AIVectorStore,
+  AIStoresAPI,
+  // Errors
+  AIError,
+  AIRateLimitError,
+  AIStructuredOutputError,
+  AIProviderError,
+};