millas 0.2.12-beta-1 → 0.2.13-beta

package/src/ai/pricing.js

@@ -0,0 +1,152 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Token pricing per model — USD per 1M tokens
+// Updated: 2025. Check provider pricing pages for latest rates.
+// ─────────────────────────────────────────────────────────────────────────────
+
+const PRICING = {
+  // ── Anthropic ───────────────────────────────────────────────────────────────
+  'claude-opus-4-5':                    { input: 15.00,  output: 75.00  },
+  'claude-sonnet-4-20250514':           { input: 3.00,   output: 15.00  },
+  'claude-sonnet-4-5':                  { input: 3.00,   output: 15.00  },
+  'claude-haiku-4-5-20251001':          { input: 0.80,   output: 4.00   },
+  'claude-3-7-sonnet-20250219':         { input: 3.00,   output: 15.00  },
+  'claude-3-5-sonnet-20241022':         { input: 3.00,   output: 15.00  },
+  'claude-3-5-haiku-20241022':          { input: 0.80,   output: 4.00   },
+  'claude-3-opus-20240229':             { input: 15.00,  output: 75.00  },
+
+  // ── OpenAI ──────────────────────────────────────────────────────────────────
+  'gpt-4o':                             { input: 2.50,   output: 10.00  },
+  'gpt-4o-mini':                        { input: 0.15,   output: 0.60   },
+  'gpt-4-turbo':                        { input: 10.00,  output: 30.00  },
+  'gpt-4':                              { input: 30.00,  output: 60.00  },
+  'gpt-3.5-turbo':                      { input: 0.50,   output: 1.50   },
+  'o1':                                 { input: 15.00,  output: 60.00  },
+  'o1-mini':                            { input: 3.00,   output: 12.00  },
+  'o3-mini':                            { input: 1.10,   output: 4.40   },
+
+  // ── Gemini ──────────────────────────────────────────────────────────────────
+  'gemini-2.5-pro':                     { input: 1.25,   output: 10.00  },
+  'gemini-2.5-flash':                   { input: 0.15,   output: 0.60   },
+  'gemini-2.0-flash':                   { input: 0.10,   output: 0.40   },
+  'gemini-2.0-flash-lite':              { input: 0.075,  output: 0.30   },
+  'gemini-1.5-pro':                     { input: 1.25,   output: 5.00   },
+  'gemini-1.5-flash':                   { input: 0.075,  output: 0.30   },
+
+  // ── Groq ────────────────────────────────────────────────────────────────────
+  'llama-3.3-70b-versatile':            { input: 0.59,   output: 0.79   },
+  'llama-3.1-70b-versatile':            { input: 0.59,   output: 0.79   },
+  'llama-3.1-8b-instant':               { input: 0.05,   output: 0.08   },
+  'mixtral-8x7b-32768':                 { input: 0.24,   output: 0.24   },
+
+  // ── Mistral ──────────────────────────────────────────────────────────────────
+  'mistral-large-latest':               { input: 2.00,   output: 6.00   },
+  'mistral-small-latest':               { input: 0.20,   output: 0.60   },
+  'open-mistral-7b':                    { input: 0.25,   output: 0.25   },
+
+  // ── DeepSeek ─────────────────────────────────────────────────────────────────
+  'deepseek-chat':                      { input: 0.27,   output: 1.10   },
+  'deepseek-reasoner':                  { input: 0.55,   output: 2.19   },
+
+  // ── xAI ─────────────────────────────────────────────────────────────────────
+  'grok-2':                             { input: 2.00,   output: 10.00  },
+  'grok-2-mini':                        { input: 0.20,   output: 1.00   },
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CostCalculator
+// ─────────────────────────────────────────────────────────────────────────────
+
+class CostCalculator {
+  /**
+   * Calculate cost for a completed response.
+   *
+   *   const cost = CostCalculator.forResponse(response);
+   *   cost.input   // 0.0003
+   *   cost.output  // 0.0015
+   *   cost.total   // 0.0018
+   *   cost.currency // 'USD'
+   *   cost.formatted // '$0.0018'
+   *
+   * @param {AIResponse} response
+   * @returns {{ input, output, total, currency, formatted } | null}
+   */
+  static forResponse(response) {
+    return CostCalculator.calculate(
+      response.model,
+      response.inputTokens,
+      response.outputTokens
+    );
+  }
+
+  /**
+   * Calculate cost given model and token counts.
+   *
+   * @param {string} model
+   * @param {number} inputTokens
+   * @param {number} outputTokens
+   * @returns {{ input, output, total, currency, formatted } | null}
+   */
+  static calculate(model, inputTokens, outputTokens) {
+    const pricing = CostCalculator._lookup(model);
+    if (!pricing) return null;
+
+    const input  = (inputTokens  / 1_000_000) * pricing.input;
+    const output = (outputTokens / 1_000_000) * pricing.output;
+    const total  = input + output;
+
+    return {
+      input:     parseFloat(input.toFixed(6)),
+      output:    parseFloat(output.toFixed(6)),
+      total:     parseFloat(total.toFixed(6)),
+      currency:  'USD',
+      formatted: `$${total.toFixed(4)}`,
+    };
+  }
+
+  /**
+   * Estimate cost for a prompt before sending it.
+   * Uses a rough character-to-token ratio (1 token ≈ 4 chars).
+   *
+   *   const est = AI.estimateCost('My long prompt here...', 'claude-sonnet-4-20250514');
+   *   est.estimated      // { input: 0.00003, output: 0.00015, total: 0.00018 }
+   *   est.note           // 'Estimate only. Output tokens unknown.'
+   *
+   * @param {string}  prompt
+   * @param {string}  model
+   * @param {number}  [expectedOutputTokens=500]
+   */
+  static estimate(prompt, model, expectedOutputTokens = 500) {
+    const inputTokens = Math.ceil(prompt.length / 4);
+    const cost        = CostCalculator.calculate(model, inputTokens, expectedOutputTokens);
+    if (!cost) return { estimated: null, note: `No pricing data for model: ${model}` };
+    return {
+      estimated:       cost,
+      inputTokens,
+      outputTokens:    expectedOutputTokens,
+      note:            'Estimate only. Output tokens are approximate.',
+    };
+  }
+
+  static _lookup(model) {
+    if (!model) return null;
+    // Exact match
+    if (PRICING[model]) return PRICING[model];
+    // Prefix match — handles versioned model strings like 'claude-3-5-sonnet-20241022-v2'
+    for (const key of Object.keys(PRICING)) {
+      if (model.startsWith(key) || key.startsWith(model.split('-').slice(0, 4).join('-'))) {
+        return PRICING[key];
+      }
+    }
+    return null;
+  }
+
+  /** Check if pricing data exists for a model. */
+  static hasPricing(model) { return !!CostCalculator._lookup(model); }
+
+  /** List all models with known pricing. */
+  static supportedModels() { return Object.keys(PRICING); }
+}
+
+module.exports = { PRICING, CostCalculator };

package/src/ai/provider_tools.js

@@ -0,0 +1,114 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Provider-native tools — executed by the AI provider, not your app
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * WebSearch — let the model search the web in real-time.
+ * Supported: Anthropic, OpenAI, Gemini
+ *
+ *   AI.tools([new WebSearch()]).generate('What happened in tech today?')
+ *   AI.tools([new WebSearch().max(5).allow(['techcrunch.com'])]).generate('...')
+ */
+class WebSearch {
+  constructor() {
+    this._max      = null;
+    this._domains  = [];
+    this._location = null;
+    this._isProvider = true;
+    this.name        = 'web_search';
+    this.description = 'Search the web for real-time information.';
+  }
+
+  /** Max number of searches the model may perform. */
+  max(n)             { this._max     = n;       return this; }
+
+  /** Restrict results to specific domains. */
+  allow(domains)     { this._domains = domains; return this; }
+
+  /** Bias results toward a location. */
+  location({ city, region, country } = {}) {
+    this._location = { city, region, country };
+    return this;
+  }
+
+  toProviderSchema(provider) {
+    if (provider === 'anthropic') {
+      const tool = { type: 'web_search_20250305', name: 'web_search' };
+      if (this._max)      tool.max_uses           = this._max;
+      if (this._domains?.length) tool.allowed_domains = this._domains;
+      return tool;
+    }
+    if (provider === 'openai') {
+      const tool = { type: 'web_search_preview' };
+      if (this._location) tool.search_context_size = 'medium';
+      if (this._domains?.length) tool.user_location = this._location;
+      return tool;
+    }
+    if (provider === 'gemini') {
+      return { google_search: {} };
+    }
+    return null;
+  }
+}
+
+/**
+ * WebFetch — let the model fetch and read web pages.
+ * Supported: Anthropic, Gemini
+ *
+ *   AI.tools([new WebFetch()]).generate('Summarize https://example.com/page')
+ */
+class WebFetch {
+  constructor() {
+    this._max     = null;
+    this._domains = [];
+    this._isProvider = true;
+    this.name        = 'web_fetch';
+    this.description = 'Fetch and read the content of web pages.';
+  }
+
+  max(n)         { this._max     = n;       return this; }
+  allow(domains) { this._domains = domains; return this; }
+
+  toProviderSchema(provider) {
+    if (provider === 'anthropic') {
+      const tool = { type: 'web_search_20250305', name: 'web_search' };
+      if (this._max) tool.max_uses = this._max;
+      if (this._domains?.length) tool.allowed_domains = this._domains;
+      return tool;
+    }
+    if (provider === 'gemini') return { url_context: {} };
+    return null;
+  }
+}
+
+/**
+ * FileSearch — search through files in vector stores.
+ * Supported: OpenAI, Gemini
+ *
+ *   AI.tools([new FileSearch({ stores: ['store_abc'] })]).generate('...')
+ */
+class FileSearch {
+  constructor({ stores = [], where = null } = {}) {
+    this._stores     = stores;
+    this._where      = where;
+    this._isProvider = true;
+    this.name        = 'file_search';
+    this.description = 'Search through files in vector stores.';
+  }
+
+  toProviderSchema(provider) {
+    if (provider === 'openai') {
+      const tool = { type: 'file_search', vector_store_ids: this._stores };
+      if (this._where) tool.filters = this._where;
+      return tool;
+    }
+    if (provider === 'gemini') {
+      return { retrieval: { vertex_ai_search: { datastore: this._stores[0] } } };
+    }
+    return null;
+  }
+}
+
+module.exports = { WebSearch, WebFetch, FileSearch };

package/src/ai/types.js

@@ -0,0 +1,356 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIMessage — a single message in a conversation
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIMessage {
+  /**
+   * @param {'user'|'assistant'|'system'|'tool'} role
+   * @param {string|Array}  content  — string or array of content parts
+   * @param {object}        [meta]   — tool_call_id, name, usage, etc.
+   */
+  constructor(role, content, meta = {}) {
+    this.role    = role;
+    this.content = content;
+    this.meta    = meta;
+  }
+
+  static user(content)       { return new AIMessage('user',      content); }
+  static assistant(content)  { return new AIMessage('assistant', content); }
+  static system(content)     { return new AIMessage('system',    content); }
+  static tool(id, name, content) {
+    return new AIMessage('tool', content, { tool_call_id: id, name });
+  }
+
+  toJSON() {
+    const base = { role: this.role, content: this.content };
+    if (this.meta.tool_call_id) {
+      base.tool_call_id = this.meta.tool_call_id;
+      base.name         = this.meta.name;
+    }
+    return base;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIResponse — structured result from any provider
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIResponse {
+  constructor({
+    text, role = 'assistant', model, provider,
+    inputTokens = 0, outputTokens = 0,
+    toolCalls = [], finishReason = 'stop',
+    raw = null,
+  }) {
+    this.text         = text || '';
+    this.role         = role;
+    this.model        = model;
+    this.provider     = provider;
+    this.inputTokens  = inputTokens;
+    this.outputTokens = outputTokens;
+    this.totalTokens  = inputTokens + outputTokens;
+    this.toolCalls    = toolCalls;   // [{ id, name, arguments }]
+    this.finishReason = finishReason;
+    this.raw          = raw;         // original provider response
+  }
+
+  /** True when the model wants to call tools. */
+  get hasToolCalls()    { return this.toolCalls.length > 0; }
+
+  /** True when the model stopped naturally. */
+  get isComplete()      { return this.finishReason === 'stop'; }
+
+  /** True when the model hit a token limit. */
+  get isTokenLimited()  { return this.finishReason === 'length'; }
+
+  /** Cast to the assistant AIMessage to append to a thread. */
+  toMessage() {
+    const content = this.hasToolCalls
+      ? [{ type: 'text', text: this.text }, ...this.toolCalls.map(tc => ({
+          type: 'tool_use', id: tc.id, name: tc.name, input: tc.arguments,
+        }))]
+      : this.text;
+    return new AIMessage('assistant', content);
+  }
+
+  toString() { return this.text; }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AIStreamEvent — typed events emitted during streaming
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIStreamEvent {
+  constructor(type, data) { this.type = type; this.data = data; }
+
+  static delta(text)        { return new AIStreamEvent('delta',    { text }); }
+  static thinking(text)     { return new AIStreamEvent('thinking', { text }); }
+  static toolCall(tc)       { return new AIStreamEvent('tool_call', tc); }
+  static complete(response) { return new AIStreamEvent('complete',  response); }
+  static error(err)         { return new AIStreamEvent('error',    { error: err }); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool — define a callable tool the model can invoke
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Tool {
+  /**
+   * @param {string}   name
+   * @param {string}   description
+   * @param {object}   schema      — JSON Schema object for parameters
+   * @param {function} handler     — async (args) => result
+   */
+  constructor(name, description, schema, handler) {
+    this.name        = name;
+    this.description = description;
+    this.schema      = schema;
+    this.handler     = handler;
+  }
+
+  /**
+   * Fluent factory:
+   *
+   *   Tool.define('get_weather')
+   *     .description('Get the weather for a city')
+   *     .parameters({
+   *       type: 'object',
+   *       properties: {
+   *         city:  { type: 'string', description: 'City name' },
+   *         units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
+   *       },
+   *       required: ['city'],
+   *     })
+   *     .handle(async ({ city, units }) => {
+   *       return await WeatherService.get(city, units);
+   *     })
+   */
+  static define(name) { return new ToolBuilder(name); }
+
+  toProviderSchema() {
+    return { name: this.name, description: this.description, input_schema: this.schema };
+  }
+
+  toOpenAISchema() {
+    return {
+      type: 'function',
+      function: { name: this.name, description: this.description, parameters: this.schema },
+    };
+  }
+}
+
+class ToolBuilder {
+  constructor(name) {
+    this._name = name;
+    this._description = '';
+    this._schema = { type: 'object', properties: {}, required: [] };
+    this._handler = null;
+  }
+  description(d)  { this._description = d; return this; }
+  parameters(s)   { this._schema = s;      return this; }
+  handle(fn)      { this._handler = fn;    return this; }
+  build() {
+    return new Tool(this._name, this._description, this._schema, this._handler);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Thread — conversation memory manager
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Thread {
+  constructor(systemPrompt = null) {
+    this._messages    = [];
+    this._systemPrompt = systemPrompt;
+    this._maxMessages  = null;    // null = unlimited
+    this._summaryFn    = null;    // async (messages) => summaryString
+  }
+
+  /** Set a new or updated system prompt. */
+  system(prompt) { this._systemPrompt = prompt; return this; }
+
+  /** Limit history to the last N messages (sliding window). */
+  limit(n) { this._maxMessages = n; return this; }
+
+  /**
+   * Provide a summarisation function. When the thread exceeds limit(),
+   * older messages are collapsed into a summary instead of dropped.
+   *
+   *   thread.summariseWith(async (msgs) => {
+   *     const res = await AI.text(`Summarise this: ${msgs.map(m=>m.content).join('\n')}`);
+   *     return res.text;
+   *   });
+   */
+  summariseWith(fn) { this._summaryFn = fn; return this; }
+
+  add(message) {
+    this._messages.push(message);
+    return this;
+  }
+
+  addUser(content)      { return this.add(AIMessage.user(content)); }
+  addAssistant(content) { return this.add(AIMessage.assistant(content)); }
+
+  /** Messages formatted for the provider, respecting limit. */
+  async toArray() {
+    let msgs = [...this._messages];
+
+    if (this._maxMessages && msgs.length > this._maxMessages) {
+      const overflow = msgs.slice(0, msgs.length - this._maxMessages);
+      msgs            = msgs.slice(msgs.length - this._maxMessages);
+
+      if (this._summaryFn) {
+        const summary = await this._summaryFn(overflow);
+        msgs.unshift(AIMessage.system(`Earlier conversation summary: ${summary}`));
+      }
+    }
+
+    return msgs.map(m => m.toJSON());
+  }
+
+  get length() { return this._messages.length; }
+
+  clear() { this._messages = []; return this; }
+
+  /** Last assistant message text. */
+  get lastReply() {
+    const last = [...this._messages].reverse().find(m => m.role === 'assistant');
+    return last ? (typeof last.content === 'string' ? last.content : last.content?.[0]?.text || '') : null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Prompt — template with variable substitution
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Prompt {
+  /**
+   * @param {string} template  — use {{variable}} syntax
+   *
+   *   Prompt.make('Summarise this in {{language}}: {{text}}')
+   *     .with({ language: 'French', text: article })
+   *     .toString()
+   */
+  constructor(template) {
+    this._template = template;
+    this._vars     = {};
+  }
+
+  static make(template) { return new Prompt(template); }
+
+  with(vars) { Object.assign(this._vars, vars); return this; }
+
+  toString() {
+    return this._template.replace(/\{\{(\w+)\}\}/g, (_, k) =>
+      Object.prototype.hasOwnProperty.call(this._vars, k) ? String(this._vars[k]) : `{{${k}}}`
+    );
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Schema — structured output enforcement
+// ─────────────────────────────────────────────────────────────────────────────
+
+class Schema {
+  /**
+   * Define expected output structure. The AI manager will:
+   *   1. Inject the schema into the prompt
+   *   2. Parse and validate the response JSON
+   *   3. Retry once if parsing fails
+   *
+   *   Schema.define({
+   *     name:       { type: 'string' },
+   *     confidence: { type: 'number', min: 0, max: 1 },
+   *     tags:       { type: 'array'  },
+   *   })
+   */
+  constructor(shape) {
+    this._shape = shape;
+  }
+
+  static define(shape) { return new Schema(shape); }
+
+  /** JSON Schema representation passed to the provider. */
+  toJSONSchema() {
+    const props    = {};
+    const required = [];
+    for (const [key, def] of Object.entries(this._shape)) {
+      props[key] = { type: def.type, description: def.description || '' };
+      if (def.enum)  props[key].enum = def.enum;
+      if (def.items) props[key].items = def.items;
+      if (def.required !== false) required.push(key);
+    }
+    return { type: 'object', properties: props, required };
+  }
+
+  /** Validate and cast a parsed object against the shape. */
+  validate(obj) {
+    const result = {};
+    const errors = [];
+    for (const [key, def] of Object.entries(this._shape)) {
+      const val = obj[key];
+      if (val === undefined || val === null) {
+        if (def.required !== false) errors.push(`Missing field: ${key}`);
+        result[key] = def.default ?? null;
+        continue;
+      }
+      if (def.type === 'number') {
+        const n = Number(val);
+        if (isNaN(n)) { errors.push(`${key}: expected number`); continue; }
+        if (def.min !== undefined && n < def.min) errors.push(`${key}: below min ${def.min}`);
+        if (def.max !== undefined && n > def.max) errors.push(`${key}: above max ${def.max}`);
+        result[key] = n;
+      } else {
+        result[key] = val;
+      }
+    }
+    if (errors.length) throw new AIStructuredOutputError(errors.join('; '), obj);
+    return result;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error types
+// ─────────────────────────────────────────────────────────────────────────────
+
+class AIError extends Error {
+  constructor(message, provider, cause = null) {
+    super(message);
+    this.name     = 'AIError';
+    this.provider = provider;
+    this.cause    = cause;
+  }
+}
+
+class AIRateLimitError extends AIError {
+  constructor(provider, retryAfter = null) {
+    super(`Rate limit exceeded on provider "${provider}"`, provider);
+    this.name       = 'AIRateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+class AIStructuredOutputError extends Error {
+  constructor(message, raw) {
+    super(`Structured output validation failed: ${message}`);
+    this.name = 'AIStructuredOutputError';
+    this.raw  = raw;
+  }
+}
+
+class AIProviderError extends AIError {
+  constructor(provider, message, statusCode = null) {
+    super(message, provider);
+    this.name       = 'AIProviderError';
+    this.statusCode = statusCode;
+  }
+}
+
+module.exports = {
+  AIMessage, AIResponse, AIStreamEvent,
+  Tool, ToolBuilder,
+  Thread, Prompt, Schema,
+  AIError, AIRateLimitError, AIStructuredOutputError, AIProviderError,
+};

package/src/auth/Auth.js

@@ -80,7 +80,9 @@ class Auth {
     if (existing) throw new HttpError(422, 'Email already in use');
 
     const hashed = await Hasher.make(data.password);
-    return this._UserModel.create({ ...data, password: hashed });
+    // is_active defaults true — set explicitly so it is always present
+    // regardless of whether the model field has a DB default.
+    return this._UserModel.create({ is_active: true, ...data, password: hashed });
   }
 
   /**
@@ -98,8 +100,22 @@ class Auth {
     const user = await this._UserModel.findBy('email', email);
     if (!user) throw new HttpError(401, 'Invalid credentials');
 
+    // Check password before is_active — avoids leaking whether the account exists
     const ok = await Hasher.check(password, user.password);
-    if (!ok)  throw new HttpError(401, 'Invalid credentials');
+    if (!ok) throw new HttpError(401, 'Invalid credentials');
+
+    // Django: 'Please enter the correct email and password for a staff account.
+    //          Note that both fields may be case-sensitive.'
+    // Millas matches this — inactive check is after password so error message
+    // doesn't reveal which condition failed to a brute-force attacker.
+    if (user.is_active === false || user.is_active === 0) {
+      throw new HttpError(401, 'This account is inactive.');
+    }
+
+    // Record last login (fire-and-forget — never block the login response)
+    try {
+      await this._UserModel.where('id', user.id).update({ last_login: new Date().toISOString() });
+    } catch { /* non-fatal — table may not have last_login yet */ }
 
     const payload = this._buildTokenPayload(user);
     const token   = this._jwt.sign(payload);