future-lang 0.3.0

package/runtime/index.js

@@ -0,0 +1,403 @@
+// runtime/index.js
+// Aggregates every capability namespace into a single `runtime` object that the
+// generated JavaScript imports as `__rt`. Add a module here and it instantly
+// becomes callable from Future as `<name>.<method>(...)`.
+
+import * as ai       from './ai.js';
+import * as http     from './http.js';
+import * as mqtt     from './mqtt.js';
+import * as tts      from './tts.js';
+import * as rag      from './rag.js';
+import * as vision   from './vision.js';
+import * as home     from './home.js';
+// Optional modules — fully backward-compatible additions.
+import * as memory   from './memory.js';
+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 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',
+];
+
+export const runtime = { ai, http, mqtt, tts, rag, vision, home, memory, schedule, system, device, math };
+
+// input(prompt) — reads a line from stdin (CLI programs).
+runtime.input = async (prompt = '') => {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(String(prompt), (answer) => { rl.close(); resolve(answer); });
+  });
+};
+
+// --- Structured manifest ---
+// Each function entry carries enough metadata for docs, editor tooling, REPL, and AI agents.
+// Shape: { description, params: [{ name, type, optional? }], returns, async }
+
+export const manifest = {
+  ai: {
+    configure: {
+      description: 'Set the AI provider — accepts a named provider ("openai", "anthropic", "ollama", "gemini", …) or a custom OpenAI-compatible base URL',
+      params: [
+        { name: 'providerOrUrl', type: 'string' },
+        { name: 'apiKey',        type: 'string' },
+        { name: 'model',         type: 'string', optional: true },
+      ],
+      returns: 'void',
+      async: false,
+    },
+    ask: {
+      description: 'Ask an AI model a question and get a text response',
+      params: [{ name: 'prompt', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    chat: {
+      description: 'Send a multi-turn message list to an AI model',
+      params: [{ name: 'messages', type: 'array' }],
+      returns: 'string',
+      async: true,
+    },
+    stream: {
+      description: 'Stream a response chunk by chunk via a callback function',
+      params: [
+        { name: 'prompt',   type: 'string' },
+        { name: 'onChunk',  type: 'function' },
+      ],
+      returns: 'void',
+      async: true,
+    },
+    embed: {
+      description: 'Generate a vector embedding for a piece of text',
+      params: [{ name: 'text', type: 'string' }],
+      returns: 'array',
+      async: true,
+    },
+  },
+
+  http: {
+    get: {
+      description: 'Perform an HTTP GET request and return the parsed response',
+      params: [
+        { name: 'url', type: 'string' },
+        { name: 'headers', type: 'object', optional: true },
+      ],
+      returns: 'any',
+      async: true,
+    },
+    post: {
+      description: 'Perform an HTTP POST request with a JSON body',
+      params: [
+        { name: 'url', type: 'string' },
+        { name: 'body', type: 'any' },
+        { name: 'headers', type: 'object', optional: true },
+      ],
+      returns: 'any',
+      async: true,
+    },
+  },
+
+  mqtt: {
+    publish: {
+      description: 'Publish a message to an MQTT topic',
+      params: [
+        { name: 'topic', type: 'string' },
+        { name: 'message', type: 'string' },
+      ],
+      returns: 'string',
+      async: true,
+    },
+    subscribe: {
+      description: 'Subscribe to an MQTT topic; handler is called on every message',
+      params: [
+        { name: 'topic', type: 'string' },
+        { name: 'handler', type: 'function' },
+      ],
+      returns: 'string',
+      async: true,
+    },
+  },
+
+  tts: {
+    speak: {
+      description: 'Speak text aloud using the system text-to-speech engine',
+      params: [{ name: 'text', type: 'string' }],
+      returns: 'void',
+      async: true,
+    },
+  },
+
+  rag: {
+    index: {
+      description: 'Index documents into the default knowledge base (chunks, embeds, stores)',
+      params: [{ name: 'docs', type: 'array|string' }],
+      returns: 'object',
+      async: true,
+    },
+    query: {
+      description: 'Query the default knowledge base and get an LLM-generated answer',
+      params: [{ name: 'question', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    create: {
+      description: 'Create a named Knowledge Base with its own isolated vector store',
+      params: [
+        { name: 'name', type: 'string' },
+        { name: 'opts', type: 'object', optional: true },
+      ],
+      returns: 'KnowledgeBase',
+      async: false,
+    },
+    indexFile: {
+      description: 'Read a local file and index its content into the default knowledge base',
+      params: [{ name: 'filePath', type: 'string' }],
+      returns: 'object',
+      async: true,
+    },
+    indexUrl: {
+      description: 'Fetch a URL and index its text content into the default knowledge base',
+      params: [{ name: 'url', type: 'string' }],
+      returns: 'object',
+      async: true,
+    },
+    stats: {
+      description: 'Return stats for the default knowledge base (chunk count, vector count)',
+      params: [],
+      returns: 'object',
+      async: false,
+    },
+  },
+
+  vision: {
+    describe: {
+      description: 'Describe the contents of an image using a vision AI model',
+      params: [{ name: 'image', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    detect: {
+      description: 'Detect and list objects, people, or labels visible in an image',
+      params: [{ name: 'image', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    ocr: {
+      description: 'Extract all readable text from an image (OCR)',
+      params: [{ name: 'image', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    classify: {
+      description: 'Classify an image into a primary category',
+      params: [{ name: 'image', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    compare: {
+      description: 'Compare two images and describe their differences',
+      params: [
+        { name: 'imageA', type: 'string' },
+        { name: 'imageB', type: 'string' },
+      ],
+      returns: 'string',
+      async: true,
+    },
+  },
+
+  home: {
+    turnOn: {
+      description: 'Turn a home automation device on',
+      params: [{ name: 'device', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    turnOff: {
+      description: 'Turn a home automation device off',
+      params: [{ name: 'device', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    set: {
+      description: 'Set a home automation device to an arbitrary value',
+      params: [
+        { name: 'device', type: 'string' },
+        { name: 'value', type: 'any' },
+      ],
+      returns: 'string',
+      async: true,
+    },
+  },
+
+  memory: {
+    forget: {
+      description: 'Delete all keys matching a pattern, or clear everything if no pattern given',
+      params: [{ name: 'pattern', type: 'string|RegExp', optional: true }],
+      returns: 'number',
+      async: false,
+    },
+    set: {
+      description: 'Store a value in the in-process memory store',
+      params: [
+        { name: 'key', type: 'string' },
+        { name: 'value', type: 'any' },
+      ],
+      returns: 'any',
+      async: false,
+    },
+    get: {
+      description: 'Retrieve a value from the memory store',
+      params: [{ name: 'key', type: 'string' }],
+      returns: 'any',
+      async: false,
+    },
+    delete: {
+      description: 'Delete a key from the memory store',
+      params: [{ name: 'key', type: 'string' }],
+      returns: 'boolean',
+      async: false,
+    },
+    search: {
+      description: 'Search memory entries whose key or value contains the query string',
+      params: [{ name: 'query', type: 'string' }],
+      returns: 'array',
+      async: false,
+    },
+  },
+
+  schedule: {
+    every: {
+      description: 'Run a callback repeatedly at a fixed interval (e.g. "30m", "5s")',
+      params: [
+        { name: 'interval', type: 'string|number' },
+        { name: 'callback', type: 'function' },
+      ],
+      returns: 'Timeout',
+      async: true,
+    },
+    once: {
+      description: 'Run a callback once after a delay (e.g. "10s", 5000)',
+      params: [
+        { name: 'delay', type: 'string|number' },
+        { name: 'callback', type: 'function' },
+      ],
+      returns: 'any',
+      async: true,
+    },
+    cron: {
+      description: 'Run a callback on a cron schedule (requires node-cron)',
+      params: [
+        { name: 'expression', type: 'string' },
+        { name: 'callback', type: 'function' },
+      ],
+      returns: 'any',
+      async: true,
+    },
+  },
+
+  system: {
+    env: {
+      description: 'Read an environment variable; returns null if not set',
+      params: [{ name: 'name', type: 'string' }],
+      returns: 'string|null',
+      async: false,
+    },
+    exec: {
+      description: 'Execute a shell command and return its stdout',
+      params: [{ name: 'command', type: 'string|array' }],
+      returns: 'string',
+      async: true,
+    },
+    open: {
+      description: 'Open a file path or URL with the OS default application',
+      params: [{ name: 'target', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    notify: {
+      description: 'Send a desktop notification with a message',
+      params: [{ name: 'message', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    read: {
+      description: 'Read a file and return its content as a string',
+      params: [{ name: 'path', type: 'string' }],
+      returns: 'string',
+      async: true,
+    },
+    write: {
+      description: 'Write a string to a file (creates or overwrites)',
+      params: [
+        { name: 'path',    type: 'string' },
+        { name: 'content', type: 'string' },
+      ],
+      returns: 'string',
+      async: true,
+    },
+  },
+
+  device: {
+    register: {
+      description: 'Register an IoT device with a configuration object (name is required)',
+      params: [{ name: 'config', type: 'object' }],
+      returns: 'object',
+      async: false,
+    },
+    get: {
+      description: 'Look up a registered device by name',
+      params: [{ name: 'name', type: 'string' }],
+      returns: 'object|null',
+      async: false,
+    },
+    list: {
+      description: 'List all registered devices',
+      params: [],
+      returns: 'array',
+      async: false,
+    },
+  },
+
+  math: {
+    round:  { description: 'Round to nearest integer',        params: [{ name: 'x', type: 'number' }], returns: 'number', async: false },
+    floor:  { description: 'Round down to nearest integer',   params: [{ name: 'x', type: 'number' }], returns: 'number', async: false },
+    ceil:   { description: 'Round up to nearest integer',     params: [{ name: 'x', type: 'number' }], returns: 'number', async: false },
+    abs:    { description: 'Absolute value',                  params: [{ name: 'x', type: 'number' }], returns: 'number', async: false },
+    sqrt:   { description: 'Square root',                     params: [{ name: 'x', type: 'number' }], returns: 'number', async: false },
+    pow:    { description: 'x raised to the power y',         params: [{ name: 'x', type: 'number' }, { name: 'y', type: 'number' }], returns: 'number', async: false },
+    log:    { description: 'Natural logarithm',               params: [{ name: 'x', type: 'number' }], returns: 'number', async: false },
+    random: { description: 'Random float between 0 and 1',   params: [], returns: 'number', async: false },
+    min:    { description: 'Smallest of the given values',    params: [{ name: '...values', type: 'number' }], returns: 'number', async: false },
+    max:    { description: 'Largest of the given values',     params: [{ name: '...values', type: 'number' }], returns: 'number', async: false },
+    pi:     { description: 'The mathematical constant π',     params: [], returns: 'number', async: false },
+    e:      { description: "Euler's number",                  params: [], returns: 'number', async: false },
+  },
+};
+
+// --- Introspection API ---
+// These methods allow programs, REPLs, and AI agents to discover the runtime at run time.
+
+/** List all available module names. */
+runtime.listModules = () => [...MODULE_NAMES];
+
+/** List all function names exported by a module. */
+runtime.listFunctions = (mod) => {
+  const m = manifest[mod];
+  return m ? Object.keys(m) : [];
+};
+
+/**
+ * Full description of the runtime: version, module list, and complete manifest.
+ * Suitable for AI agent discovery or documentation generation.
+ */
+runtime.describe = () => ({
+  version: '0.2.0',
+  modules: [...MODULE_NAMES],
+  manifest,
+});
+
+export default runtime;

package/runtime/lsp-metadata.js

@@ -0,0 +1,104 @@
+// runtime/lsp-metadata.js
+// Generates VSCode / Language Server Protocol compatible metadata from the
+// runtime manifest. Consume this in a Future LSP server or VSCode extension to
+// provide completion items, hover documentation, and signature help.
+
+import { manifest } from './index.js';
+
+/**
+ * Generate a flat list of completion items for all capability methods.
+ * Each item follows the LSP CompletionItem shape (kind names, not numeric codes).
+ * @returns {object[]}
+ */
+export function generateCompletions() {
+  const items = [];
+  for (const [module, methods] of Object.entries(manifest)) {
+    for (const [name, meta] of Object.entries(methods)) {
+      const required = meta.params.filter((p) => !p.optional);
+      const optional = meta.params.filter((p) => p.optional);
+      const paramList = [
+        ...required.map((p) => p.name),
+        ...optional.map((p) => `${p.name}?`),
+      ].join(', ');
+      const snippet = `${module}.${name}(${
+        meta.params.map((p, i) => `\${${i + 1}:${p.name}}`).join(', ')
+      })`;
+      items.push({
+        label: `${module}.${name}`,
+        kind: 'Function',
+        detail: `${module}.${name}(${paramList}) → ${meta.async ? `Promise<${meta.returns}>` : meta.returns}`,
+        documentation: meta.description,
+        insertText: snippet,
+        insertTextFormat: 'Snippet',
+        module,
+        method: name,
+        async: meta.async,
+      });
+    }
+  }
+  return items;
+}
+
+/**
+ * Generate hover documentation for a specific module.method pair.
+ * @param {string} module
+ * @param {string} method
+ * @returns {{ signature: string, description: string, params: object[] } | null}
+ */
+export function generateHoverInfo(module, method) {
+  const meta = manifest[module]?.[method];
+  if (!meta) return null;
+  const paramList = meta.params
+    .map((p) => `${p.name}${p.optional ? '?' : ''}: ${p.type}`)
+    .join(', ');
+  const ret = meta.async ? `Promise<${meta.returns}>` : meta.returns;
+  return {
+    signature: `${module}.${method}(${paramList}): ${ret}`,
+    description: meta.description,
+    params: meta.params,
+  };
+}
+
+/**
+ * Signature help for a specific module.method — used when the user types `(`.
+ * @returns {{ label: string, parameters: object[] } | null}
+ */
+export function generateSignatureHelp(module, method) {
+  const meta = manifest[module]?.[method];
+  if (!meta) return null;
+  const paramStrings = meta.params.map((p) => `${p.name}${p.optional ? '?' : ''}: ${p.type}`);
+  const label = `${module}.${method}(${paramStrings.join(', ')})`;
+  return {
+    label,
+    documentation: meta.description,
+    parameters: meta.params.map((p, i) => ({
+      label: paramStrings[i],
+      documentation: p.optional ? `Optional. Type: ${p.type}` : `Type: ${p.type}`,
+    })),
+  };
+}
+
+/**
+ * All reserved keywords in the Future language.
+ * Used by syntax highlighters, LSP semantic tokens, and editor grammar files.
+ * @returns {string[]}
+ */
+export function generateLanguageKeywords() {
+  return ['print', 'if', 'else', 'end', 'function', 'return', 'true', 'false', 'and', 'or', 'not', 'on', 'every'];
+}
+
+/**
+ * Full LSP-ready metadata bundle.
+ * Suitable for initialising a Language Server or generating a VSCode extension's language contribution.
+ * @returns {object}
+ */
+export function generateLanguageMetadata() {
+  return {
+    languageId: 'future',
+    fileExtensions: ['.future'],
+    keywords: generateLanguageKeywords(),
+    completions: generateCompletions(),
+    modules: Object.keys(manifest),
+    manifest,
+  };
+}

package/runtime/math.js

@@ -0,0 +1,16 @@
+// runtime/math.js — Math module for the Future language.
+// All functions mirror JavaScript's Math object so Future programs can do
+// numeric work without importing anything explicitly.
+
+export const round  = (x)       => Math.round(Number(x));
+export const floor  = (x)       => Math.floor(Number(x));
+export const ceil   = (x)       => Math.ceil(Number(x));
+export const abs    = (x)       => Math.abs(Number(x));
+export const sqrt   = (x)       => Math.sqrt(Number(x));
+export const pow    = (x, y)    => Math.pow(Number(x), Number(y));
+export const log    = (x)       => Math.log(Number(x));
+export const random = ()        => Math.random();
+export const min    = (...args) => Math.min(...args.map(Number));
+export const max    = (...args) => Math.max(...args.map(Number));
+export const pi     = Math.PI;
+export const e      = Math.E;

package/runtime/memory.js

@@ -0,0 +1,61 @@
+// runtime/memory.js — In-process key-value store with fuzzy search.
+// Suitable for session state, conversation context, and lightweight RAG-style retrieval.
+// Swap the `store` Map for a Redis/SQLite/vector-DB client to go persistent.
+
+const store = new Map();
+
+/** Store a value under a key. @returns the stored value. */
+export function set(key, value) {
+  store.set(String(key), value);
+  return value;
+}
+
+/** Retrieve a value by key. @returns the value or null. */
+export function get(key) {
+  return store.has(String(key)) ? store.get(String(key)) : null;
+}
+
+/** Remove a key. @returns true if the key existed. */
+function memDelete(key) {
+  return store.delete(String(key));
+}
+export { memDelete as delete };
+
+/**
+ * Search all stored entries whose key or stringified value contains the query.
+ * @returns {Array<{ key: string, value: any }>}
+ */
+export function search(query) {
+  const q = String(query).toLowerCase();
+  const results = [];
+  for (const [key, value] of store) {
+    const v = typeof value === 'string' ? value : JSON.stringify(value);
+    if (key.toLowerCase().includes(q) || v.toLowerCase().includes(q)) {
+      results.push({ key, value });
+    }
+  }
+  return results;
+}
+
+/**
+ * Forget (delete) all keys that match a pattern.
+ * Pattern can be an exact key, a substring, or a RegExp.
+ * With no argument, clears everything.
+ * @param {string|RegExp} [pattern]
+ * @returns {number} number of keys removed.
+ */
+export function forget(pattern) {
+  if (pattern === undefined) {
+    const count = store.size;
+    store.clear();
+    return count;
+  }
+  const test = pattern instanceof RegExp
+    ? (k) => pattern.test(k)
+    : (k) => k.includes(String(pattern));
+  let removed = 0;
+  for (const key of [...store.keys()]) {
+    if (test(key)) { store.delete(key); removed++; }
+  }
+  return removed;
+}

package/runtime/mqtt.js

@@ -0,0 +1,49 @@
+// runtime/mqtt.js — MQTT publish/subscribe.
+// Uses the `mqtt` npm package + MQTT_URL when available. With no broker it falls
+// back to an in-process loopback so publish/subscribe still work for demos/tests.
+
+import process from 'node:process';
+
+let client = null;                 // real client, or false for offline mode
+const localSubs = new Map();       // topic -> handler[]  (offline fallback)
+
+async function getClient() {
+  if (client !== null) return client;
+  const url = process.env.MQTT_URL;
+  if (!url) { client = false; return client; }
+  try {
+    const mod = await import('mqtt');
+    const c = mod.default.connect(url);
+    await new Promise((res, rej) => { c.once('connect', res); c.once('error', rej); });
+    client = c;
+  } catch (e) {
+    console.warn(`[mqtt] broker/package unavailable (${e.message}); using local loopback.`);
+    client = false;
+  }
+  return client;
+}
+
+/** Publish a message to a topic. @returns {Promise<string>} the payload sent. */
+export async function publish(topic, message) {
+  const c = await getClient();
+  const payload = typeof message === 'string' ? message : JSON.stringify(message);
+  if (c) {
+    await new Promise((res) => c.publish(topic, payload, res));
+  } else {
+    for (const h of localSubs.get(topic) || []) h(payload, topic);
+  }
+  return payload;
+}
+
+/** Subscribe to a topic. `handler(message, topic)` runs on each message. */
+export async function subscribe(topic, handler) {
+  const c = await getClient();
+  if (c) {
+    c.subscribe(topic);
+    c.on('message', (t, buf) => { if (t === topic) handler(buf.toString(), t); });
+  } else {
+    if (!localSubs.has(topic)) localSubs.set(topic, []);
+    localSubs.get(topic).push(handler);
+  }
+  return topic;
+}

package/runtime/providers/anthropic.js

@@ -0,0 +1,59 @@
+// runtime/providers/anthropic.js — Anthropic native Messages API.
+// Supports: ask, chat, stream. embed() falls back to keyword vectors
+// because Anthropic doesn't have a public embeddings endpoint yet.
+
+import { parseSSE, keywordVector } from './util.js';
+
+const BASE = 'https://api.anthropic.com/v1';
+
+/**
+ * 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 headers = {
+    'content-type':      'application/json',
+    'x-api-key':         key,
+    'anthropic-version': '2023-06-01',
+  };
+
+  async function chat(messages) {
+    const res = await fetch(`${BASE}/messages`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ model, max_tokens: 1024, messages }),
+    });
+    if (!res.ok) throw new Error(`[anthropic] HTTP ${res.status}: ${await res.text()}`);
+    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 stream(messages, onChunk) {
+    const res = await fetch(`${BASE}/messages`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({ model, max_tokens: 1024, messages, stream: true }),
+    });
+    if (!res.ok) throw new Error(`[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 ?? '');
+      }
+    }
+  }
+
+  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 };
+}