Metadata-Version: 2.5
Name: neutron-os
Version: 1.17.12
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-os-lm[chat,mcp]>=0.70.24
Requires-Dist: jsonschema>=4.21
Provides-Extra: all
Requires-Dist: axiom-ext-openmc>=0.1.0; extra == 'all'
Requires-Dist: epicscorelibs>=7.0.7; extra == 'all'
Requires-Dist: hypothesis>=6.0; extra == 'all'
Requires-Dist: jupytext>=1.16; extra == 'all'
Requires-Dist: markdown-it-py>=3; extra == 'all'
Requires-Dist: nbformat>=5.9; extra == 'all'
Requires-Dist: nptdms>=1.9; extra == 'all'
Requires-Dist: pillow; extra == 'all'
Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
Requires-Dist: pyepics>=3.5; extra == 'all'
Requires-Dist: pyserial>=3.5; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest-postgresql>=6.0; extra == 'all'
Requires-Dist: pytest-testmon>=2.1; extra == 'all'
Requires-Dist: pytest-xdist>=3.5; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Requires-Dist: scipy>=1.11; extra == 'all'
Requires-Dist: websockets>=12; extra == 'all'
Provides-Extra: daq-epics
Requires-Dist: epicscorelibs>=7.0.7; extra == 'daq-epics'
Requires-Dist: pyepics>=3.5; extra == 'daq-epics'
Provides-Extra: daq-mat
Requires-Dist: scipy>=1.11; extra == 'daq-mat'
Provides-Extra: daq-serial
Requires-Dist: pyserial>=3.5; extra == 'daq-serial'
Provides-Extra: daq-tdms
Requires-Dist: nptdms>=1.9; extra == 'daq-tdms'
Provides-Extra: daq-ws
Requires-Dist: websockets>=12; extra == 'daq-ws'
Provides-Extra: dev
Requires-Dist: epicscorelibs>=7.0.7; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: markdown-it-py>=3; extra == 'dev'
Requires-Dist: nptdms>=1.9; extra == 'dev'
Requires-Dist: pillow; extra == 'dev'
Requires-Dist: pyepics>=3.5; extra == 'dev'
Requires-Dist: pyserial>=3.5; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-postgresql>=6.0; extra == 'dev'
Requires-Dist: pytest-testmon>=2.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: scipy>=1.11; extra == 'dev'
Requires-Dist: websockets>=12; extra == 'dev'
Provides-Extra: guide
Requires-Dist: markdown-it-py>=3; extra == 'guide'
Provides-Extra: notebook
Requires-Dist: jupytext>=1.16; extra == 'notebook'
Requires-Dist: nbformat>=5.9; extra == 'notebook'
Provides-Extra: openmc
Requires-Dist: axiom-ext-openmc>=0.1.0; extra == 'openmc'
Provides-Extra: telemetry
Requires-Dist: psycopg[binary]>=3.1; extra == 'telemetry'
Description-Content-Type: text/markdown

# NeutronOS

NeutronOS is the nuclear-facility layer. One command, `neut`. Each capability is an extension, and the extension's `axiom-extension.toml` is what the CLI loads.

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

## Install

```bash
pip install neutron-os
neut --help
```

That install is the CLI, the builtin extensions below, and the platform package they run on (`axiom-os-lm`). Physics codes are extras. OpenMC is the one that ships:

```bash
pip install "neutron-os[openmc]"
```

`neut model run` is the NeutronOS path. Plain `openmc` is unchanged.

From a checkout: `pip install -e ".[all]"`, or `./scripts/bootstrap.sh`. Setup detail is [CONTRIBUTING.md](CONTRIBUTING.md).

## What a command is

A noun is an extension. The manifest names the noun, the kind, and the entry point. `neut` dispatches to that entry. The same manifest is how an agent finds a tool.

```mermaid
flowchart TB
  person[Person or agent] --> neut[neut]
  neut --> manifest["axiom-extension.toml"]
  manifest --> cmd["kind: cmd"]
  manifest --> tool["kind: tool"]
  manifest --> service["kind: service"]
  cmd --> code[Extension code]
  tool --> code
  service --> code
  classDef person fill:#e3f2fd,stroke:#1565c0,color:#000000
  classDef cmd fill:#1976d2,stroke:#0d47a1,color:#ffffff
  classDef ext fill:#fff3e0,stroke:#e65100,color:#000000
  class person person
  class neut,cmd,tool,service cmd
  class manifest,code ext
  linkStyle default stroke:#777777,stroke-width:3px
```

Discovery order, highest first: `.neut/extensions/`, then `~/.neut/extensions/`, then the builtins in this repository. A later tier does not override an earlier one. The project copy wins.

## Extensions

```mermaid
flowchart TB
  subgraph models [Models]
    model["neut model"]
    facility["neut facility"]
    bench["neut bench"]
    compute["neut compute"]
  end
  subgraph operate [Operations]
    experiment["neut experiment"]
    site["neut site"]
    logbook[ops logbook]
  end
  subgraph signals [Signals]
    daq["neut daq"]
    telemetry["neut telemetry"]
    kit["neut kit"]
  end
  subgraph serve [Serving]
    web["webapp /app"]
  end
  site --> daq
  daq --> telemetry
  telemetry --> web
  model --> facility
  classDef cmd fill:#1976d2,stroke:#0d47a1,color:#ffffff
  classDef store fill:#c8e6c9,stroke:#2e7d32,color:#000000
  class model,facility,bench,compute,experiment,site,daq,telemetry,kit cmd
  class logbook,web store
  linkStyle default stroke:#777777,stroke-width:3px
```

| Extension | Noun | What it is |
|---|---|---|
| [model_corral](src/neutron_os/extensions/builtins/model_corral/README.md) | `neut model`, `neut facility` | Versioned physics-model registry and site packs |
| [expman](src/neutron_os/extensions/builtins/expman/README.md) | `neut experiment`, `neut ops-request`, `neut calendar-request` | Sample lifecycle, operations requests, calendar requests |
| [daq](src/neutron_os/extensions/builtins/daq/README.md) | `neut daq`, `neut topology` | Signal providers, conform, ingest, preflight |
| [telemetry](src/neutron_os/extensions/builtins/telemetry/README.md) | `neut telemetry` | Staged CSV to the time-series table, and the query over it |
| [site](src/neutron_os/extensions/builtins/site/README.md) | `neut site` | Bind this install, deploy a release, scaffold a site package |
| [nuclear_bench](src/neutron_os/extensions/builtins/nuclear_bench/README.md) | `neut bench` | Labeled question pools and a seeded sampler |
| [demo](src/neutron_os/extensions/builtins/demo/README.md) | `neut demo` | Scripted walkthroughs |
| [kit](src/neutron_os/extensions/builtins/kit/README.md) | `neut kit` | A contribution folder. Init and check. It does not deploy |
| [fleet_compute](src/neutron_os/extensions/builtins/fleet_compute/README.md) | `neut compute` | Stochastic transport batches: decompose, dispatch, aggregate |
| [ops_log](src/neutron_os/extensions/builtins/ops_log/README.md) | logbook `reactor_ops` | What an operations entry is, and who may sign it |
| [webapp](webapp/README.md) | service at `/app` | Shared site UI. Gold is projected into the OLTP store |
| [twin](src/neutron_os/extensions/builtins/twin/README.md) | none yet | Receipt, reference, and scorecard types for a reactor twin |
| [eclab](src/neutron_os/extensions/builtins/eclab/README.md) | none | Generated, watermarked corpus for export-control tests |
| [graph](src/neutron_os/extensions/builtins/graph/README.md) | none | Optional ontology provider. No manifest, so it is not loaded |

Two packs ship with `neut facility`: **MSRE** and **PWR-generic**.

## A reading, end to end

A site package says which node this install is. `neut daq` reads that site's sources and conforms rows. `neut telemetry` lands staged files into `reactor_timeseries`. The web app serves `/app` from the OLTP catalog a gold push fills. Models stay in the corral; a prediction names the deck by `corral:<name>@<revision>`.

```mermaid
flowchart TB
  subgraph node [This node]
    bind["neut site bind"]
    acquire["neut daq run"]
    land["neut telemetry ingest"]
  end
  subgraph keep [Stored]
    rows[conformed rows]
    series[reactor_timeseries]
    oltp[OLTP catalog]
  end
  bind --> acquire
  acquire --> rows
  rows --> land
  land --> series
  series --> push[gold push]
  push --> oltp
  oltp --> app["/app"]
  classDef cmd fill:#1976d2,stroke:#0d47a1,color:#ffffff
  classDef store fill:#c8e6c9,stroke:#2e7d32,color:#000000
  class bind,acquire,land,push,app cmd
  class rows,series,oltp store
  linkStyle default stroke:#777777,stroke-width:3px
```

## Commands you will actually type

```bash
neut model add ./input.i
neut model validate ./input.i
neut model list
neut model materials --card UO2
neut facility list
neut experiment list
neut daq diagnose
neut telemetry query metrics
neut site whoami
```

Every `neut model` command accepts `--json`. The verbs are `init`, `validate`, `add`, `clone`, `search`, `list`, `show`, `pull`, `lineage`, `diff`, `export`, `audit`, `generate`, `lint`, `sweep`, `materials`, `share`, `receive`, `review`, `reviews`, `resolve`, `invite`, `contributors`, `status`.

`neut facility` is `list`, `show`, `install`, `uninstall`, `init`, `publish`, `materials`, `sync`. `uninstall` takes `--confirm`.

## What this repository does not register

Chat, signal ingest, and document publishing are not `neut` nouns. They are already on the platform CLI:

| | Command |
|---|---|
| Chat | `axi chat` |
| Signals | `axi signal brief` |
| Publishing | `axi pub overview` |
| Federation | `axi federation` |
| Retrieval | `axi rag` |
| Diagnostics | `axi doctor` |

NeutronOS contributes the nuclear catalog those surfaces read: materials, models, facility packs, and the extensions above.

## Where things live

```
src/neutron_os/
  cli.py                         # neut. Brand, then dispatch
  extensions/builtins/           # one directory per extension, each with axiom-extension.toml
webapp/                          # the shared /app package, separate wheel
runtime/                         # this install's config and state
docs/                            # prds, specs, adrs, guides, runbooks
```

Extension tests live next to the extension. `tests/` is cross-cutting only.

## Development

```bash
make test
pytest -m "not integration"
ruff check src/ tests/
```

## Design rules

- Reactor-agnostic core. A facility's specifics live in its site package and its packs.
- Offline-first. Queue locally, send when the path is back.
- A person confirms writes that sit next to operations.
- One model has one composition. Two sources that disagree do not get averaged.

## Documentation

Start at [docs/guides/start-here.md](docs/guides/start-here.md), then the map in [docs/README.md](docs/README.md).

- [Executive PRD](docs/prds/prd-executive.md)
- [Master spec](docs/specs/spec-executive.md)
- [ADR index](docs/adrs/README.md)
- [Glossary](docs/glossary.md)

## License

Apache 2.0 — see [LICENSE](LICENSE).

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