nous

What this is

nous is a simulation-based digital twin of an edge-AI inference appliance: the man-portable, backpack-class kind of device that supports a single operator working in disconnected or contested environments. It runs the appliance's physics as a virtual model in software. There is no hardware in the loop and no live telemetry feed, so in the digital-twin taxonomy it is a digital model, not a unit bidirectionally synced to a physical device (see LIMITATIONS.md). The modelled appliance pairs a Jetson-class compute module with battery, solar/fuel-cell auxiliary power, a thermal envelope, environmental and biometric sensors, multi-mode radios, and a local-plus-cloud inference path. The twin runs the device end-to-end as a tick-driven asynchronous system that exposes itself to a controller (a Claude session or any MCP client) through the Model Context Protocol.

The point is to make the behaviour of an edge-AI unit legible: which capabilities are intact right now, which have degraded, how long the device can sustain a given workload, and what an estimator can honestly say about the operator and the environment. To that end every subsystem has a parametric physics model, a sensor model that emits noisy observations, and a recursive estimator (a Kalman filter sized to the subsystem, or a particle filter for the discrete comms link state) that turns those observations back into a calibrated belief state. A self-model layer aggregates those beliefs into capability claims the controller can reason about.

The codebase is meant to be small and easy to inspect. It is not a wrapper around a commercial sim; it is a deliberate, opinionated reimplementation of just enough physics, control, and standards-interop to support useful conversations with a controller. Every numeric curve lives in a hardware profile YAML so the same engine can be retargeted to a new device (Jetson AGX Orin 64GB is the reference profile). NATO and open-standard adapters (CoT/TAK, SensorThings, MISB KLV, NMEA 0183, STANAG 4774, MQTT) provide the seams for plugging the modelled unit into mission stacks.

Status

Pre-1.0. The L0 scaffold (layout, audited MCP tool surface, FSM, engine tick loop, hardware-profile loader, policy/audit/runner spine) is in place. The L1 subsystem rollout (power, APU, thermal, compute, inference, storage, comms, position, sensors, biometrics) and their estimators are landed on main with passing tests; the interop adapters (CoT, SensorThings, MISB KLV, NMEA, STANAG, MQTT) now emit standards-shaped output. The self-model layer aggregates the live estimators into calibrated capability claims (BL-018, BL-035). See STATUS.md for the phase table and the per-component maturity ledger, LIMITATIONS.md for the explicit gaps, docs/backlog.md for the line-item tracker, and docs/audit-2026-06-14b.md for the most recent point-in-time audit (full code index, validation against the conformance documents, and the live-MCP probe). The audit cadence and the regression-pin pattern are codified in ADR 0023.

Layout

src/nous/        engine, server, policy/audit/runner, subsystems, estimators,
                 self-model, interop adapters, OAuth issuer, scenarios loader
profiles/        hardware profile YAML (jetson-agx-orin reference, others)
scenarios/       scripted scenario YAML for replayable runs
skills/          short markdown runbooks for the controller
docs/            architecture, ADRs, STPA artefacts, conformance posture,
                 model cards, hardware-profile reference, deployment guide
deploy/          systemd units, Caddy template, cloud-init, install script
alembic/         database migrations (SQLite + WAL by default)
tests/           unit, integration, and stdio end-to-end tests
scripts/         autogen helpers for tool reference, ADR index, backlog
examples/        a self-driving demo, an inspector quickstart

Capabilities

• Tick-loop physics simulation of an edge-AI inference appliance (man-portable, backpack-class), with subsystem models for compute, power, auxiliary power (battery, solar, fuel cell), thermal, storage, sensors, position, biometrics, comms, and inference, all driven by a single hardware-profile YAML.
• Hand-rolled finite-state machine over the mission posture (stowed, boot, idle, mission, relay, monitoring, C2, degraded, thermal-limited, low-power, safe, shutdown, fault) with explicit transitions.
• Recursive estimators per subsystem (per-channel Kalman filters, plus a particle filter for the comms link state) feeding a self-model capability layer that produces calibrated endurance, thermal-headroom, inference-capacity, and link-budget claims.
• A FastMCP tool surface exposed over stdio or HTTP with OAuth 2.1, with every tool call classified into a tier (read-only, reversible, stateful, irreversible) and gated by policy mode.
• An append-only JSONL audit trail (output hashed, never stored verbatim) and a Claude/Anthropic client with a hard daily call cap and explicit prompt-cache discipline.
• Interop adapters for the standards a mission stack expects: CoT/TAK, OGC SensorThings, MISB KLV, NMEA 0183, STANAG 4774/4778, and MQTT.
• A VM deployment bundle (Ubuntu 26.04 LTS + systemd + Caddy + logrotate; also works on 24.04) and an examples/self_driving_demo.py for running the twin with a Claude session as the controller.

Install

nous builds with uv and Python 3.12+ (the deployment baseline is 3.14 on Ubuntu 26.04 LTS; 3.12 and 3.13 are still supported).

git clone https://github.com/rmednitzer/nous
cd nous
uv sync --all-extras

Once installed, nous --help lists the CLI subcommands (serve, tick, scenario).

Build and test

make install     # uv sync --all-extras
make check       # ruff + mypy strict + pytest
make docs-build  # mkdocs build --strict

Run it

uv run nous serve              # MCP server on stdio (default)
NOUS_TRANSPORT=http uv run nous serve   # HTTP transport with OAuth
uv run nous scenario scenarios/env-monitoring-urban.yaml

examples/self_driving_demo.py wires Claude to the stdio transport for a short end-to-end demo. Pair it with the runbooks in skills/ for a guided tour.

Cross-references

• STATUS.md -- maturity by phase and per-document state
• LIMITATIONS.md -- explicit boundaries (single operator, no hardware in the loop, linear-Gaussian estimators, etc.)
• docs/backlog.md -- BL-NNN line-item tracker
• docs/adr/ -- numbered architecture decision records
• docs/stpa/ -- STPA-Pro safety analysis artefacts
• AGENTS.md -- conventions for AI-assisted contributors
• CONTRIBUTING.md -- how to land changes
• SECURITY.md -- reporting and hardening posture

Live deployment

A single-VM reference instance tracks main automatically; every merged PR reaches it within five minutes (docs/deployment.md). The public face of the project is the showcase under docs/showcase/; the live VM itself remains private and CIDR-gated (ADR 0017).

License

Apache-2.0. See LICENSE and NOTICE. Source files are SPDX-tagged where appropriate; REUSE.toml declares the project-wide license posture for REUSE 3.x compliance.