neutron-os 1.3.1

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

pip install neutron-os

That installs the whole platform: the neut CLI, the Model Corral, Materials Database, Facility Packs, the Experiment Manager, and the Axiom-provided chat / knowledge-retrieval / signal / publishing surfaces. No physics code required — operations tracking, experiment scheduling, the model registry, and knowledge retrieval all work on their own.

Verify:

neut --help                  # NeutronOS CLI
axi doctor                   # environment + dependency check (Axiom-provided)

NeutronOS bundles axiom-os-lm (the Axiom platform) and adds the nuclear-domain layer on top.

Physics codes (optional)

NeutronOS runs transport/physics codes through optional, pluggable adapters — per ADR-018 and ADR-044, each code is its own AEOS-conformant extension, shipped as a pip extra you install only when you run that code. NeutronOS is not tied to any one code; MCNP, MPACT, Serpent and others install the same way (neutron-os[mcnp], …) as their adapters ship.

OpenMC is the reference adapter. Install its extra (the wrapper) plus the native code:

pip install "neutron-os[openmc]"      # the Axiom OpenMC adapter (the extra)
conda install -c conda-forge openmc   # the native physics code; full Python API

Then both surfaces work — and the wrapper is non-shadowing, so plain OpenMC is untouched:

Surface	Command	Notes
Traditional OpenMC	openmc -i geometry.xml, import openmc; openmc.run()	Exactly as the OpenMC docs describe
NeutronOS-routed	neut model run pin-cell --on local:openmc --tail	Adds a live convergence dashboard, signed receipts, federation routing

Prefer Docker to a local OpenMC build? The adapter has a Docker runner (kernel_options={"runner": "docker"} pulls openmc/openmc:latest) — skip the conda step entirely.

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 materials --card 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 materials --card UO2         # Generate MCNP cards
neut model materials --card 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:

axi chat                               # Start interactive session
axi chat --resume                      # Continue last session
axi 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:

axi signal brief                       # Catch up on what happened
axi signal draft                       # Generate weekly changelog
axi signal status                      # Pipeline health
axi 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:

axi pub overview                       # Document ecosystem dashboard
axi pub publish report.md              # Generate + publish
axi pub review report.md               # Interactive review
axi 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. These ship with the Axiom platform and are invoked as axi <noun> (not registered NeutronOS nouns):

Feature	Command	Description
Federation	axi federation	Node identity, peer discovery, trust, .axiompack distribution
RAG	axi rag	Three-tier knowledge corpus (community / org / personal)
Knowledge	axi knowledge	Observatory — velocity, accumulation, impact metrics
Research	axi research	Call to Research — distributed research coordination
Security	axi security	TRIAGE — content verification, anomaly detection
Connections	axi connect	Manage external service credentials
Diagnostics	axi 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)
│       └── 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 (500+)
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

See CHANGELOG.md for full release notes.

Version	Date	Highlights
v1.2.0	2026-05-28	Provenance rule sets (gate controlled/proprietary artifacts before ingest); data-platform multi-site topology (NETL → Rascal → TACC); tracks Axiom 0.22.0
v1.1.0	2026-05-26	Tracks Axiom 0.21.0 (RIVET/TIDY boundary, RACI D6 graduation tier); agent-fleet rename off Pixar names
v1.0.0	2026-05-20	First clean public release after the privacy + release-infrastructure overhaul; Experiment Manager (neut experiment) builtin; GitHub-primary mirror flip
v0.9.1	2026-04-02	Release 1: Model Corral, facility packs, CoreForge bridge, first PyPI publish
v0.x	2026-03	Pre-1.0 materials database + CI alignment (yanked from PyPI; install ≥1.0.0)

Current release: neutron-os v1.2.0 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.