neutron-os 1.1.0

Nuclear facility digital operations platform — extends Axiom

NeutronOS

Nuclear Energy Unified Technology for Research, Operations & Networks

A modular digital platform for nuclear facilities that unifies model management, operations tracking, signal analysis, and knowledge retrieval — replacing fragmented workflows (paper logs, spreadsheets, phone calls) with integrated digital tools.

Built on top of Axiom (domain-agnostic platform framework). NeutronOS adds nuclear-specific knowledge, agents, facility packs, and tools.

Install

Two commands take you from a clean Mac/Linux laptop to a fully working install:

conda install -c conda-forge openmc
pip install neutron-os

Verify:

neut --help                  # NeutronOS CLI
neut doctor                  # environment + dependency check
openmc --version             # OpenMC CLI (traditional surface, unchanged)
python -c "import openmc"    # OpenMC Python API (unchanged)

The first command installs the OpenMC physics code natively (the maintained build from conda-forge — fastest at runtime, full Python API). The second installs NeutronOS, which bundles axiom-os-lm (the Axiom platform) and axiom-ext-openmc (the Axiom adapter that wraps OpenMC). Per ADR-018 and ADR-044, each physics code is its own AEOS-conformant standalone extension; bundling them as NeutronOS deps makes pip install neutron-os the single integration step.

Two surfaces for OpenMC after install:

Surface	Command	Notes
Traditional OpenMC	openmc -i geometry.xml, import openmc; openmc.run()	Unchanged — works exactly as the OpenMC docs describe. The wrapper is non-shadowing.
NeutronOS-routed	neut model run pin-cell --on local:openmc --tail	Bonus path: live convergence dashboard, signed receipts, federation routing

If Docker is preferred over a local OpenMC install, the wrapper has a Docker runner: kernel_options={"runner": "docker"} pulls openmc/openmc:latest and dispatches into it. Skip the conda step and run with Docker only.

From source (developer install):

git clone https://rsicc-gitlab.tacc.utexas.edu/ut-computational-ne/neutron-os-core.git
cd neutron-os-core
pip install -e ".[all]"

# Or use the bootstrap script (creates venv, installs, sets up direnv)
./scripts/bootstrap.sh

See CONTRIBUTING.md for detailed setup. The first-day install walkthrough with troubleshooting lives at docs/guides/first-day-openmc-install.md.

What NeutronOS Does

NeutronOS ships nuclear-domain builtins; the AXI orchestrator, chat, signal, and publishing surfaces are provided by the underlying Axiom platform.

Researcher / Operator
    |
    v
neut model ──> Physics model registry (Model Corral)
    |             init, validate, add, search, generate, review, share...
    |
neut facility ──> Facility packs (NETL-TRIGA, MSRE, PWR-generic)
    |               Materials database, configurations, procedures
    |
neut experiment ──> Experiment Manager (neut exp) — sample lifecycle
    |
neut demo ──> Guided walkthroughs

  + Axiom-provided surfaces (chat assistant, signal pipeline, document
    publishing) layered on top via the Axiom platform.

Key Capabilities

Model Corral (24 CLI commands)

Physics model registry with auto-detection, validation, material generation, and collaboration:

neut model add ./input.i               # Auto-detect code type (MCNP, MPACT, etc.)
neut model validate ./input.i           # Validate model file
neut model search --code mcnp           # Search by code type
neut model list                         # Browse registered models
neut model generate --material UO2      # Generate MCNP/MPACT material cards
neut model materials                    # List verified materials (11 compositions)
neut model review <id>                  # Start collaborative review
neut model share <id>                   # Share via federation

All commands support --json. Full list: init, validate, add, clone, search, list, show, pull, lineage, diff, export, audit, generate, lint, sweep, materials, share, receive, review, reviews, resolve, invite, contributors, status.

Materials Database

11 verified compositions from authoritative references (PNNL-15870, GA-4314, NUREG/CR-6698):

neut model materials                    # List all materials
neut model generate --material UO2      # Generate MCNP cards
neut model generate --material Zircaloy-4 --format mpact  # MPACT format

MaterialSource protocol with 5 sources and priority merging. Deterministic MCNP/MPACT card generation.

Facility Packs

Pre-built knowledge bundles for specific reactor types:

neut facility list                      # Available packs
neut facility install NETL-TRIGA        # Install a facility pack
neut facility show NETL-TRIGA           # Pack details
neut facility materials NETL-TRIGA      # Facility-specific materials
neut facility sync                      # Sync with upstream

Shipped packs: NETL-TRIGA, MSRE, PWR-generic. Each includes materials, configurations, and domain knowledge.

Interactive Chat (Axiom-provided)

Chat is provided by Axiom's AXI orchestrator, not a NeutronOS builtin. NeutronOS contributes the nuclear knowledge, materials database, and facility grounding.

Nuclear engineering assistant with tool calling and RAG grounding:

neut chat                              # Start interactive session
neut chat --resume                     # Continue last session
neut chat --simple                     # Read-only mode (no writes)

The assistant has access to the materials database, model registry, and facility knowledge. When asked about material compositions, it uses verified database values — never training data.

Signal Pipeline (Axiom-provided)

Signal ingestion is provided by Axiom's SCAN agent; there is no neut signal noun registered in NeutronOS today.

Proactive program awareness — ingest signals from multiple sources:

neut signal brief                      # Catch up on what happened
neut signal draft                      # Generate weekly changelog
neut signal status                     # Pipeline health
neut signal watch                      # Watch for new signals

Sources: voice memos, Microsoft Teams, GitLab, freetext. Extracts: decisions, action items, risks, blockers, deadlines, people mentions, technical concepts.

Document Publishing (Axiom-provided)

Document publishing is provided by Axiom's PRESS agent; there is no neut pub noun registered in NeutronOS today.

Markdown to DOCX lifecycle with review gates:

neut pub overview                      # Document ecosystem dashboard
neut pub publish report.md             # Generate + publish
neut pub review report.md              # Interactive review
neut pub status                        # Document status

CoreForge Bridge

Integration with CoreForge neutronics tools for MCNP model workflows.

Platform Features (via Axiom)

NeutronOS inherits all Axiom platform capabilities:

Feature	Command	Description
Federation	neut federation	Node identity, peer discovery, trust, .axiompack distribution
RAG	neut rag	Three-tier knowledge corpus (community / org / personal)
Knowledge	neut knowledge	Observatory — velocity, accumulation, impact metrics
Research	neut research	Call to Research — distributed research coordination
Security	neut security	TRIAGE — content verification, anomaly detection
Connections	neut connect	Manage external service credentials
Diagnostics	neut doctor	TRIAGE — AI-powered environment health checks

Repository Structure

Neutron_OS/
├── src/neutron_os/           # Python package root
│   ├── cli.py                #   CLI entry point
│   └── extensions/builtins/  #   Builtin extensions
│       ├── model_corral/     #     Model Corral (neut model, neut facility)
│       ├── expman/           #     Experiment Manager (neut experiment / neut exp)
│       ├── rag_grounding/    #     RAG grounding hooks + connect presets
│       └── demo/             #     Guided walkthroughs (neut demo)
├── runtime/                  # Instance data (config, inbox, sessions)
├── tests/                    # Cross-cutting tests
├── docs/                     # PRDs, tech specs, ADRs
├── infra/                    # Deployment configs (K3D, Docker)
├── scripts/                  # Bootstrap and install scripts
└── pyproject.toml            # Package definition

The agent fleet (AXI/SCAN/TIDY/RIVET/TRIAGE/PRESS/CURIO/…), gateway/orchestrator, and shared infra helpers (axiom.infra.*) are provided by Axiom, not this repo.

Development

# Run all tests (445+)
make test

# Run specific suites
pytest tests/ -v                                # Cross-cutting
pytest src/neutron_os/extensions/builtins/model_corral/tests/ -v  # Model Corral
pytest -m "not integration"                     # Unit only (runs as pre-push hook)

# Lint (must pass before push)
ruff check src/ tests/
ruff format src/ tests/

# Build
make build

Tech Stack

Layer	Technology
CLI & Agents	Python (argparse, rich, prompt-toolkit)
LLM Gateway	Model-agnostic (Anthropic, OpenAI, Qwen, any OpenAI-compatible)
Database	PostgreSQL + pgvector
RAG	pgvector embeddings, hybrid vector+full-text search
Infrastructure	K3D (local), Docker Compose (fallback)
CI/CD	GitLab CI
Packaging	Hatchling (pip install neutron-os)
Platform	Axiom (axiom-os-lm)

Design Principles

• Reactor-agnostic core with facility-specific configuration via packs
• Offline-first — queue locally, sync on restore
• Human-in-the-loop for all writes in safety-adjacent contexts
• No vendor lock-in — model-agnostic, cloud-agnostic, IDE-agnostic
• Provider pattern — swap implementations via config, not code changes
• Federation-native — every node is sovereign; invite = join as peer, not shared DB user

Releases

Version	Date	Highlights
v0.9.1	2026-04-02	Release 1 (Nick + Cole): Model Corral, facility packs, CoreForge bridge, PyPI publish
v0.8.x	2026-03	Materials database, TIDY steward, CI alignment
v0.7.x	2026-03	Signal pipeline, document publisher, Rascal deployment

Current release: neutron-os v0.9.1 on PyPI

Contributing

See CONTRIBUTING.md for development workflow, git practices, and conventions.

License

Apache 2.0 — see LICENSE.

Acknowledgments

Developed at The University of Texas at Austin, Department of Mechanical Engineering — Nuclear & Radiation Engineering Program.