Metadata-Version: 2.4
Name: nerv-cli
Version: 0.1.0
Summary: Nervous Machine CLI — compose/deploy/sync a self-learning causal graph against the deployed NM MCP servers. Orchestration only: the learning math lives server-side and, for devices, in a compiled sha256-pinned kernel artifact. No kernel or framework source ships in this package.
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: anthropic>=0.69
Requires-Dist: python-dotenv>=1.0
Requires-Dist: mcp>=1.0
Dynamic: license-file

# nerv — the Nervous Machine CLI

Compose, deploy, and sync a self-learning causal graph against the **deployed**
Nervous Machine servers. Domain experts write two YAML files; an agent
orchestrates the rest; devices learn autonomously with a compiled kernel.

**Two rules** separate `nerv` from demo-ware:

1. **Call the deployed servers or fail — never fabricate.** No dry-run mode
   that prints plausible numbers. Misconfig/auth → it raises; a tool error →
   the real error surfaces.
2. **The learning math lives server-side.** `nerv` only orchestrates. Device
   deploys receive the kernel as a compiled, sha256-pinned artifact fetched
   with your own credential — never as source. The bundle's loader re-verifies
   the hash and replays a golden trajectory before first use.

## Setup

```sh
pip install nerv-cli
nerv login          # OAuth sign-in with your issued User ID + access key
```

Operators with a static `NM_API_TOKEN` can set it in the environment instead;
`nerv login` is the customer path (tokens cached, auto-refresh, pod-scoped
server-side by your credential).

## The lifecycle

```sh
nerv new my-domain --namespace <your-ns>   # scaffold the no-code kit: yamls + SKILL.md + AUTHORING.md
nerv compose prior my-domain --check-only  # conformance pass, then collaborative composition
nerv compose validation my-domain          # validation pipeline + REQUIRED scale test
nerv deploy my-domain --target pi          # gated bundle: compiled kernel, hash-pinned MANIFEST
nerv sync my-domain --device <bundle-dir>  # consume the device outbox
```

No learning before the calibration slice freezes the measurement scale — the
deploy refuses without a passing scale test, on purpose. On the device,
learning is autonomous (kernel only — no LLM, no network) and queues typed
signals in `results/outbox.jsonl`: `anomaly` (acute) / `curiosity` (chronic) /
`promote` (earned). `sync` is idempotent: `promote` writes back to your pod's
global prior deterministically (dry-run by default; `--apply-promotes`
writes); `curiosity`/`anomaly` become agent proposals for your review.
Patches ship only new low-certainty edges — existing learned state is
verified byte-identical or the deploy refuses.

## Bring your own agent (MCP is the contract)

The deployed MCP servers are the fixed contract; the agent is swappable:

- **Claude Code (recommended interactive):** `--emit claude-code` prints a
  ready `.mcp.json` + prompt + run command. Without `NM_API_TOKEN` set, the
  config is header-free and your client discovers OAuth on first use.
- **Any MCP-capable agent** (Claude Desktop, Cursor, custom): `--emit` prints
  the prompt + server contract to wire in.
- **Headless / CI:** `--agent anthropic` drives Claude's API directly with
  your `ANTHROPIC_API_KEY`.

`introspect` is the observational loop (read-only): per edge it reads live
certainty/weight and judges `validating` / `revised` / `stalled` — "I don't
know yet" over a forced cause. Acting on a hypothesis is the separate
`curiosity`/patch step, additive only.

## Access & license

The CLI is Apache-2.0 (see LICENSE/NOTICE). The servers, the compiled kernel
artifacts, and hosted graph state are separate licensed services — using them
requires credentials issued by Nervous Machine, and every write is fenced to
your pod namespace server-side.

Contact: heidi@everychart.io
