Metadata-Version: 2.4
Name: kronos-fusion-ml
Version: 0.1.0
Summary: KODEX — the Kronos Family of Codes: a benchmarked AI/ML surrogate suite for fusion, with calibrated uncertainty and an abstention gate on every model.
Author: Kronos Fusion Energy
License: Apache-2.0
Project-URL: Homepage, https://www.kronosfusionenergy.com/kodex
Project-URL: Repository, https://github.com/KronosFE/kronos-ml
Keywords: fusion,surrogate,machine-learning,uncertainty-quantification,gyrokinetic,cgyro
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: kronos-toolkit
Provides-Extra: nn
Requires-Dist: torch>=2; extra == "nn"
Provides-Extra: ml
Requires-Dist: scikit-learn>=1.1; extra == "ml"
Provides-Extra: data
Requires-Dist: pandas>=1.3; extra == "data"
Requires-Dist: pyarrow; extra == "data"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.4; extra == "plot"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# KODEX — the Kronos Family of Codes

A benchmarked AI/ML surrogate suite for fusion. Fast, calibrated stand-ins for
expensive physics — **every code knows when it is out of its depth.**

- **One contract:** `predict(x) -> Prediction(y, uncertainty, in_domain)`
- **Calibrated uncertainty** on every prediction (the **KHALO** layer)
- **An abstention gate** on every prediction (the **KGATE** trust boundary)
- **Honest provenance** in the type: every surrogate is `[T]` tagged, naming the
  real code it stands in for (`retired_by`) — nothing is ever mistaken for
  high-fidelity, and nothing is called "live."

30 codes across three rollout **phases** (Phase 1 = data-backed, ships first;
Phase 2 = partial data; Phase 3 = roadmap). See [`BENCHMARKS.md`](BENCHMARKS.md)
for the honest per-code numbers and [`FAMILY.md`](FAMILY.md) for the technical note.

## Install

```bash
pip install -e ".[ml,data,nn]"     # kronos-toolkit + numpy/scipy are the core
```

The core imports with **no torch and no sklearn**; heavy dependencies load only
when a surrogate actually runs.

## Quickstart

```python
import kronos_ml as K

K.list_surrogates()                 # the 30 K-codes
K.fleet(phase=1)                    # Phase-1 cards

# a real CGYRO transport prediction (representative fidelity, mu=400)
p = K.run("KYRO", [3.5, 1.6])       # a/L_T, magnetic shear
p.y, p.uncertainty, p.in_domain     # ion heat flux Q_i, 1-sigma, trust gate

# the model-free safety gate
K.get("KGATE").clamp([2.0, 0.3, 9.0, 5.0, 0.9, 60.0])   # -> projected onto the envelope

# provenance travels with the value
p.as_tagged("CGYRO (nonlinear gyrokinetic)")            # [T] retired_by CGYRO
```

## The fleet (30 codes)

**Spine:** `KHALO` (uncertainty) · `KGATE` (abstention gate).
**Phase-1 members:** `KOIL` (magnet twin + quench) · `KFLOW` (state estimation) ·
`KMAT` (materials screen) · `KYRO` (CGYRO transport) · `KWARD` (disruption) ·
`KORE` (equilibrium) · `KAIROS` (control) · `KQUBIT` (quantum-ML, no-advantage).
**Phase-2/3:** breeder/burner/isotope/neutronics/operational codes, more quantum
(`KQROSS`, `KSENSE`, `KTENSOR`), multi-fidelity (`KFUSE`), and roadmap codes
(`KFORGE`, `KDRIVE`, `KLAW`, `KGEN`, `KPILOT`, …). `KECON` is a **generic** open
techno-economics calculator with a **financial firewall** — it carries no Kronos
cost/price/valuation data, ever.

## Honesty

Every pre-registered miss is kept (KFLOW AC-18, KWARD <30 ms warning, KORE 1%
bar). CGYRO-backed results are at **representative fidelity (reduced electron
mass μ=400)**; the real-mass "gold" validation point is the single open item.
No economics or Kronos financials in any physics code. Apache-2.0.
