future-lang 0.4.0 → 0.4.2

package/ROADMAP.md

@@ -1,6 +1,6 @@
 # Future — Roadmap
 
-**Version:** 0.3.0 · **Last updated:** 2026-06-13
+**Version:** 0.4.1 · **Last updated:** 2026-06-13
 
 Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 
@@ -18,7 +18,9 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 | Multi-line strings | 📋 | Strings must be single-line today |
 | String `+` concatenation | ✅ | Works via binary `+` operator |
 | Integer division / modulo | 📋 | `math.trunc(a / b)` workaround for now |
-| `use "other.future"` imports | 💡 | No cross-file composition yet |
+| `use "other.future"` imports | ✅ | Named + namespace imports; npm packages; recursive deps |
+| `else if` chains | ✅ | One `end` for the whole chain |
+| Reserved namespace protection | ✅ | Compile-time error if reserved name is reassigned |
 | REPL (`future repl`) | 💡 | Interactive shell with introspection |
 
 ---
@@ -28,11 +30,14 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 | Feature | Status | Notes |
 |---------|--------|-------|
 | `ai.ask(prompt)` | ✅ | Single-turn Q&A |
+| `ai.ask(prompt, opts)` | ✅ | `opts`: `temperature`, `max_tokens`, `model`, `system` |
 | `ai.chat(messages)` | ✅ | Multi-turn conversation |
+| `ai.chat(messages, opts)` | ✅ | Inference options forwarded to provider |
 | `ai.embed(text)` | ✅ | Real embeddings (OpenAI/Ollama) + keyword fallback |
-| `ai.stream(prompt, callback)` | ✅ | Streaming via SSE — runtime implemented |
+| `ai.stream(prompt, cb, opts?)` | ✅ | Streaming via SSE; opts forwarded |
 | `stream ai.ask() ... end` syntax | ✅ | Language-level streaming with implicit `chunk` variable |
 | `ai.configure(provider, key, model)` | ✅ | Pluggable provider from Future code |
+| Structured `AiError` (status, code, provider) | ✅ | Catchable with rich properties |
 | Provider: Anthropic | ✅ | Native Messages API |
 | Provider: OpenAI | ✅ | Via OpenAI-compat layer |
 | Provider: Ollama | ✅ | Local models, no key needed |
@@ -205,8 +210,11 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 | `len(x)` built-in | ✅ | Arrays, strings, objects — sync, no runtime needed |
 | `math.*` module | ✅ | Full JS Math wrapper |
 | `input(prompt)` built-in | ✅ | stdin (Node.js) / `window.prompt` (browser) |
+| `else if` chains | ✅ | One `end` closes the whole chain |
+| `use "./file.future"` imports | ✅ | Named or namespace imports, recursive deps |
+| `use "npm-pkg" as alias` | ✅ | Import npm packages as namespaces |
+| Reserved namespace protection | ✅ | Compile-time error on redefinition |
 | Multi-line strings | 📋 | Strings must be single-line |
-| `use "other.future"` — module imports | 💡 | No cross-file composition |
 | REPL (`future repl`) | 💡 | Interactive shell with introspection |
 
 ---
@@ -230,21 +238,57 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 
 ---
 
+## HTTP
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| `http.get(url, headers?)` | ✅ | Parses JSON or returns text |
+| `http.post(url, body, headers?)` | ✅ | JSON body; parses response |
+| `http.configure({ headers, timeout })` | ✅ | Global defaults for all requests |
+| Structured `HttpError` (status, code, url, body) | ✅ | Catchable with rich properties |
+| `http.put / patch / delete` | 📋 | Additional HTTP verbs |
+| Response headers access | 📋 | `res.headers.get("content-type")` |
+
+---
+
+## Testing
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| `future test` command | ✅ | Finds `*.test.future` / `test/**/*.future`, runs all |
+| `future test <pattern>` | ✅ | Filter by filename substring |
+| `assert` namespace | ✅ | `ok`, `equal`, `notEqual`, `deepEqual`, `fail` |
+| Per-file pass/fail reporting | ✅ | `✓` / `✗` with error message |
+| Exit code 1 on failure | ✅ | Integrates with CI |
+| Test isolation (separate process) | 📋 | Currently runs in same Node process |
+| `assert.throws(fn)` | 📋 | Assert that a function throws |
+| Coverage reporting | 💡 | Line coverage for `.future` files |
+
+---
+
 ## Tooling
 
 | Feature | Status | Notes |
 |---------|--------|-------|
 | CLI: `future run` | ✅ | |
 | CLI: `future compile` | ✅ | |
-| Structured manifest | ✅ | All 12 modules, 50+ functions fully described |
+| CLI: `future compile --sourcemap` | ✅ | Emits Source Map v3 `.js.map` |
+| CLI: `future run --debug` | ✅ | Per-call timing via `FUTURE_DEBUG=1` |
+| CLI: `future test` | ✅ | Test runner for `*.test.future` files |
+| CLI: `future new` | ✅ | Project scaffold |
+| CLI: `future check` | ✅ | Syntax-check without running |
+| CLI: `future fmt` | ✅ | Auto-formatter |
+| CLI: `future doctor` | ✅ | Environment health check |
+| CLI: `future playground` | ✅ | Launches browser playground server |
+| Source maps (`.js.map`) | ✅ | VLQ-encoded Source Map v3 |
+| Structured manifest | ✅ | All 13 modules, 50+ functions fully described |
 | Runtime introspection API | ✅ | `runtime.describe()` / `listModules()` / `listFunctions()` |
 | LSP metadata module | ✅ | Completions, hover, signatures |
 | Browser playground | ✅ | `future-playground.html` — 11 examples |
+| `FUTURE_FOR_LLMS.md` | ✅ | BNF grammar + all APIs for AI code assistants |
+| npm publish (`future-lang`) | ✅ | Public — `npm install -g future-lang` |
 | VSCode extension | 📋 | Syntax highlighting, completions, hover |
 | Language Server (LSP) | 📋 | Full editor integration |
-| `future fmt` | 📋 | Auto-formatter |
-| `future check` | 📋 | Lint / type check without running |
-| npm publish (`future-lang`) | 📋 | Public package registry |
 
 ---
 
@@ -252,12 +296,15 @@ Status legend: ✅ Done · 🔄 In progress · 📋 Planned · 💡 Idea
 
 | Priority | Item | Why it matters |
 |----------|------|----------------|
-| 🔴 Critical | npm publish (`future-lang`) | Required to ship publicly |
 | 🔴 Critical | VSCode extension (syntax highlighting) | First impression for new users |
-| 🟠 High | `use "other.future"` imports | Cross-file composition for real projects |
-| 🟠 High | `system.env(name)` | Read env vars from Future code |
+| 🔴 Critical | Language Server (LSP) | Completions and hover for all IDEs |
+| 🟠 High | `ai.extract(text, schema)` | Structured output is the #1 AI use case |
+| 🟠 High | Test isolation (separate process) | Prevents test state leakage |
+| 🟠 High | `assert.throws(fn)` | Needed for error-handling tests |
 | 🟡 Medium | Home Assistant REST API | Most HA users don't run MQTT |
 | 🟡 Medium | Persistent memory / device registry | Most programs are stateless today |
 | 🟡 Medium | Agent tool-calling loop (ReAct) | True autonomous agents |
+| 🟡 Medium | `http.put / patch / delete` | Needed for full REST APIs |
 | 🟢 Low | `rag.delete(id)` | Selective document removal |
 | 🟢 Low | REPL | Nice-to-have for exploration |
+| 🟢 Low | Coverage reporting | `.future` line coverage |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "future-lang",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Future — a small programming language that transpiles to JavaScript, with a capability runtime (HTTP/AI/MQTT/TTS).",
   "type": "module",
   "bin": {

package/runtime/ai.js

@@ -34,31 +34,76 @@ export function configure(baseUrlOrProvider, apiKey, model) {
   });
 }
 
-/** Ask a single question. @returns {Promise<string>} */
-export async function ask(prompt) {
-  return chat([{ role: 'user', content: String(prompt) }]);
+/**
+ * Ask a single question.
+ * @param {string} prompt
+ * @param {{ temperature?: number, max_tokens?: number, model?: string, system?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function ask(prompt, opts = {}) {
+  return chat([{ role: 'user', content: String(prompt) }], opts);
 }
 
-/** Multi-turn chat. messages = [{ role, content }, ...]. @returns {Promise<string>} */
-export async function chat(messages) {
+/**
+ * Multi-turn chat.
+ * @param {Array<{role,content}>} messages
+ * @param {{ temperature?: number, max_tokens?: number, model?: string, system?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export async function chat(messages, opts = {}) {
   const provider = resolveProvider();
   if (!provider) return offlineStub(messages);
-  return provider.chat(messages);
+  return provider.chat(messages, opts);
 }
 
 /**
  * Stream a response chunk-by-chunk.
  * @param {string|Array} promptOrMessages
- * @param {(chunk: string) => void} onChunk  Called with each text fragment.
+ * @param {(chunk: string) => void} onChunk
+ * @param {{ temperature?: number, max_tokens?: number, model?: string }} [opts]
  * @returns {Promise<void>}
  */
-export async function stream(promptOrMessages, onChunk) {
+export async function stream(promptOrMessages, onChunk, opts = {}) {
   const messages = Array.isArray(promptOrMessages)
     ? promptOrMessages
     : [{ role: 'user', content: String(promptOrMessages) }];
   const provider = resolveProvider();
   if (!provider) { onChunk(offlineStub(messages)); return; }
-  return provider.stream(messages, onChunk);
+  return provider.stream(messages, onChunk, opts);
+}
+
+/**
+ * Like ask(), but returns a structured result object instead of a plain string.
+ * Includes the generated text, model used, provider name, and token counts.
+ *
+ * @param {string|Array} prompt  String prompt or messages array
+ * @param {{ temperature?: number, max_tokens?: number, model?: string, system?: string }} [opts]
+ * @returns {Promise<{ text: string, model: string, provider: string, tokens: { input: number, output: number, total: number } }>}
+ */
+export async function complete(prompt, opts = {}) {
+  const messages = Array.isArray(prompt)
+    ? prompt
+    : [{ role: 'user', content: String(prompt) }];
+  const provider = resolveProvider();
+  if (!provider) {
+    return {
+      text:     offlineStub(messages),
+      model:    'none',
+      provider: 'offline',
+      tokens:   { input: 0, output: 0, total: 0 },
+    };
+  }
+  if (typeof provider.complete === 'function') {
+    return provider.complete(messages, opts);
+  }
+  // Fallback for providers that don't implement complete() yet.
+  const text = await provider.chat(messages, opts);
+  return {
+    text,
+    model:    opts.model ?? 'unknown',
+    provider: provider.name,
+    tokens:   { input: 0, output: 0, total: 0 },
+  };
 }
 
 /**

package/runtime/assert.js

@@ -0,0 +1,27 @@
+// runtime/assert.js — Test assertions for `future test`.
+// Wraps node:assert/strict with Future-friendly error messages.
+
+import nodeAssert from 'node:assert/strict';
+
+function wrap(fn, name) {
+  return (...args) => {
+    try {
+      fn(...args);
+    } catch (err) {
+      // Re-throw with the assert namespace tag so the test runner can identify it.
+      const e = new Error(err.message);
+      e.name = 'AssertionError';
+      e.namespace = 'assert';
+      e.operator = err.operator ?? name;
+      e.actual = err.actual;
+      e.expected = err.expected;
+      throw e;
+    }
+  };
+}
+
+export const ok        = wrap((val, msg)        => nodeAssert.ok(val, msg),                       'ok');
+export const equal     = wrap((a, b, msg)        => nodeAssert.equal(a, b, msg),                   'equal');
+export const notEqual  = wrap((a, b, msg)        => nodeAssert.notEqual(a, b, msg),                'notEqual');
+export const deepEqual = wrap((a, b, msg)        => nodeAssert.deepEqual(a, b, msg),               'deepEqual');
+export const fail      = (msg = 'assertion failed') => { throw Object.assign(new Error(msg), { name: 'AssertionError', namespace: 'assert' }); };

package/runtime/http.js

@@ -1,32 +1,78 @@
 // runtime/http.js — consume REST APIs.
 // Uses the global fetch (stable in Node 22). Returns parsed JSON or text.
 
+export class HttpError extends Error {
+  constructor(status, statusText, url, body) {
+    super(`HTTP ${status} ${statusText} — ${url}`);
+    this.name = 'HttpError';
+    this.status = status;
+    this.statusText = statusText;
+    this.url = url;
+    this.body = body;
+    this.namespace = 'http';
+    this.code = `HTTP_${status}`;
+  }
+}
+
+// Global config state — mutated by configure().
+let _config = {
+  headers: {},
+  timeout: 0,
+};
+
+/**
+ * Set global defaults for all HTTP requests.
+ * Useful for Authorization headers, base timeouts, etc.
+ * @param {{ headers?: Record<string,string>, timeout?: number }} opts
+ */
+export function configure(opts = {}) {
+  if (opts.headers) _config.headers = { ..._config.headers, ...opts.headers };
+  if (opts.timeout != null) _config.timeout = opts.timeout;
+}
+
 // Default headers — many public APIs (e.g. GitHub) reject requests without a
 // User-Agent. Callers can override any of these.
 const DEFAULT_HEADERS = {
-  'user-agent': 'future-lang/0.2 (+https://github.com/future-lang)',
+  'user-agent': 'future-lang/0.4 (+https://github.com/humolot/future-lang)',
   accept: 'application/json, text/*;q=0.9, */*;q=0.8',
 };
 
-async function parse(res) {
+async function parseBody(res) {
   const ct = res.headers.get('content-type') || '';
   return ct.includes('application/json') ? res.json() : res.text();
 }
 
+function buildSignal() {
+  if (!_config.timeout) return undefined;
+  return AbortSignal.timeout(_config.timeout);
+}
+
 /** GET a URL. @returns parsed JSON object/array, or text. */
 export async function get(url, headers = {}) {
-  const res = await fetch(url, { headers: { ...DEFAULT_HEADERS, ...headers } });
-  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText} for ${url}`);
-  return parse(res);
+  const res = await fetch(url, {
+    headers: { ...DEFAULT_HEADERS, ..._config.headers, ...headers },
+    signal: buildSignal(),
+  });
+  if (!res.ok) {
+    let body;
+    try { body = await parseBody(res); } catch { body = null; }
+    throw new HttpError(res.status, res.statusText, url, body);
+  }
+  return parseBody(res);
 }
 
 /** POST a JSON body to a URL. @returns parsed JSON or text. */
 export async function post(url, body, headers = {}) {
   const res = await fetch(url, {
     method: 'POST',
-    headers: { ...DEFAULT_HEADERS, 'content-type': 'application/json', ...headers },
+    headers: { ...DEFAULT_HEADERS, 'content-type': 'application/json', ..._config.headers, ...headers },
     body: typeof body === 'string' ? body : JSON.stringify(body),
+    signal: buildSignal(),
   });
-  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText} for ${url}`);
-  return parse(res);
+  if (!res.ok) {
+    let errBody;
+    try { errBody = await parseBody(res); } catch { errBody = null; }
+    throw new HttpError(res.status, res.statusText, url, errBody);
+  }
+  return parseBody(res);
 }

package/runtime/index.js

@@ -16,15 +16,16 @@ import * as schedule from './schedule.js';
 import * as system   from './system.js';
 import * as device   from './device.js';
 import * as math     from './math.js';
+import * as assert   from './assert.js';
 import readline from 'node:readline';
 
 // Canonical ordered list of capability module names.
 const MODULE_NAMES = [
   'ai', 'http', 'mqtt', 'tts', 'rag', 'vision', 'home',
-  'memory', 'schedule', 'system', 'device', 'math',
+  'memory', 'schedule', 'system', 'device', 'math', 'assert',
 ];
 
-const _base = { ai, http, mqtt, tts, rag, vision, home, memory, schedule, system, device, math };
+const _base = { ai, http, mqtt, tts, rag, vision, home, memory, schedule, system, device, math, assert };
 
 /**
  * When FUTURE_DEBUG=1, wrap every namespace method with timing/logging.
@@ -82,10 +83,16 @@ export const manifest = {
     },
     ask: {
       description: 'Ask an AI model a question and get a text response',
-      params: [{ name: 'prompt', type: 'string' }],
+      params: [{ name: 'prompt', type: 'string' }, { name: 'opts', type: 'object', optional: true }],
       returns: 'string',
       async: true,
     },
+    complete: {
+      description: 'Like ask(), but returns a structured object: { text, model, provider, tokens: { input, output, total } }',
+      params: [{ name: 'prompt', type: 'string|array' }, { name: 'opts', type: 'object', optional: true }],
+      returns: '{ text: string, model: string, provider: string, tokens: { input: number, output: number, total: number } }',
+      async: true,
+    },
     chat: {
       description: 'Send a multi-turn message list to an AI model',
       params: [{ name: 'messages', type: 'array' }],
@@ -406,6 +413,14 @@ export const manifest = {
     pi:     { description: 'The mathematical constant π',     params: [], returns: 'number', async: false },
     e:      { description: "Euler's number",                  params: [], returns: 'number', async: false },
   },
+
+  assert: {
+    ok:        { description: 'Assert that value is truthy',                    params: [{ name: 'value', type: 'any' }, { name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+    equal:     { description: 'Assert that actual === expected',                params: [{ name: 'actual', type: 'any' }, { name: 'expected', type: 'any' }, { name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+    notEqual:  { description: 'Assert that actual !== expected',                params: [{ name: 'actual', type: 'any' }, { name: 'expected', type: 'any' }, { name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+    deepEqual: { description: 'Assert deep structural equality',                params: [{ name: 'actual', type: 'any' }, { name: 'expected', type: 'any' }, { name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+    fail:      { description: 'Unconditionally fail the test with a message',   params: [{ name: 'msg', type: 'string', optional: true }], returns: 'void', async: false },
+  },
 };
 
 // --- Introspection API ---
@@ -425,7 +440,7 @@ runtime.listFunctions = (mod) => {
  * Suitable for AI agent discovery or documentation generation.
  */
 runtime.describe = () => ({
-  version: '0.4.0',
+  version: '0.4.2',
   modules: [...MODULE_NAMES],
   manifest,
 });

package/runtime/providers/anthropic.js

@@ -6,13 +6,26 @@ import { parseSSE, keywordVector } from './util.js';
 
 const BASE = 'https://api.anthropic.com/v1';
 
+export class AiError extends Error {
+  constructor(status, provider, body) {
+    const msg = body?.error?.message ?? body ?? `HTTP ${status}`;
+    super(`[ai:${provider}] ${msg}`);
+    this.name = 'AiError';
+    this.status = status;
+    this.code = `AI_HTTP_${status}`;
+    this.namespace = 'ai';
+    this.provider = provider;
+    this.body = body;
+  }
+}
+
 /**
  * Create an Anthropic provider instance.
  * @param {{ apiKey: string, model?: string }} config
  */
 export function create(config) {
-  const key   = config.apiKey;
-  const model = config.model ?? 'claude-sonnet-4-6';
+  const key          = config.apiKey;
+  const defaultModel = config.model ?? 'claude-sonnet-4-6';
 
   const headers = {
     'content-type':      'application/json',
@@ -20,28 +33,43 @@ export function create(config) {
     'anthropic-version': '2023-06-01',
   };
 
-  async function chat(messages) {
+  async function chat(messages, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, max_tokens, messages };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+    if (opts.system)              body.system      = opts.system;
+
     const res = await fetch(`${BASE}/messages`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ model, max_tokens: 1024, messages }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[anthropic] HTTP ${res.status}: ${await res.text()}`);
+    if (!res.ok) {
+      let errBody;
+      try { errBody = await res.json(); } catch { errBody = await res.text(); }
+      throw new AiError(res.status, 'anthropic', errBody);
+    }
     const data = await res.json();
     return (data.content ?? []).map((b) => b.text ?? '').join('').trim();
   }
 
-  async function ask(prompt) {
-    return chat([{ role: 'user', content: String(prompt) }]);
+  async function ask(prompt, opts = {}) {
+    return chat([{ role: 'user', content: String(prompt) }], opts);
   }
 
-  async function stream(messages, onChunk) {
+  async function stream(messages, onChunk, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, max_tokens, messages, stream: true };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
     const res = await fetch(`${BASE}/messages`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ model, max_tokens: 1024, messages, stream: true }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[anthropic] stream HTTP ${res.status}`);
+    if (!res.ok) throw new AiError(res.status, 'anthropic', `stream HTTP ${res.status}`);
     for await (const { event, data } of parseSSE(res.body)) {
       if (event === 'content_block_delta' || data?.type === 'content_block_delta') {
         onChunk(data.delta?.text ?? '');
@@ -49,11 +77,42 @@ export function create(config) {
     }
   }
 
+  async function complete(messages, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, max_tokens, messages };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+    if (opts.system)              body.system      = opts.system;
+
+    const res = await fetch(`${BASE}/messages`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      let errBody;
+      try { errBody = await res.json(); } catch { errBody = await res.text(); }
+      throw new AiError(res.status, 'anthropic', errBody);
+    }
+    const data = await res.json();
+    const text = (data.content ?? []).map((b) => b.text ?? '').join('').trim();
+    return {
+      text,
+      model: data.model ?? model,
+      provider: 'anthropic',
+      tokens: {
+        input:  data.usage?.input_tokens  ?? 0,
+        output: data.usage?.output_tokens ?? 0,
+        total:  (data.usage?.input_tokens ?? 0) + (data.usage?.output_tokens ?? 0),
+      },
+    };
+  }
+
   async function embed(text) {
     // Anthropic has no public embeddings endpoint — use keyword vector fallback.
     // For production semantic search, configure an OpenAI-compatible provider with an embed model.
     return keywordVector(String(text));
   }
 
-  return { name: 'anthropic', ask, chat, stream, embed };
+  return { name: 'anthropic', ask, chat, complete, stream, embed };
 }

package/runtime/providers/openai-compat.js

@@ -7,19 +7,20 @@
 // No separate SDK or special casing needed.
 
 import { parseSSE, keywordVector } from './util.js';
+import { AiError } from './anthropic.js';
 
 /**
  * Well-known provider presets. Used when FUTURE_AI_PROVIDER is set without FUTURE_AI_BASE_URL.
  * Users can always override by setting FUTURE_AI_BASE_URL directly.
  */
 export const PRESETS = {
-  openai:      { baseUrl: 'https://api.openai.com/v1',                         embedModel: 'text-embedding-3-small' },
-  ollama:      { baseUrl: 'http://localhost:11434/v1',                          embedModel: 'nomic-embed-text' },
-  openrouter:  { baseUrl: 'https://openrouter.ai/api/v1',                       embedModel: null },
+  openai:      { baseUrl: 'https://api.openai.com/v1',                              embedModel: 'text-embedding-3-small' },
+  ollama:      { baseUrl: 'http://localhost:11434/v1',                               embedModel: 'nomic-embed-text' },
+  openrouter:  { baseUrl: 'https://openrouter.ai/api/v1',                            embedModel: null },
   gemini:      { baseUrl: 'https://generativelanguage.googleapis.com/v1beta/openai', embedModel: 'text-embedding-004' },
-  venice:      { baseUrl: 'https://api.venice.ai/api/v1',                       embedModel: null },
-  groq:        { baseUrl: 'https://api.groq.com/openai/v1',                     embedModel: null },
-  together:    { baseUrl: 'https://api.together.xyz/v1',                        embedModel: 'togethercomputer/m2-bert-80M-8k-retrieval' },
+  venice:      { baseUrl: 'https://api.venice.ai/api/v1',                            embedModel: null },
+  groq:        { baseUrl: 'https://api.groq.com/openai/v1',                          embedModel: null },
+  together:    { baseUrl: 'https://api.together.xyz/v1',                             embedModel: 'togethercomputer/m2-bert-80M-8k-retrieval' },
 };
 
 /**
@@ -27,44 +28,89 @@ export const PRESETS = {
  * @param {{ baseUrl: string, apiKey: string, model?: string, embedModel?: string }} config
  */
 export function create(config) {
-  const baseUrl    = config.baseUrl.replace(/\/$/, '');
-  const apiKey     = config.apiKey;
-  const model      = config.model     ?? 'gpt-4o-mini';
-  const embedModel = config.embedModel ?? null;
+  const baseUrl      = config.baseUrl.replace(/\/$/, '');
+  const apiKey       = config.apiKey;
+  const defaultModel = config.model      ?? 'gpt-4o-mini';
+  const embedModel   = config.embedModel ?? null;
+  const providerTag  = `openai-compat(${baseUrl})`;
 
   const headers = {
     'content-type':  'application/json',
     'authorization': `Bearer ${apiKey}`,
   };
 
-  async function chat(messages) {
+  async function chat(messages, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, messages, max_tokens };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
     const res = await fetch(`${baseUrl}/chat/completions`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ model, messages, max_tokens: 1024 }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[ai/${baseUrl}] HTTP ${res.status}: ${await res.text()}`);
+    if (!res.ok) {
+      let errBody;
+      try { errBody = await res.json(); } catch { errBody = await res.text(); }
+      throw new AiError(res.status, providerTag, errBody);
+    }
     const data = await res.json();
     return data.choices?.[0]?.message?.content?.trim() ?? '';
   }
 
-  async function ask(prompt) {
-    return chat([{ role: 'user', content: String(prompt) }]);
+  async function ask(prompt, opts = {}) {
+    return chat([{ role: 'user', content: String(prompt) }], opts);
   }
 
-  async function stream(messages, onChunk) {
+  async function stream(messages, onChunk, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, messages, max_tokens, stream: true };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
     const res = await fetch(`${baseUrl}/chat/completions`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({ model, messages, max_tokens: 1024, stream: true }),
+      body: JSON.stringify(body),
     });
-    if (!res.ok) throw new Error(`[ai/${baseUrl}] stream HTTP ${res.status}`);
+    if (!res.ok) throw new AiError(res.status, providerTag, `stream HTTP ${res.status}`);
     for await (const { data } of parseSSE(res.body)) {
       const chunk = data.choices?.[0]?.delta?.content;
       if (chunk) onChunk(chunk);
     }
   }
 
+  async function complete(messages, opts = {}) {
+    const model      = opts.model      ?? defaultModel;
+    const max_tokens = opts.max_tokens ?? 1024;
+    const body       = { model, messages, max_tokens };
+    if (opts.temperature != null) body.temperature = opts.temperature;
+
+    const res = await fetch(`${baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      let errBody;
+      try { errBody = await res.json(); } catch { errBody = await res.text(); }
+      throw new AiError(res.status, providerTag, errBody);
+    }
+    const data = await res.json();
+    const text = data.choices?.[0]?.message?.content?.trim() ?? '';
+    return {
+      text,
+      model: data.model ?? model,
+      provider: providerTag,
+      tokens: {
+        input:  data.usage?.prompt_tokens     ?? 0,
+        output: data.usage?.completion_tokens ?? 0,
+        total:  data.usage?.total_tokens      ?? 0,
+      },
+    };
+  }
+
   async function embed(text) {
     if (!embedModel) return keywordVector(String(text));
     try {
@@ -81,5 +127,5 @@ export function create(config) {
     }
   }
 
-  return { name: `openai-compat(${baseUrl})`, ask, chat, stream, embed };
+  return { name: providerTag, ask, chat, complete, stream, embed };
 }