neuralos 3.9.5 → 3.9.6

package/cli.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { Needle } = require('./index');
+
+function usage(code = 0) {
+  const text = `neuralos ${require('./package.json').version} — offline tool-calling + embeddings engine
+
+Usage:
+  neuralos run   --tools <tools.json> [--impl <impl.js>] [--system <text>]
+                 [--query <text>] [--max-steps <n>] [--max-new-tokens <n>]
+  neuralos embed --text <text>
+  neuralos info
+
+tools.json: array of { name, description, parameters }
+impl.js:    optional module exporting { toolName: (args) => result } functions
+`;
+  process.stdout.write(text);
+  process.exit(code);
+}
+
+function argValue(flag, argv) {
+  const i = argv.indexOf(flag);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+const argv = process.argv.slice(2);
+const command = argv[0];
+
+try {
+  if (!command || command === '--help' || command === '-h') usage(0);
+
+  if (command === 'info') {
+    const info = require('./index').engineInfo();
+    console.log(JSON.stringify(info, null, 2));
+    process.exit(0);
+  }
+
+  if (command === 'embed') {
+    const text = argValue('--text', argv);
+    if (!text) usage(1);
+    const agent = new Needle();
+    process.stdout.write(JSON.stringify(agent.embed(text)) + '\n');
+    process.exit(0);
+  }
+
+  if (command === 'run') {
+    const toolsPath = argValue('--tools', argv);
+    const implPath = argValue('--impl', argv);
+    const query = argValue('--query', argv) || '';
+    const system = argValue('--system', argv) || '';
+    const maxSteps = Number(argValue('--max-steps', argv) || 8);
+    const maxNewTokens = Number(argValue('--max-new-tokens', argv) || 512);
+    if (!toolsPath) usage(1);
+
+    const schemas = JSON.parse(fs.readFileSync(path.resolve(toolsPath), 'utf8'));
+    const tools = schemas.map((schema) => {
+      const entry = { ...schema };
+      if (implPath) {
+        const impls = require(path.resolve(implPath));
+        if (typeof impls[schema.name] === 'function') {
+          entry.implementation = impls[schema.name];
+        }
+      }
+      return entry;
+    });
+    const agent = new Needle({ tools, system });
+    process.stdout.write(JSON.stringify(agent.run(query, { maxSteps, maxNewTokens }), null, 2) + '\n');
+    process.exit(0);
+  }
+
+  usage(1);
+} catch (err) {
+  process.stderr.write(`neuralos: ${err && err.message ? err.message : err}\n`);
+  process.exit(1);
+}

package/engine.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * neuralOS engine loader — locates the platform engine package
+ * (libneedle3 shared library + needle3.cact weights), binds the C ABI
+ * through koffi, and loads the base weights once per process.
+ *
+ * The C ABI mirrors needle/__init__.py in the Python distribution:
+ *   int  needle_init(const char *system, const char *tools, const char *tool_index)
+ *   int  needle_complete(const char *text, int max_new_tokens, char *buffer, int buffer_len)
+ *   int  needle_embed(const char *text, float *out, int dim)
+ *   void needle_reset(void)
+ *   int  needle_load(const char *data, unsigned long long len)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const koffi = require('koffi');
+
+const PLATFORM_PACKAGES = {
+  'darwin-arm64': { pkg: 'neuralos-darwin-arm64', lib: 'libneedle3.dylib' },
+  'darwin-x64': { pkg: 'neuralos-darwin-x64', lib: 'libneedle3.dylib' },
+  'linux-x64-gnu': { pkg: 'neuralos-linux-x64-gnu', lib: 'libneedle3.so' },
+  'linux-arm64-gnu': { pkg: 'neuralos-linux-arm64-gnu', lib: 'libneedle3.so' },
+  'win32-x64': { pkg: 'neuralos-win32-x64', lib: 'libneedle3.dll' },
+};
+
+function platformKey() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin') return a === 'arm64' ? 'darwin-arm64' : (a === 'x64' ? 'darwin-x64' : null);
+  if (p === 'win32') return a === 'x64' ? 'win32-x64' : null;
+  if (p === 'linux') {
+    if (a !== 'x64' && a !== 'arm64') return null;
+    // musl (Alpine) engines are not bundled; detect via process.report.
+    try {
+      const report = process.report && process.report.getReport && process.report.getReport();
+      if (report && report.header && !report.header.glibcVersionRuntime) return null;
+    } catch (_) { /* assume glibc */ }
+    return a === 'x64' ? 'linux-x64-gnu' : 'linux-arm64-gnu';
+  }
+  return null;
+}
+
+function platformPackageDir() {
+  const key = platformKey();
+  if (!key) {
+    throw new Error(
+      `neuralOS: no bundled engine for ${process.platform}/${process.arch}. ` +
+      'Supported: darwin arm64/x64, linux x64/arm64 (glibc), win32 x64.');
+  }
+  const spec = PLATFORM_PACKAGES[key];
+  let dir;
+  try {
+    dir = path.dirname(require.resolve(spec.pkg + '/package.json'));
+  } catch (err) {
+    throw new Error(
+      `neuralOS: engine package ${spec.pkg} is not installed. Reinstall neuralos ` +
+      `(optional dependencies must be allowed: npm i neuralos --include=optional).`);
+  }
+  return { dir, lib: spec.lib, key };
+}
+
+let _engine = null;
+
+function engine() {
+  if (_engine) return _engine;
+  const { dir, lib: libName } = platformPackageDir();
+  const libPath = path.join(dir, 'bin', libName);
+  const weightsPath = path.join(dir, 'bin', 'needle3.cact');
+  if (!fs.existsSync(libPath)) throw new Error(`neuralOS: engine library missing: ${libPath}`);
+  if (!fs.existsSync(weightsPath)) throw new Error(`neuralOS: weights missing: ${weightsPath}`);
+
+  const lib = koffi.load(libPath);
+  const needleInit = lib.func('int needle_init(const char *system, const char *tools, const char *tool_index)');
+  const needleComplete = lib.func('int needle_complete(const char *text, int max_new_tokens, _Out_ char *buffer, int buffer_len)');
+  const needleEmbed = lib.func('int needle_embed(const char *text, float *out, int dim)');
+  const needleReset = lib.func('void needle_reset()');
+  const needleLoad = lib.func('int needle_load(const char *data, unsigned long long len)');
+
+  const weights = fs.readFileSync(weightsPath);
+  const dataPtr = koffi.as(weights, 'const char *');
+  if (needleLoad(dataPtr, weights.length) < 0) {
+    throw new Error(`neuralOS: needle_load failed for ${weightsPath}`);
+  }
+
+  _engine = {
+    libPath,
+    weightsPath,
+    init: (systemText, toolsJson, toolIndexPath) =>
+      needleInit(systemText, toolsJson, toolIndexPath || null),
+    complete: (text, maxNewTokens, buf, len) =>
+      needleComplete(text, maxNewTokens, buf, len),
+    embed: (text, out, dim) => needleEmbed(text, out, dim),
+    reset: () => needleReset(),
+    allocBuffer: (n) => koffi.alloc('char', n),
+    allocFloats: (n) => koffi.alloc('float', n),
+    // koffi.decode(ptr, 'string') would deref the pointer as char**; the
+    // correct read of a raw char buffer is 'char' + length, NUL-trimmed.
+    decodeString: (ptr, n) => {
+      const bytes = Buffer.from(koffi.decode(ptr, 'char', n));
+      const end = bytes.indexOf(0);
+      return bytes.subarray(0, end === -1 ? bytes.length : end).toString('utf8');
+    },
+    decodeFloats: (ptr, n) => koffi.decode(ptr, 'float', n),
+  };
+  return _engine;
+}
+
+/** The currently bound agent (needle_init is engine-global, like Python's). */
+let _active = null;
+
+function bindAgent(agent) {
+  const e = engine();
+  if (_active === agent) return e;
+  if (e.init(agent.systemText, agent.toolsJson, null) < 0) {
+    _active = null;
+    throw new Error('neuralOS: needle_init failed');
+  }
+  _active = agent;
+  return e;
+}
+
+module.exports = { engine, bindAgent, platformKey, platformPackageDir, PLATFORM_PACKAGES };

package/index.js

@@ -0,0 +1,160 @@
+'use strict';
+
+/**
+ * neuralOS — the automation foundation model for tiny devices, for Node.js.
+ *
+ * Offline tool-calling, structured extraction and embeddings on the bundled
+ * libneedle3 engine + needle3.cact weights (installed via the platform
+ * optional dependency for your OS/arch).
+ *
+ *   const { Needle, tool } = require('neuralos');
+ *
+ *   const getWeather = tool({
+ *     name: 'get_weather',
+ *     description: 'Get the current weather for a city.',
+ *     parameters: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+ *   }, (args) => ({ city: args.city, temp_c: 27, sky: 'clear' }));
+ *
+ *   const agent = new Needle({ tools: [getWeather] });
+ *   console.log(agent.run("What's the weather in Lagos?"));
+ */
+
+const engineLoader = require('./engine');
+const { normalizeTools, tool } = require('./tools');
+
+const UNRESET_TURNS = 4;
+
+function withDateFact(system, autoDate) {
+  const text = system || '';
+  if (!autoDate) return text;
+  // Mirror Python: skip when the caller already supplied a date fact/ISO stamp.
+  if (/\bdate\s*:/.test(text) || /\d{4}-\d{2}-\d{2}/.test(text)) return text;
+  const now = new Date();
+  const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+  const pad = (n) => String(n).padStart(2, '0');
+  const fact =
+    `date: ${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ` +
+    `${days[now.getDay()]} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+  if (!text.trim()) return fact;
+  return fact + '; ' + text;
+}
+
+class Needle {
+  constructor({
+    tools = [],
+    system = '',
+    autoDate = true,
+    stateless = false,
+    bufferSize = 65536,
+  } = {}) {
+    this._functions = new Map();
+    this._schemas = normalizeTools(tools, this._functions);
+    this.systemText = withDateFact(system, autoDate);
+    this.toolsJson = JSON.stringify(this._schemas);
+    this._stateless = !!stateless;
+    this._turns = 0;
+    this._bufferSize = bufferSize;
+    this._bind();
+  }
+
+  _bind() {
+    engineLoader.bindAgent(this);
+  }
+
+  _countQuery() {
+    this._turns++;
+    if (this._turns === UNRESET_TURNS + 1) {
+      console.warn(
+        `neuralOS: ${UNRESET_TURNS} queries on this agent without reset(); every turn stays in the ` +
+        'conversation, so unrelated queries lose accuracy. Call reset() between independent queries.');
+    }
+  }
+
+  complete(text = '', maxNewTokens = 512) {
+    if (this._stateless) this.reset();
+    this._countQuery();
+    return this._complete(text, maxNewTokens);
+  }
+
+  _complete(text, maxNewTokens, parse = true) {
+    this._bind();
+    const e = engineLoader.engine();
+    const buffer = e.allocBuffer(this._bufferSize);
+    const rc = e.complete(text || '', Math.trunc(maxNewTokens), buffer, this._bufferSize);
+    if (rc < 0) {
+      const detail = e.decodeString(buffer, this._bufferSize);
+      throw new Error(detail || `neuralOS: needle_complete failed (code ${rc})`);
+    }
+    const raw = e.decodeString(buffer, this._bufferSize);
+    if (!parse) return raw;
+    let response;
+    try {
+      response = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`neuralOS: engine returned an unparseable envelope (${err.message})`);
+    }
+    return response;
+  }
+
+  /** Execute tool calls until the model responds. Mirrors Python's run(). */
+  run(query = '', { maxSteps = 8, maxNewTokens = 512 } = {}) {
+    if (this._stateless) this.reset();
+    this._countQuery();
+    let response = this._complete(query, maxNewTokens);
+    const executed = [];
+    for (let step = 0; step < maxSteps; step++) {
+      const calls = response.function_calls || [];
+      if (response.type !== 'call' || !calls.length) break;
+      const results = [];
+      for (const call of calls) {
+        const name = String(call.name);
+        const fn = this._functions.get(name);
+        if (!fn) {
+          results.push({ error: 'unknown tool: ' + name });
+          continue;
+        }
+        try {
+          results.push(fn(call.arguments || {}));
+        } catch (err) {
+          results.push({ error: String((err && err.message) || err) });
+        }
+      }
+      executed.push(...results);
+      response = this._complete(JSON.stringify(results), maxNewTokens, false);
+      try { response = JSON.parse(response); } catch (_) { /* handled below */ }
+      if (typeof response !== 'object' || response === null) {
+        throw new Error('neuralOS: engine returned an unparseable envelope');
+      }
+    }
+    response.results = executed;
+    return response;
+  }
+
+  embed(text = '') {
+    this._bind();
+    const e = engineLoader.engine();
+    const dim = e.embed(text || '', null, 0);
+    if (dim <= 0) throw new Error(`neuralOS: needle_embed failed (code ${dim})`);
+    const out = e.allocFloats(dim);
+    const rc = e.embed(text || '', out, dim);
+    if (rc !== dim) throw new Error(`neuralOS: needle_embed failed (code ${rc})`);
+    return e.decodeFloats(out, dim);
+  }
+
+  reset() {
+    this._bind();
+    engineLoader.engine().reset();
+    this._turns = 0;
+  }
+}
+
+module.exports = {
+  Needle,
+  tool,
+  version: require('./package.json').version,
+  platformKey: engineLoader.platformKey,
+  engineInfo: () => {
+    const e = engineLoader.engine();
+    return { lib: e.libPath, weights: e.weightsPath };
+  },
+};

package/package.json

@@ -1,55 +1,49 @@
 {
-  "main": "bin/gybackend.cjs",
+  "name": "neuralos",
+  "version": "3.9.6",
+  "description": "neuralOS - automation foundation model for tiny devices: offline tool-calling + embeddings engine for Node.js, weights bundled",
+  "main": "index.js",
   "bin": {
-    "gybackend": "bin/gybackend.cjs"
+    "neuralos": "cli.js"
   },
+  "files": [
+    "index.js",
+    "engine.js",
+    "tools.js",
+    "cli.js",
+    "test.js",
+    "README.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=18"
   },
-  "dependencies": {
-    "@nats-io/jetstream": "^3.4.0",
-    "@nats-io/kv": "^3.4.0",
-    "@nats-io/transport-node": "^3.4.0",
-    "better-sqlite3": "^12.11.1"
-  },
-  "optionalDependencies": {
-    "node-pty": "1.2.0-beta.3",
-    "serialport": "^12.0.0",
-    "ssh2": "^1.17.0"
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DrOlu/neuralOS.git"
   },
+  "homepage": "https://github.com/DrOlu/neuralOS#readme",
   "keywords": [
-    "forward-deployed-engineer",
-    "fde",
-    "ai-terminal",
-    "ai-agent",
-    "ssh",
-    "winrm",
-    "serial-console",
-    "cisco",
-    "network-automation",
-    "sre",
-    "observability",
-    "incident-response",
-    "change-management",
-    "infrastructure-automation",
-    "runbooks",
     "neuralos",
-    "aiops",
-    "ai-sre",
-    "agentic-ai",
-    "chatops",
-    "self-healing",
-    "runbook-automation",
-    "closed-loop-remediation",
-    "mcp"
+    "needle",
+    "llm",
+    "tool-calling",
+    "structured-extraction",
+    "embeddings",
+    "on-device",
+    "offline",
+    "tinyml",
+    "ai"
   ],
-  "license": "MIT",
-  "homepage": "https://rterm.app",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/DrOlu/RTerm.git"
+  "dependencies": {
+    "koffi": "^2.9.0"
   },
-  "name": "neuralos",
-  "version": "3.9.5",
-  "description": "Standalone neuralOS backend (rterm-backend): AI-native terminal & agentic-AI operations platform. Ships the neuralOS plugin — on-device data agents (verified probe menus over real data sources, engine + weights auto-provisioned on first use)."
+  "optionalDependencies": {
+    "neuralos-darwin-arm64": "3.9.6",
+    "neuralos-darwin-x64": "3.9.6",
+    "neuralos-linux-x64-gnu": "3.9.6",
+    "neuralos-linux-arm64-gnu": "3.9.6",
+    "neuralos-win32-x64": "3.9.6"
+  }
 }

package/test.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { Needle, tool } = require('./index');
+
+const getWeather = tool({
+  name: 'get_weather',
+  description: 'Get the current weather for a city.',
+  parameters: {
+    type: 'object',
+    properties: { city: { type: 'string' } },
+    required: ['city'],
+  },
+}, (args) => ({ city: args.city, temp_c: 27, sky: 'clear' }));
+
+const agent = new Needle({ tools: [getWeather] });
+const result = agent.run('What is the weather in Lagos?');
+console.log(JSON.stringify(result.results));
+
+const vector = agent.embed('hello world');
+console.log('embed dim:', vector.length);

package/tools.js

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * Tool schema normalization. A tool is one of:
+ *   - a schema object: { name, description, parameters, implementation? }
+ *     (parameters is a JSON schema object; implementation is optional)
+ *   - a function with a `.needleSchema` property (schema + implementation in one)
+ *
+ * Tool functions receive ONE argument: the arguments object the model produced.
+ */
+
+function normalizeTools(tools, functions) {
+  const schemas = [];
+  for (const entry of tools || []) {
+    if (typeof entry === 'function' && entry.needleSchema) {
+      const schema = entry.needleSchema;
+      if (!schema || typeof schema.name !== 'string') {
+        throw new TypeError('neuralOS: function.needleSchema must be {name, description, parameters}');
+      }
+      schemas.push(schema);
+      functions.set(schema.name, entry);
+    } else if (entry && typeof entry === 'object' && typeof entry.name === 'string') {
+      schemas.push({
+        name: entry.name,
+        description: entry.description || '',
+        parameters: entry.parameters || { type: 'object', properties: {} },
+      });
+      if (typeof entry.implementation === 'function') {
+        functions.set(entry.name, entry.implementation);
+      }
+    } else {
+      throw new TypeError(
+        'neuralOS: each tool must be a schema object {name, description, parameters, implementation?} ' +
+        'or a function with a .needleSchema property');
+    }
+  }
+  return schemas;
+}
+
+/** A tiny `tool` helper, mirroring the Python decorator ergonomics. */
+function tool(schema, fn) {
+  const wrapped = (args) => fn(args);
+  wrapped.needleSchema = schema;
+  return wrapped;
+}
+
+module.exports = { normalizeTools, tool };