neuralos 3.9.5 → 3.10.0

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,230 @@
+'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?"));
+ *
+ * Structured extraction (Python parity):
+ *
+ *   const { extract, Field } = require('neuralos');
+ *   const invoice = extract('Invoice INV-7, 12 May 2024, total 49.62', {
+ *     type: 'object',
+ *     properties: {
+ *       invoice_no: Field({ type: 'string' }),
+ *       issue_date: Field({ type: 'string', format: 'date' }),
+ *       total:      Field({ type: 'number', ge: 0 }),
+ *     },
+ *     required: ['invoice_no', 'total'],
+ *   });
+ */
+
+const engineLoader = require('./engine');
+const { normalizeTools, tool, Field } = require('./tools');
+const { ExtractionValidationError, sourceYears, groundedNumberPaths,
+        ungroundedPaths, annotateUngrounded, validateExtraction } = require('./validate');
+
+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._seenYears = new Set();
+    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, annotate = 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})`);
+    }
+    for (const year of sourceYears(text || '')) this._seenYears.add(year);
+    if (annotate) {
+      annotateUngrounded(response, this._schemas, this._seenYears, this.systemText, text);
+    }
+    return response;
+  }
+
+  /** Execute tool calls until the model responds. Mirrors Python's run(). */
+  run(query = '', { maxSteps = 8, maxNewTokens = 512, strict = true } = {}) {
+    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 = [];
+      const ungrounded = ungroundedPaths(response);
+      for (const call of calls) {
+        const name = String(call.name);
+        let fabricated = [...(ungrounded.get(name) || [])].sort();
+        if (strict && fabricated.length) {
+          const grounded = groundedNumberPaths(call.arguments || {}, query, this.systemText);
+          fabricated = fabricated.filter((path) => !grounded.has(path));
+        }
+        if (strict && fabricated.length) {
+          results.push({ error: 'ungrounded ' + fabricated.join(', ') });
+          continue;
+        }
+        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, 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);
+  }
+
+  /** One-shot structured extraction against this agent's system prompt. */
+  extract(text, schema, { maxNewTokens = 512, strict = true } = {}) {
+    return extract(text, schema, {
+      system: this.systemText, maxNewTokens, strict, autoDate: false,
+    });
+  }
+
+  reset() {
+    this._bind();
+    engineLoader.engine().reset();
+    this._turns = 0;
+    this._seenYears = new Set();
+  }
+
+  close() {
+    this._closed = true;
+  }
+}
+
+/**
+ * One-shot structured extraction — Python-parity semantics:
+ * the record is the only tool, the first call is the answer, and with
+ * strict=true (default) ungrounded values raise ExtractionValidationError
+ * instead of being returned silently.
+ */
+function extract(text, schema, { system = '', maxNewTokens = 512, strict = true,
+                                  autoDate = true } = {}) {
+  const agent = new Needle({ tools: [schema], system, autoDate });
+  let response;
+  try {
+    response = agent._complete(text, maxNewTokens);
+  } finally {
+    agent.close();
+  }
+  const calls = (response.function_calls && response.function_calls.length)
+    ? response.function_calls
+    : (response.suppressed_calls || []);
+  if (!calls.length) return null;
+  const arguments_ = calls[0].arguments || {};
+  if (strict) validateExtraction(text, schema, arguments_, response, agent.systemText);
+  return arguments_;
+}
+
+module.exports = {
+  Needle,
+  tool,
+  Field,
+  extract,
+  ExtractionValidationError,
+  validate: require('./validate'),
+  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,50 @@
 {
-  "main": "bin/gybackend.cjs",
+  "name": "neuralos",
+  "version": "3.10.0",
+  "description": "neuralOS - automation foundation model for tiny devices: offline tool-calling, structured extraction and embeddings for Node.js, weights bundled",
+  "main": "index.js",
   "bin": {
-    "gybackend": "bin/gybackend.cjs"
+    "neuralos": "cli.js"
   },
+  "files": [
+    "index.js",
+    "engine.js",
+    "validate.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.10.0",
+    "neuralos-darwin-x64": "3.10.0",
+    "neuralos-linux-x64-gnu": "3.10.0",
+    "neuralos-linux-arm64-gnu": "3.10.0",
+    "neuralos-win32-x64": "3.10.0"
+  }
 }

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,89 @@
+'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 if (entry && typeof entry === 'object') {
+      // An ANONYMOUS schema: the record itself is the only tool (Python parity —
+      // needle._resolve passes plain dicts through unwrapped, which is what
+      // extract() relies on: the engine answers with arguments only).
+      schemas.push(entry);
+    } 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;
+}
+
+/**
+ * Field — declarative constraints for a schema property, mirroring the Python
+ * `needle.Field`. Build the property, then attach it to your JSON schema:
+ *
+ *   parameters: {
+ *     type: 'object',
+ *     properties: {
+ *       total: Field({ type: 'number', description: 'invoice total', ge: 0 }),
+ *       status: Field({ type: 'string', enum: ['paid', 'unpaid', 'overdue'] }),
+ *     },
+ *     required: ['total'],
+ *   }
+ *
+ * Python parity: ge/le → minimum/maximum, gt/lt → exclusiveMinimum/Maximum,
+ * min_length/max_length → minLength/maxLength, min_items/max_items →
+ * minItems/maxItems, plus enum/const/pattern/format/multipleOf.
+ */
+function Field({ default: defaultValue, description, enum: enum_, const: const_,
+                 ge, le, gt, lt, multiple_of: multipleOf, min_length: minLength,
+                 max_length: maxLength, pattern, format, min_items: minItems,
+                 max_items: maxItems, unique_items: uniqueItems, ...rest } = {}) {
+  const schema = { ...rest };
+  const pairs = [['description', description], ['enum', enum_],
+                 ['minimum', ge], ['maximum', le],
+                 ['exclusiveMinimum', gt], ['exclusiveMaximum', lt],
+                 ['multipleOf', multipleOf], ['minLength', minLength],
+                 ['maxLength', maxLength], ['pattern', pattern], ['format', format],
+                 ['minItems', minItems], ['maxItems', maxItems],
+                 ['uniqueItems', uniqueItems]];
+  for (const [key, value] of pairs) {
+    if (value !== undefined && value !== null) schema[key] = value;
+  }
+  if (const_ !== undefined) schema.const = const_;
+  if (defaultValue !== undefined) schema.default = defaultValue;
+  return schema;
+}
+
+module.exports = { normalizeTools, tool, Field };