Metadata-Version: 2.4
Name: neutron-os
Version: 1.2.0
Summary: Nuclear facility digital operations platform — extends Axiom
Project-URL: Homepage, https://github.com/UT-Computational-NE/neutron-os-core
Project-URL: Repository, https://github.com/UT-Computational-NE/neutron-os-core
Author-email: Benjamin Booth <bbooth@utexas.edu>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: mcnp,model-registry,nuclear,physics,reactor,simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: axiom-ext-openmc>=0.1.0
Requires-Dist: axiom-os-lm>=0.22.0
Provides-Extra: all
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest-xdist>=3.5; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/b-tree-labs/axiom-os) (domain-agnostic platform framework). NeutronOS adds nuclear-specific knowledge, agents, facility packs, and tools.

[![PyPI](https://img.shields.io/pypi/v/neutron-os)](https://pypi.org/project/neutron-os/)
[![Tests](https://img.shields.io/badge/tests-445%2B-brightgreen)]()
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

## Install

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

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

Verify:

```bash
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](https://github.com/b-tree-labs/axiom-os/blob/main/docs/adrs/adr-018-physics-code-extensions-and-wasm-tier.md) and [ADR-044](https://github.com/b-tree-labs/axiom-os/blob/main/docs/adrs/adr-044-extension-distribution-model.md), 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):**

```bash
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](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:

```bash
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):

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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

```bash
# 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](https://github.com/b-tree-labs/axiom-os) (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](https://pypi.org/project/neutron-os/) on PyPI

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, git practices, and conventions.

## License

Apache 2.0 — see [LICENSE](LICENSE).

## Acknowledgments

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