neuralosd 1.0.0__tar.gz

neuralosd-1.0.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: neuralosd
+Version: 1.0.0
+Summary: Deterministic-first agentic runtime — @probe framework, chain runner, meta-selector, HITL guardrails, MCP/OpenAPI exposure, and microVM sandbox backends (BoxLite / Microsandbox)
+Author-email: Hyperspace Technologies <agent@superagent.ng>
+License: MIT
+Keywords: neuralos,agentic,sandbox,microvm,on-device,tool-calling,deterministic,offline,probes
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: model
+Requires-Dist: neuralos>=3.0.3; extra == "model"
+Provides-Extra: boxlite
+Requires-Dist: boxlite>=0.10.0; extra == "boxlite"
+Provides-Extra: msb
+Provides-Extra: data
+Requires-Dist: pydantic>=2; extra == "data"
+Requires-Dist: pymysql; extra == "data"
+Provides-Extra: all
+Requires-Dist: neuralos>=3.0.3; extra == "all"
+Requires-Dist: boxlite>=0.10.0; extra == "all"
+Requires-Dist: pydantic>=2; extra == "all"
+Requires-Dist: pymysql; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+
+# neuralosd — deterministic-first agentic runtime
+
+**One pip install. Two sandbox backends. Any data source. Offline. On CPU.**
+
+`neuralosd` is the agentic runtime for [neuralOS](https://neuralos.ng) — the
+121M-parameter on-device tool-calling model. It turns any data source into a
+private, offline question-answering service inside hardware-isolated microVMs.
+
+```
+pip install neuralosd[all]
+```
+
+## What it does
+
+```
+YOUR DATA (CSV, DB, API, logs)     THE RUNTIME                THE RESULT
+──────────────────────           ──────────────            ──────────────
+profile → model → generate  →   @probe + router    →    ask in English,
+                         →   chains + guardrails     get verified
+                         →   serve + monitor         answers, offline
+```
+
+## Two sandbox backends
+
+| Backend | Install | Best for |
+|---|---|---|
+| **BoxLite** | `pip install neuralosd[boxlite]` | persistent service boxes, CoW clones, port publication |
+| **Microsandbox** | `pip install neuralosd[msb]` | live RAM snapshots, CoW forks, declarative recreate |
+
+Both run the same probe contract. Switch by configuration, not code.
+
+## Quick start
+
+```bash
+# 1. Install
+pip install neuralosd[all]
+
+# 2. Build an instance from your data
+neuralosd build --source your_data.csv --name my-analyst
+
+# 3. Deploy into a sandbox
+neuralosd deploy --name my-analyst --backend boxlite
+
+# 4. Ask
+neuralosd ask --instance my-analyst "how many records"
+```
+
+## The @probe framework
+
+```python
+from neuralosd import probe, Instance
+
+@probe(
+    description="Customers ranked by lifetime spend",
+    triggers=["top customers", "best customers"],
+    args={"limit": {"type": "integer", "min": 1, "max": 25, "default": 10}},
+    pii=["email"],
+)
+def top_customers(limit: int = 10):
+    return db.query("SELECT ... LIMIT %s", (limit,))
+
+inst = Instance(name="my-analyst", probes=[top_customers])
+env = inst.ask("top customers")
+print(env["results"])
+```
+
+## Chains (multi-step answers)
+
+```python
+from neuralosd import chain, ChainRunner
+
+@chain(name="genre_deep_dive", steps=[
+    {"probe": "top_genres"},
+    {"probe": "tracks_by_genre", "args": {"genre": "{{step_0.genre}}"}},
+])
+def genre_deep_dive(ctx): ...
+
+runner = ChainRunner(probes_by_name)
+runner.register("genre_deep_dive", genre_deep_dive._chain_steps)
+result = runner.run("genre_deep_dive")
+```
+
+## Meta-selector (multi-instance routing)
+
+```python
+from neuralosd import MetaSelector
+
+selector = MetaSelector({
+    "finance": {"description": "revenue, invoices, customers"},
+    "ops":     {"description": "incidents, uptime, alerts"},
+})
+instance = selector.route("how many open incidents")  # → "ops"
+```
+
+## HITL guardrails
+
+```python
+from neuralosd import ConfirmStore
+store = ConfirmStore()
+pending = store.create(probe_fn, args, reason="low confidence")
+# ... human confirms ...
+result = store.confirm(pending["confirm_token"])
+```
+
+## MCP server (expose probes to any AI agent)
+
+```bash
+python3 -m neuralosd.mcp /path/to/instance
+# or add to Claude Desktop / Cursor MCP config
+```
+
+## License
+
+MIT

neuralosd-1.0.0/README.md

@@ -0,0 +1,114 @@
+# neuralosd — deterministic-first agentic runtime
+
+**One pip install. Two sandbox backends. Any data source. Offline. On CPU.**
+
+`neuralosd` is the agentic runtime for [neuralOS](https://neuralos.ng) — the
+121M-parameter on-device tool-calling model. It turns any data source into a
+private, offline question-answering service inside hardware-isolated microVMs.
+
+```
+pip install neuralosd[all]
+```
+
+## What it does
+
+```
+YOUR DATA (CSV, DB, API, logs)     THE RUNTIME                THE RESULT
+──────────────────────           ──────────────            ──────────────
+profile → model → generate  →   @probe + router    →    ask in English,
+                         →   chains + guardrails     get verified
+                         →   serve + monitor         answers, offline
+```
+
+## Two sandbox backends
+
+| Backend | Install | Best for |
+|---|---|---|
+| **BoxLite** | `pip install neuralosd[boxlite]` | persistent service boxes, CoW clones, port publication |
+| **Microsandbox** | `pip install neuralosd[msb]` | live RAM snapshots, CoW forks, declarative recreate |
+
+Both run the same probe contract. Switch by configuration, not code.
+
+## Quick start
+
+```bash
+# 1. Install
+pip install neuralosd[all]
+
+# 2. Build an instance from your data
+neuralosd build --source your_data.csv --name my-analyst
+
+# 3. Deploy into a sandbox
+neuralosd deploy --name my-analyst --backend boxlite
+
+# 4. Ask
+neuralosd ask --instance my-analyst "how many records"
+```
+
+## The @probe framework
+
+```python
+from neuralosd import probe, Instance
+
+@probe(
+    description="Customers ranked by lifetime spend",
+    triggers=["top customers", "best customers"],
+    args={"limit": {"type": "integer", "min": 1, "max": 25, "default": 10}},
+    pii=["email"],
+)
+def top_customers(limit: int = 10):
+    return db.query("SELECT ... LIMIT %s", (limit,))
+
+inst = Instance(name="my-analyst", probes=[top_customers])
+env = inst.ask("top customers")
+print(env["results"])
+```
+
+## Chains (multi-step answers)
+
+```python
+from neuralosd import chain, ChainRunner
+
+@chain(name="genre_deep_dive", steps=[
+    {"probe": "top_genres"},
+    {"probe": "tracks_by_genre", "args": {"genre": "{{step_0.genre}}"}},
+])
+def genre_deep_dive(ctx): ...
+
+runner = ChainRunner(probes_by_name)
+runner.register("genre_deep_dive", genre_deep_dive._chain_steps)
+result = runner.run("genre_deep_dive")
+```
+
+## Meta-selector (multi-instance routing)
+
+```python
+from neuralosd import MetaSelector
+
+selector = MetaSelector({
+    "finance": {"description": "revenue, invoices, customers"},
+    "ops":     {"description": "incidents, uptime, alerts"},
+})
+instance = selector.route("how many open incidents")  # → "ops"
+```
+
+## HITL guardrails
+
+```python
+from neuralosd import ConfirmStore
+store = ConfirmStore()
+pending = store.create(probe_fn, args, reason="low confidence")
+# ... human confirms ...
+result = store.confirm(pending["confirm_token"])
+```
+
+## MCP server (expose probes to any AI agent)
+
+```bash
+python3 -m neuralosd.mcp /path/to/instance
+# or add to Claude Desktop / Cursor MCP config
+```
+
+## License
+
+MIT

neuralosd-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neuralosd"
+version = "1.0.0"
+description = "Deterministic-first agentic runtime — @probe framework, chain runner, meta-selector, HITL guardrails, MCP/OpenAPI exposure, and microVM sandbox backends (BoxLite / Microsandbox)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Hyperspace Technologies", email = "agent@superagent.ng" }]
+keywords = ["neuralos", "agentic", "sandbox", "microvm", "on-device",
+            "tool-calling", "deterministic", "offline", "probes"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.scripts]
+neuralosd = "neuralosd.cli:main"
+
+[project.optional-dependencies]
+model = ["neuralos>=3.0.3"]
+boxlite = ["boxlite>=0.10.0"]
+msb = []
+data = ["pydantic>=2", "pymysql"]
+all = ["neuralos>=3.0.3", "boxlite>=0.10.0", "pydantic>=2", "pymysql"]
+dev = ["pytest", "pytest-asyncio"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

neuralosd-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neuralosd-1.0.0/src/neuralosd/__init__.py

@@ -0,0 +1,24 @@
+"""neuralosd — deterministic-first agentic runtime for neuralOS.
+
+One pip install. Two sandbox backends (BoxLite, Microsandbox). Any data
+source. Offline. On CPU. With verification gates, audit trail, and
+deterministic routing.
+"""
+__version__ = "1.0.0"
+
+from .probe import probe, enum_arg, pattern_arg, int_arg, ProbeMeta
+from .router import Router, NoResults
+from .instance import Instance
+from .chains import ChainRunner, chain, ChainError
+from .meta import MetaSelector
+from .hitl import ConfirmStore, ConfirmRequired
+from .lint import TriggerLinter
+
+__all__ = [
+    "probe", "enum_arg", "pattern_arg", "int_arg", "ProbeMeta",
+    "Router", "NoResults", "Instance",
+    "ChainRunner", "chain", "ChainError",
+    "MetaSelector",
+    "ConfirmStore", "ConfirmRequired",
+    "TriggerLinter",
+]

neuralosd-1.0.0/src/neuralosd/_cmd/ask.py

@@ -0,0 +1,7 @@
+import os, sys, json
+def run(a):
+    d = os.path.abspath(a.instance_dir)
+    os.chdir(d); sys.path.insert(0, d)
+    import ask
+    sys.argv = ["ask.py"] + [a.question] if hasattr(a, 'question') else sys.argv
+    ask.main() if hasattr(ask, 'main') else None

neuralosd-1.0.0/src/neuralosd/_cmd/calibrate.py

@@ -0,0 +1,13 @@
+def run(a):
+    import sys, subprocess, os
+    script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                          "..", "tools", "calibrate.py")
+    if not os.path.exists(script):
+        script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              "..", "..", "..",
+                              "agent-skills", "skills", "neuralos", "scripts",
+                              "calibrate.py")
+    if os.path.exists(script):
+        raise SystemExit(subprocess.call([sys.executable, script] + sys.argv[1:]))
+    print(f"tool script not found: {script}")
+    raise SystemExit(1)

neuralosd-1.0.0/src/neuralosd/_cmd/diff.py

@@ -0,0 +1,13 @@
+def run(a):
+    import sys, subprocess, os
+    script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                          "..", "tools", "diff.py")
+    if not os.path.exists(script):
+        script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              "..", "..", "..",
+                              "agent-skills", "skills", "neuralos", "scripts",
+                              "diff.py")
+    if os.path.exists(script):
+        raise SystemExit(subprocess.call([sys.executable, script] + sys.argv[1:]))
+    print(f"tool script not found: {script}")
+    raise SystemExit(1)

neuralosd-1.0.0/src/neuralosd/_cmd/gaps.py

@@ -0,0 +1,13 @@
+def run(a):
+    import sys, subprocess, os
+    script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                          "..", "tools", "gaps.py")
+    if not os.path.exists(script):
+        script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              "..", "..", "..",
+                              "agent-skills", "skills", "neuralos", "scripts",
+                              "gaps.py")
+    if os.path.exists(script):
+        raise SystemExit(subprocess.call([sys.executable, script] + sys.argv[1:]))
+    print(f"tool script not found: {script}")
+    raise SystemExit(1)

neuralosd-1.0.0/src/neuralosd/_cmd/golden.py

@@ -0,0 +1,13 @@
+def run(a):
+    import sys, subprocess, os
+    script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                          "..", "tools", "golden.py")
+    if not os.path.exists(script):
+        script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              "..", "..", "..",
+                              "agent-skills", "skills", "neuralos", "scripts",
+                              "golden.py")
+    if os.path.exists(script):
+        raise SystemExit(subprocess.call([sys.executable, script] + sys.argv[1:]))
+    print(f"tool script not found: {script}")
+    raise SystemExit(1)

neuralosd-1.0.0/src/neuralosd/_cmd/init.py

@@ -0,0 +1,21 @@
+def run(a):
+    import subprocess, sys, os
+    out = a.out or f"./{a.name}"
+    scripts = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                           "..", "..", "..", "..",
+                           "agent-skills", "skills", "neuralos", "scripts")
+    profile = os.path.join(out, "profile.json")
+    os.makedirs(out, exist_ok=True)
+    for step in [
+        [sys.executable, os.path.join(scripts, "profile_data.py"),
+         "--source", a.source, "--out", profile],
+        [sys.executable, os.path.join(scripts, "gen_pydantic.py"),
+         "--profile", profile, "--out", os.path.join(out, "models.py")],
+        [sys.executable, os.path.join(scripts, "gen_needle_instance.py"),
+         "--profile", profile, "--models", os.path.join(out, "models.py"),
+         "--out", out, "--agent-name", a.name],
+    ]:
+        r = subprocess.run(step, capture_output=True, text=True)
+        if r.returncode:
+            print(r.stderr[-500:]); raise SystemExit(r.returncode)
+    print(f"instance '{a.name}' generated at {out}")

neuralosd-1.0.0/src/neuralosd/_cmd/invariants.py

@@ -0,0 +1,13 @@
+def run(a):
+    import sys, subprocess, os
+    script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                          "..", "tools", "invariants.py")
+    if not os.path.exists(script):
+        script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              "..", "..", "..",
+                              "agent-skills", "skills", "neuralos", "scripts",
+                              "invariants.py")
+    if os.path.exists(script):
+        raise SystemExit(subprocess.call([sys.executable, script] + sys.argv[1:]))
+    print(f"tool script not found: {script}")
+    raise SystemExit(1)

neuralosd-1.0.0/src/neuralosd/_cmd/lint.py

@@ -0,0 +1,8 @@
+import json, sys
+def run(a):
+    from neuralosd.lint import TriggerLinter
+    menu = json.load(open(a.menu))
+    r = TriggerLinter(menu, top=a.top).lint()
+    for h in r["hard"]: print(f"HARD {h}")
+    for s in r["soft"]: print(f"soft {s}")
+    raise SystemExit(1 if r["hard"] else 0)

neuralosd-1.0.0/src/neuralosd/_cmd/openapi.py

@@ -0,0 +1,13 @@
+def run(a):
+    import sys, subprocess, os
+    script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                          "..", "tools", "openapi.py")
+    if not os.path.exists(script):
+        script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              "..", "..", "..",
+                              "agent-skills", "skills", "neuralos", "scripts",
+                              "openapi.py")
+    if os.path.exists(script):
+        raise SystemExit(subprocess.call([sys.executable, script] + sys.argv[1:]))
+    print(f"tool script not found: {script}")
+    raise SystemExit(1)

neuralosd-1.0.0/src/neuralosd/_cmd/serve.py

@@ -0,0 +1,5 @@
+import os, sys
+def run(a):
+    d = os.path.abspath(a.instance_dir)
+    os.chdir(d); sys.path.insert(0, d)
+    import serve; serve.main()

neuralosd-1.0.0/src/neuralosd/_cmd/truth.py

@@ -0,0 +1,13 @@
+def run(a):
+    import sys, subprocess, os
+    script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                          "..", "tools", "truth.py")
+    if not os.path.exists(script):
+        script = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              "..", "..", "..",
+                              "agent-skills", "skills", "neuralos", "scripts",
+                              "truth.py")
+    if os.path.exists(script):
+        raise SystemExit(subprocess.call([sys.executable, script] + sys.argv[1:]))
+    print(f"tool script not found: {script}")
+    raise SystemExit(1)

neuralosd-1.0.0/src/neuralosd/adapters.py

@@ -0,0 +1,54 @@
+"""Sandbox adapters — route probe execution to BoxLite / MSB sandboxes.
+
+An adapter implements the same interface as an in-process probe: takes
+kwargs, returns a result dict. The instance's tier declaration routes
+execution to the right substrate.
+"""
+import json
+import urllib.request
+from typing import Any, Dict
+
+
+class BoxLiteAdapter:
+    """Executes probes inside a BoxLite box via `boxlite serve` REST."""
+
+    def __init__(self, serve_url: str = "http://localhost:8100",
+                 api_key: str = None, box_name: str = "chinook-1gb"):
+        self.serve_url = serve_url.rstrip("/")
+        self.api_key = api_key
+        self.box_name = box_name
+
+    def exec_probe(self, code: str) -> Dict:
+        """Run a Python snippet inside the sandbox."""
+        req = urllib.request.Request(
+            f"{self.serve_url}/v1/boxes/{self.box_name}/exec",
+            data=json.dumps({"command": code}).encode(),
+            headers={"Content-Type": "application/json",
+                     **({"Authorization": f"Bearer {self.api_key}"}
+                        if self.api_key else {})})
+        r = urllib.request.urlopen(req, timeout=120)
+        return json.loads(r.read())
+
+
+class MSBAdapter:
+    """Executes probes inside a Microsandbox via `msb exec`."""
+
+    def __init__(self, sandbox_name: str = "chinook-ms"):
+        self.sandbox_name = sandbox_name
+
+    def exec_probe(self, code: str) -> Dict:
+        import subprocess
+        r = subprocess.run(
+            ["msb", "exec", self.sandbox_name, "--", "python3", "-c", code],
+            capture_output=True, text=True, timeout=120)
+        return {"stdout": r.stdout, "stderr": r.stderr,
+                "exit_code": r.returncode}
+
+
+def get_adapter(tier: str, **kwargs) -> Any:
+    """Factory: tier string → adapter instance, or None for in-process."""
+    if tier.startswith("sandbox:boxlite:"):
+        return BoxLiteAdapter(box_name=tier.split(":")[-1], **kwargs)
+    if tier.startswith("sandbox:msb:"):
+        return MSBAdapter(sandbox_name=tier.split(":")[-1], **kwargs)
+    return None   # in-process

neuralosd-1.0.0/src/neuralosd/backends/__init__.py

@@ -0,0 +1,15 @@
+from .boxlite_backend import BoxLiteBackend
+from .msb_backend import MSBBackend
+
+
+def get_backend(name: str, **kwargs):
+    if name == "boxlite":
+        return BoxLiteBackend(**kwargs)
+    if name == "msb":
+        return MSBBackend(**kwargs)
+    raise ValueError(f"unknown backend: {name}")
+
+
+def available_backends():
+    return {"boxlite": BoxLiteBackend.available(),
+            "msb": MSBBackend.available()}

neuralosd-1.0.0/src/neuralosd/backends/boxlite_backend.py

@@ -0,0 +1,69 @@
+"""BoxLite backend — lifecycle management for BoxLite microVM boxes."""
+import asyncio
+from typing import Any, Dict, Optional
+
+
+class BoxLiteBackend:
+    """Manages BoxLite box lifecycle for neuralOS instances."""
+
+    def __init__(self, serve_url: str = None, api_key: str = None):
+        self.serve_url = serve_url
+        self.api_key = api_key
+
+    def _rt(self):
+        import boxlite
+        if self.serve_url:
+            cred = boxlite.ApiKeyCredential(self.api_key) if self.api_key else None
+            return boxlite.Boxlite.rest(
+                boxlite.BoxliteRestOptions(url=self.serve_url, credential=cred))
+        return boxlite.Boxlite.default()
+
+    async def create(self, name: str, image: str = "python:3.12-slim",
+                     cpus: int = 1, memory_mib: int = 1024,
+                     disk_gb: int = 6, **kwargs):
+        rt = self._rt()
+        got = await rt.get_or_create(
+            boxlite.BoxOptions(image=image, auto_delete=0,
+                               cpus=cpus, memory_mib=memory_mib,
+                               disk_size_gb=disk_gb, **kwargs),
+            name=name)
+        return got[0] if isinstance(got, tuple) else got
+
+    async def start(self, name: str):
+        box = await self._rt().get(name)
+        await box.start()
+
+    async def stop(self, name: str):
+        box = await self._rt().get(name)
+        await box.stop()
+
+    async def remove(self, name: str):
+        await self._rt().remove(name)
+
+    async def fork(self, template: str, name: str):
+        tpl = await self._rt().get(template)
+        return await tpl.clone_box(name=name)
+
+    async def exec(self, name: str, cmd: str, args: list = None):
+        box = await self._rt().get(name)
+        ex = await box.exec(cmd, args or [], timeout_secs=300)
+        out = []
+        async for line in ex.stdout(): out.append(line)
+        await ex.wait()
+        return "".join(out)
+
+    async def export(self, name: str, dest: str):
+        box = await self._rt().get(name)
+        await box.export(dest=dest)
+
+    @staticmethod
+    def available() -> bool:
+        try:
+            import boxlite
+            return True
+        except ImportError:
+            return False
+
+    @staticmethod
+    def name() -> str:
+        return "boxlite"