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
