future-lang 0.3.2 → 0.4.1

package/FUTURE_FOR_LLMS.md

@@ -0,0 +1,364 @@
+# Future — Reference for LLMs
+
+Future is a small language that compiles to JavaScript. It does NOT exist in your training data. Read this file before generating Future code.
+
+---
+
+## Reserved words
+
+```
+print  if  else  end  function  return  true  false  null  none
+and  or  not  for  in  while  try  catch  on  every  stream
+agent  use  as
+```
+
+Reserved namespaces (cannot be reassigned or used as function names):
+```
+ai  http  mqtt  tts  rag  vision  home  memory  schedule  system  device  math  assert
+```
+
+---
+
+## Grammar (simplified BNF)
+
+```
+program     = statement*
+statement   = print | assignment | if | function | return
+            | for | while | try | on | every | stream | agent | use | expr_stmt
+
+print       = "print" expression
+assignment  = IDENTIFIER "=" expression
+if          = "if" expression block ("else if" expression block)* ("else" block)? "end"
+function    = "function" IDENTIFIER "(" params ")" block "end"
+return      = "return" expression?
+for         = "for" IDENTIFIER "in" expression block "end"
+while       = "while" expression block "end"
+try         = "try" block "catch" IDENTIFIER block "end"
+on          = "on" IDENTIFIER expression block "end"
+every       = "every" expression block "end"
+stream      = "stream" call_expr block "end"
+agent       = "agent" IDENTIFIER ("use" IDENTIFIER)* block "end"
+use         = "use" STRING ("as" IDENTIFIER)?
+
+block       = statement*
+params      = (IDENTIFIER ("," IDENTIFIER)*)?
+expression  = or_expr
+call_expr   = IDENTIFIER "(" args ")"
+            | IDENTIFIER "." IDENTIFIER "(" args ")"
+args        = (expression ("," expression)*)?
+```
+
+---
+
+## Syntax rules
+
+- Blocks end with `end` — NO curly braces, NO semicolons
+- `#` starts a line comment
+- Strings: `"double"` or `'single'`
+- String interpolation: `"Hello, {name}!"` — any `{identifier}` or `{identifier.prop}`
+- Escape literal brace: `\{`
+- `null` and `none` are the same
+- Commas in lists: required — `[1, 2, 3]`
+- Commas in objects: optional — `{ name: "Alice"  age: 30 }` or `{ name: "Alice", age: 30 }`
+
+---
+
+## Every construct with example
+
+### Variables
+```
+name = "Alice"
+age  = 30
+ok   = true
+data = null
+```
+
+### Print
+```
+print "Hello, {name}!"
+print age
+```
+
+### If / else if / else
+```
+if score >= 90
+    print "A"
+else if score >= 80
+    print "B"
+else if score >= 70
+    print "C"
+else
+    print "F"
+end
+```
+
+### Function
+```
+function add(a, b)
+    return a + b
+end
+
+result = add(3, 4)
+print result
+```
+
+### For loop
+```
+fruits = ["apple", "banana", "cherry"]
+for fruit in fruits
+    print "I like {fruit}"
+end
+```
+
+### While loop
+```
+count = 0
+while count < 5
+    count = count + 1
+end
+```
+
+### Try / catch
+```
+try
+    data = http.get("https://api.example.com/data")
+    print data.title
+catch err
+    print "Error: {err}"
+end
+```
+
+### Objects and lists
+```
+user   = { name: "João"  age: 30  city: "Lisbon" }
+scores = [85, 92, 78]
+print user.name
+print scores.length
+```
+
+### String interpolation
+```
+msg = "Name: {user.name}, Age: {user.age}"
+print msg
+print "Pi is {math.pi}"
+```
+
+---
+
+## Import system
+
+```
+# Import all functions from a file by name
+use "./utils.future"
+result = formatName("Alice")
+
+# Import as a namespace
+use "./math.future" as m
+result = m.add(10, 20)
+
+# Import an npm package as a namespace
+use "date-fns" as df
+```
+
+Imported `.future` files must contain only top-level function declarations. They compile to ES module exports automatically.
+
+---
+
+## Capability namespaces
+
+No `async`/`await` needed — the compiler handles it. Any namespace call switches the program to async mode automatically.
+
+### `ai`
+```
+answer  = ai.ask("What is the capital of France?")
+reply   = ai.chat([{ role: "user"  content: "Hello" }])
+embed   = ai.embed("text to embed")
+ai.configure("openai", "sk-...")
+ai.configure("ollama")
+
+# With options: temperature and max_tokens
+answer = ai.ask("Explain quantum physics", { temperature: 0.2  max_tokens: 200 })
+reply  = ai.chat(messages, { model: "gpt-4o"  temperature: 0.7 })
+
+stream ai.ask("Tell me a story")
+    print chunk
+end
+```
+
+### `http`
+```
+data = http.get("https://api.example.com/todos/1")
+print data.title
+
+res = http.post("https://api.example.com/items", { name: "Widget"  price: 9.99 })
+print res.id
+```
+
+### `mqtt`
+```
+mqtt.publish("home/light", "on")
+
+on mqtt "home/temp"
+    print "Temperature: {message}"
+end
+```
+
+### `tts`
+```
+tts.speak("Hello from Future!")
+```
+
+### `memory`
+```
+memory.set("key", "value")
+val = memory.get("key")
+memory.delete("key")
+results = memory.search("query")
+memory.forget()          # clear all
+memory.forget("prefix")  # clear matching keys
+```
+
+### `schedule`
+```
+every "30m"
+    data = http.get("https://api.example.com/stats")
+    print data.count
+end
+
+# schedule.once and schedule.cron also available
+```
+
+### `http`
+```
+data = http.get("https://api.example.com/todos/1")
+print data.title
+
+res = http.post("https://api.example.com/items", { name: "Widget"  price: 9.99 })
+print res.id
+
+# Global config (call once at the top of your program)
+http.configure({ headers: { Authorization: "Bearer {token}" }  timeout: 5000 })
+
+# Errors have .status, .code, .url, .body properties
+try
+    data = http.get("https://api.example.com/private")
+catch err
+    print "Status: {err.status}"
+    print "Code: {err.code}"
+end
+```
+
+### `assert` (use in *.test.future files)
+```
+assert.ok(value)
+assert.equal(actual, expected)
+assert.notEqual(a, b)
+assert.deepEqual(obj1, obj2)
+assert.fail("custom message")
+```
+
+### `system`, `rag`, `vision`, `home`, `device`
+See [README.md](README.md) for full API tables.
+
+### `math`
+```
+print math.round(3.7)    # 4
+print math.sqrt(16)      # 4
+print math.pi            # 3.14159…
+print math.random()      # 0–1
+print math.max(1, 5, 3)  # 5
+```
+
+### `len` (built-in, not a namespace)
+```
+print len([1, 2, 3])          # 3
+print len("hello")            # 5
+print len({ a: 1  b: 2 })     # 2
+```
+
+---
+
+## Agents
+
+```
+agent support
+    use rag
+    use memory
+
+    docs = rag.query(goal)
+    memory.set("last", goal)
+    return docs
+end
+
+answer = support("How do I reset the device?")
+print answer
+```
+
+`goal` is the implicit parameter. `use` inside an agent declares capabilities (documentation only — no generated code).
+
+---
+
+## Common mistakes
+
+| Wrong | Correct |
+|-------|---------|
+| `if (x > 0) {` | `if x > 0` |
+| `end if` | `end` |
+| `elif` | `else if` |
+| `&&` / `\|\|` / `!` | `and` / `or` / `not` |
+| `x++` | `x = x + 1` |
+| `x += 1` | `x = x + 1` |
+| `// comment` | `# comment` |
+| `import "./utils.js"` | `use "./utils.future"` |
+| `let x = 5` | `x = 5` |
+| `function f() { }` | `function f()` + body + `end` |
+
+---
+
+## What compiles to what
+
+```future
+x = 1
+```
+```js
+let x;
+x = 1;
+```
+
+```future
+if x > 0
+    print "positive"
+else if x < 0
+    print "negative"
+else
+    print "zero"
+end
+```
+```js
+if (x > 0) {
+  console.log("positive");
+} else if (x < 0) {
+  console.log("negative");
+} else {
+  console.log("zero");
+}
+```
+
+```future
+answer = ai.ask("Hello?")
+```
+```js
+import { runtime as __rt } from "future-lang/runtime";
+let answer;
+answer = await __rt.ai.ask("Hello?");
+```
+
+```future
+use "./utils.future"
+name = formatName("Alice")
+```
+```js
+import { formatName } from "./utils.js";
+let name;
+name = formatName("Alice");
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "future-lang",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "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,42 @@ 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);
 }
 
 /**

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,46 @@ 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',
 ];
 
-export const runtime = { 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.
+ * Non-function properties (constants like math.pi) pass through unchanged.
+ */
+function wrapDebug(base) {
+  const wrapped = {};
+  for (const [ns, mod] of Object.entries(base)) {
+    wrapped[ns] = {};
+    for (const [key, val] of Object.entries(mod)) {
+      if (typeof val !== 'function') { wrapped[ns][key] = val; continue; }
+      wrapped[ns][key] = async (...args) => {
+        const preview = args.length ? String(JSON.stringify(args[0])).slice(0, 60) : '';
+        process.stderr.write(`\x1b[90m[debug] ${ns}.${key}(${preview}) …\x1b[0m\n`);
+        const t = Date.now();
+        try {
+          const result = await val(...args);
+          process.stderr.write(`\x1b[90m[debug] ${ns}.${key} ✓ ${Date.now() - t}ms\x1b[0m\n`);
+          return result;
+        } catch (err) {
+          process.stderr.write(`\x1b[31m[debug] ${ns}.${key} ✗ ${Date.now() - t}ms — ${err.message}\x1b[0m\n`);
+          throw err;
+        }
+      };
+    }
+  }
+  return wrapped;
+}
+
+export const runtime = process.env.FUTURE_DEBUG === '1' ? wrapDebug(_base) : _base;
 
 // input(prompt) — reads a line from stdin (CLI programs).
 runtime.input = async (prompt = '') => {
@@ -376,6 +407,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 ---
@@ -395,7 +434,7 @@ runtime.listFunctions = (mod) => {
  * Suitable for AI agent discovery or documentation generation.
  */
 runtime.describe = () => ({
-  version: '0.2.0',
+  version: '0.4.1',
   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 ?? '');