latentplant 0.4.0__tar.gz

latentplant-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Santibanez-Leal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

latentplant-0.4.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: latentplant
+Version: 0.4.0
+Summary: Learned world models for industrial process time series: action-conditioned latent dynamics, imagination rollouts with calibrated uncertainty, planning and regime-change detection
+Author-email: Felipe Santibanez-Leal <fsantibanez@gmail.com>
+License: MIT
+Project-URL: Repository, https://github.com/fsantibanezleal/CAOS_LatentPlant
+Keywords: world-models,latent-dynamics,model-based-rl,imagination,process-control,time-series,uncertainty-quantification,mineral-processing,rssm,planning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: torch>=2.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: onnx
+Requires-Dist: onnx>=1.16; extra == "onnx"
+Requires-Dist: onnxruntime>=1.18; extra == "onnx"
+Provides-Extra: baselines
+Requires-Dist: sysidentpy>=0.3; extra == "baselines"
+Requires-Dist: pysindy>=1.7; extra == "baselines"
+Dynamic: license-file
+
+# latentplant
+
+[![ci](https://github.com/fsantibanezleal/CAOS_LatentPlant/actions/workflows/ci.yml/badge.svg)](https://github.com/fsantibanezleal/CAOS_LatentPlant/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Learned world models for industrial process time series.** An action-conditioned model of
+process dynamics that can be rolled forward in imagination, carries calibrated uncertainty, and
+supports what-if queries, planning and regime-change detection.
+
+## What a world model is here, and why it is not a forecaster
+
+A forecaster maps history to a future. A world model maps history **and a proposed action
+sequence** to a distribution over futures:
+
+```python
+rollout(obs_ctx, act_ctx, exo_ctx, act_fut, exo_fut, n_samples=64)
+```
+
+`act_fut` is an argument. That single difference is what makes counterfactual questions
+expressible ("what if we raise the amine dose for the next four hours") and what makes planning
+possible at all. A model that ignores its action input is a forecaster wearing a costume, so the
+test suite asserts direction-of-effect on a system with known gain.
+
+## The disciplines baked in
+
+**Rollout-first evaluation.** One-step teacher-forced error is not a world-model metric: on any
+autocorrelated process series it flatters a model that has learned nothing. Everything in
+`latentplant.metrics` is indexed by horizon, and `break_even_horizon` reports where the model
+stops beating persistence. That integer belongs next to every headline number.
+
+**Two uncertainties, reported separately.** `uncertainty_split` returns aleatoric (process and
+sensor noise, irreducible) and epistemic (the model does not know this region) as different
+arrays. A noisy tag and an unfamiliar operating point look identical in a single band and mean
+completely different things; the epistemic band is what a regime-change alarm should watch.
+
+**Cadence is declared, not guessed.** An hourly lab assay carried on 20-second rows repeats about
+180 times. A model trained without masking those repeats learns to copy the previous row and
+scores beautifully. `PlantSchema` takes `update_seconds` per tag and `stale_mask` marks the
+repeats so the loss can ignore them.
+
+**Leakage-safe by construction.** Episodes never cross an acquisition gap, windows never cross an
+episode, splits are chronological, and standardization is fitted on train only.
+
+## Install
+
+```bash
+pip install latentplant                 # core: numpy + torch
+pip install "latentplant[onnx]"         # ONNX export for a browser inference lane
+pip install "latentplant[baselines]"    # sysidentpy / pysindy baseline adapters
+```
+
+## Quick start
+
+```python
+import numpy as np
+from latentplant import (PlantSchema, TagSpec, ProbabilisticEnsemble,
+                         split_on_gaps, make_windows, chronological_split)
+from latentplant.metrics import rollout_report
+
+schema = PlantSchema(
+    tags=(
+        TagSpec("silica_conc", "target", "pct", 0.0, 10.0, update_seconds=3600.0),
+        TagSpec("pulp_level", "observation", "pct", 0.0, 100.0),
+        TagSpec("amina_flow", "action", "m3/h", 0.0, 800.0),
+        TagSpec("iron_feed", "exogenous", "pct"),
+    ),
+    row_seconds=20.0,
+)
+
+episodes = split_on_gaps(schema, values, timestamps)      # a plant stop ends an episode
+windows = make_windows(schema, episodes, context=24, horizon=12)
+train, val, test = chronological_split(windows)
+
+wm = ProbabilisticEnsemble(n_obs=2, n_act=1, n_exo=1, n_members=5)
+wm.fit(train, epochs=60, seed=0)
+
+roll = wm.rollout(test.obs_ctx, test.act_ctx, test.exo_ctx,
+                  test.act_fut, test.exo_fut, n_samples=64, seed=0)
+lo, hi = roll.interval(0.9)
+print(rollout_report(roll.samples, test.obs_fut, test.obs_ctx, test.mask_fut))
+```
+
+Counterfactual A/B from the same anchor:
+
+```python
+more, less = wm.counterfactual(ctx_obs, ctx_act, ctx_exo, action_a, action_b, exo_fut)
+lift = more.mean - less.mean
+```
+
+On real plant data this supports direction-of-effect claims only: logged actions come from a
+closed loop, so observational data does not identify interventions without assumptions. On a
+simulator the ground truth exists and the imagination-to-reality gap is measured instead.
+
+Plan against the model, and measure what the plan was worth:
+
+```python
+from latentplant import Planner, cvar_cost, target_tracking_cost, imagination_gap
+
+planner = Planner(model=wm, bounds=action_bounds, horizon=24, method="cem")
+plan = planner.plan(obs_ctx[:1], act_ctx[:1], exo_ctx[:1], exo_fut[:1],
+                    cvar_cost(target_tracking_cost(target), alpha=0.2),
+                    action_rate_penalty=2.0)
+
+realized = env.execute(plan.actions)          # only possible where truth exists
+print(imagination_gap(plan, realized, persistence_from=obs_ctx[0]))
+```
+
+Fix an overconfident model's intervals without retraining it:
+
+```python
+from latentplant import fit_conformal, calibration_report
+
+conf = fit_conformal(cal_roll, cal.obs_fut, level=0.9, mask=cal.mask_fut)
+print(calibration_report(conf, test_roll, test.obs_fut, mask=test.mask_fut))
+```
+
+## Documentation
+
+Full docs in [`docs/`](docs/README.md): concepts (what a world model is, the plant contract,
+windows and leakage), models (probabilistic ensemble, RSSM, ensembled RSSM), evaluation (rollout
+metrics, conformal calibration) and planning (imagination, the imagination-to-reality gap).
+
+## Status
+
+0.03.000, alpha. Shipping now: the ingestion contract with the multi-rate observation operator,
+episodes/windows/leakage-safe splits, the probabilistic ensemble (PETS-class, TS-inf
+propagation), the vector RSSM, the ensembled RSSM with the aleatoric/epistemic split, the
+rollout metric suite, split-conformal interval calibration, and CEM/MPPI planning with the
+imagination-to-reality gap. On the roadmap: ONNX export for a browser inference lane, a
+Gymnasium imagination env, and baseline adapters.
+
+## Not to be confused with
+
+[`phenoforge`](https://pypi.org/project/phenoforge/), the sibling engine, which fits and
+ensembles **closed-form phenomenological equations**. `latentplant` **learns latent dynamics from
+data**. Same industry, different object.
+
+## References
+
+The design follows: Chua et al. 2018, *Deep RL in a Handful of Trials with Probabilistic Dynamics
+Models*, [arXiv:1805.12114](https://arxiv.org/abs/1805.12114) (probabilistic ensembles, TS-inf);
+Lakshminarayanan et al. 2017, *Simple and Scalable Predictive Uncertainty Estimation using Deep
+Ensembles*, [arXiv:1612.01474](https://arxiv.org/abs/1612.01474); Hafner et al. 2019, *Learning
+Latent Dynamics for Planning from Pixels*, [arXiv:1811.04551](https://arxiv.org/abs/1811.04551)
+(RSSM); Hafner et al. 2023, *Mastering Diverse Domains through World Models*,
+[arXiv:2301.04104](https://arxiv.org/abs/2301.04104); Janner et al. 2019, *When to Trust Your
+Model*, [arXiv:1906.08253](https://arxiv.org/abs/1906.08253) (rollout horizon and compounding
+error); Che et al. 2016, *Recurrent Neural Networks for Multivariate Time Series with Missing
+Values*, [arXiv:1606.01865](https://arxiv.org/abs/1606.01865) (cadence and masking); Romano et
+al. 2019, *Conformalized Quantile Regression*,
+[arXiv:1905.03222](https://arxiv.org/abs/1905.03222) (interval calibration); Williams et al.
+2017, *Information Theoretic Model Predictive Control*,
+[arXiv:1707.02342](https://arxiv.org/abs/1707.02342) (MPPI); Levine et al. 2020, *Offline
+Reinforcement Learning: Tutorial, Review, and Perspectives*,
+[arXiv:2005.01643](https://arxiv.org/abs/2005.01643) (why the planner refuses to issue
+setpoints).
+
+Developed by Felipe Santibanez-Leal. MIT licensed.

latentplant-0.4.0/README.md

@@ -0,0 +1,158 @@
+# latentplant
+
+[![ci](https://github.com/fsantibanezleal/CAOS_LatentPlant/actions/workflows/ci.yml/badge.svg)](https://github.com/fsantibanezleal/CAOS_LatentPlant/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Learned world models for industrial process time series.** An action-conditioned model of
+process dynamics that can be rolled forward in imagination, carries calibrated uncertainty, and
+supports what-if queries, planning and regime-change detection.
+
+## What a world model is here, and why it is not a forecaster
+
+A forecaster maps history to a future. A world model maps history **and a proposed action
+sequence** to a distribution over futures:
+
+```python
+rollout(obs_ctx, act_ctx, exo_ctx, act_fut, exo_fut, n_samples=64)
+```
+
+`act_fut` is an argument. That single difference is what makes counterfactual questions
+expressible ("what if we raise the amine dose for the next four hours") and what makes planning
+possible at all. A model that ignores its action input is a forecaster wearing a costume, so the
+test suite asserts direction-of-effect on a system with known gain.
+
+## The disciplines baked in
+
+**Rollout-first evaluation.** One-step teacher-forced error is not a world-model metric: on any
+autocorrelated process series it flatters a model that has learned nothing. Everything in
+`latentplant.metrics` is indexed by horizon, and `break_even_horizon` reports where the model
+stops beating persistence. That integer belongs next to every headline number.
+
+**Two uncertainties, reported separately.** `uncertainty_split` returns aleatoric (process and
+sensor noise, irreducible) and epistemic (the model does not know this region) as different
+arrays. A noisy tag and an unfamiliar operating point look identical in a single band and mean
+completely different things; the epistemic band is what a regime-change alarm should watch.
+
+**Cadence is declared, not guessed.** An hourly lab assay carried on 20-second rows repeats about
+180 times. A model trained without masking those repeats learns to copy the previous row and
+scores beautifully. `PlantSchema` takes `update_seconds` per tag and `stale_mask` marks the
+repeats so the loss can ignore them.
+
+**Leakage-safe by construction.** Episodes never cross an acquisition gap, windows never cross an
+episode, splits are chronological, and standardization is fitted on train only.
+
+## Install
+
+```bash
+pip install latentplant                 # core: numpy + torch
+pip install "latentplant[onnx]"         # ONNX export for a browser inference lane
+pip install "latentplant[baselines]"    # sysidentpy / pysindy baseline adapters
+```
+
+## Quick start
+
+```python
+import numpy as np
+from latentplant import (PlantSchema, TagSpec, ProbabilisticEnsemble,
+                         split_on_gaps, make_windows, chronological_split)
+from latentplant.metrics import rollout_report
+
+schema = PlantSchema(
+    tags=(
+        TagSpec("silica_conc", "target", "pct", 0.0, 10.0, update_seconds=3600.0),
+        TagSpec("pulp_level", "observation", "pct", 0.0, 100.0),
+        TagSpec("amina_flow", "action", "m3/h", 0.0, 800.0),
+        TagSpec("iron_feed", "exogenous", "pct"),
+    ),
+    row_seconds=20.0,
+)
+
+episodes = split_on_gaps(schema, values, timestamps)      # a plant stop ends an episode
+windows = make_windows(schema, episodes, context=24, horizon=12)
+train, val, test = chronological_split(windows)
+
+wm = ProbabilisticEnsemble(n_obs=2, n_act=1, n_exo=1, n_members=5)
+wm.fit(train, epochs=60, seed=0)
+
+roll = wm.rollout(test.obs_ctx, test.act_ctx, test.exo_ctx,
+                  test.act_fut, test.exo_fut, n_samples=64, seed=0)
+lo, hi = roll.interval(0.9)
+print(rollout_report(roll.samples, test.obs_fut, test.obs_ctx, test.mask_fut))
+```
+
+Counterfactual A/B from the same anchor:
+
+```python
+more, less = wm.counterfactual(ctx_obs, ctx_act, ctx_exo, action_a, action_b, exo_fut)
+lift = more.mean - less.mean
+```
+
+On real plant data this supports direction-of-effect claims only: logged actions come from a
+closed loop, so observational data does not identify interventions without assumptions. On a
+simulator the ground truth exists and the imagination-to-reality gap is measured instead.
+
+Plan against the model, and measure what the plan was worth:
+
+```python
+from latentplant import Planner, cvar_cost, target_tracking_cost, imagination_gap
+
+planner = Planner(model=wm, bounds=action_bounds, horizon=24, method="cem")
+plan = planner.plan(obs_ctx[:1], act_ctx[:1], exo_ctx[:1], exo_fut[:1],
+                    cvar_cost(target_tracking_cost(target), alpha=0.2),
+                    action_rate_penalty=2.0)
+
+realized = env.execute(plan.actions)          # only possible where truth exists
+print(imagination_gap(plan, realized, persistence_from=obs_ctx[0]))
+```
+
+Fix an overconfident model's intervals without retraining it:
+
+```python
+from latentplant import fit_conformal, calibration_report
+
+conf = fit_conformal(cal_roll, cal.obs_fut, level=0.9, mask=cal.mask_fut)
+print(calibration_report(conf, test_roll, test.obs_fut, mask=test.mask_fut))
+```
+
+## Documentation
+
+Full docs in [`docs/`](docs/README.md): concepts (what a world model is, the plant contract,
+windows and leakage), models (probabilistic ensemble, RSSM, ensembled RSSM), evaluation (rollout
+metrics, conformal calibration) and planning (imagination, the imagination-to-reality gap).
+
+## Status
+
+0.03.000, alpha. Shipping now: the ingestion contract with the multi-rate observation operator,
+episodes/windows/leakage-safe splits, the probabilistic ensemble (PETS-class, TS-inf
+propagation), the vector RSSM, the ensembled RSSM with the aleatoric/epistemic split, the
+rollout metric suite, split-conformal interval calibration, and CEM/MPPI planning with the
+imagination-to-reality gap. On the roadmap: ONNX export for a browser inference lane, a
+Gymnasium imagination env, and baseline adapters.
+
+## Not to be confused with
+
+[`phenoforge`](https://pypi.org/project/phenoforge/), the sibling engine, which fits and
+ensembles **closed-form phenomenological equations**. `latentplant` **learns latent dynamics from
+data**. Same industry, different object.
+
+## References
+
+The design follows: Chua et al. 2018, *Deep RL in a Handful of Trials with Probabilistic Dynamics
+Models*, [arXiv:1805.12114](https://arxiv.org/abs/1805.12114) (probabilistic ensembles, TS-inf);
+Lakshminarayanan et al. 2017, *Simple and Scalable Predictive Uncertainty Estimation using Deep
+Ensembles*, [arXiv:1612.01474](https://arxiv.org/abs/1612.01474); Hafner et al. 2019, *Learning
+Latent Dynamics for Planning from Pixels*, [arXiv:1811.04551](https://arxiv.org/abs/1811.04551)
+(RSSM); Hafner et al. 2023, *Mastering Diverse Domains through World Models*,
+[arXiv:2301.04104](https://arxiv.org/abs/2301.04104); Janner et al. 2019, *When to Trust Your
+Model*, [arXiv:1906.08253](https://arxiv.org/abs/1906.08253) (rollout horizon and compounding
+error); Che et al. 2016, *Recurrent Neural Networks for Multivariate Time Series with Missing
+Values*, [arXiv:1606.01865](https://arxiv.org/abs/1606.01865) (cadence and masking); Romano et
+al. 2019, *Conformalized Quantile Regression*,
+[arXiv:1905.03222](https://arxiv.org/abs/1905.03222) (interval calibration); Williams et al.
+2017, *Information Theoretic Model Predictive Control*,
+[arXiv:1707.02342](https://arxiv.org/abs/1707.02342) (MPPI); Levine et al. 2020, *Offline
+Reinforcement Learning: Tutorial, Review, and Perspectives*,
+[arXiv:2005.01643](https://arxiv.org/abs/2005.01643) (why the planner refuses to issue
+setpoints).
+
+Developed by Felipe Santibanez-Leal. MIT licensed.

latentplant-0.4.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "latentplant"
+version = "0.4.0"
+description = "Learned world models for industrial process time series: action-conditioned latent dynamics, imagination rollouts with calibrated uncertainty, planning and regime-change detection"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Felipe Santibanez-Leal", email = "fsantibanez@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.24", "torch>=2.2"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering",
+]
+keywords = [
+  "world-models", "latent-dynamics", "model-based-rl", "imagination",
+  "process-control", "time-series", "uncertainty-quantification",
+  "mineral-processing", "rssm", "planning",
+]
+
+[project.urls]
+Repository = "https://github.com/fsantibanezleal/CAOS_LatentPlant"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.4"]
+onnx = ["onnx>=1.16", "onnxruntime>=1.18"]
+baselines = ["sysidentpy>=0.3", "pysindy>=1.7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: long-running training comparisons (deselect with -m 'not slow')"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]

latentplant-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

latentplant-0.4.0/src/latentplant/__init__.py

@@ -0,0 +1,69 @@
+"""latentplant: learned world models for industrial process time series.
+
+An action-conditioned model of process dynamics that can be rolled forward in
+imagination, carries calibrated uncertainty, and supports what-if queries,
+planning and regime-change detection.
+
+This package is the engine. It is deliberately domain-agnostic: it knows about
+observations, actions, exogenous inputs and cadence, not about flotation. The
+mining instantiation lives in the product that consumes it (Porvenir).
+
+Sibling engine, different concept: `phenoforge` fits and ensembles CLOSED-FORM
+phenomenological equations. `latentplant` learns latent dynamics from data. They
+share a domain and nothing else.
+"""
+
+from .calibrate import (
+    ConformalIntervals,
+    calibration_report,
+    coverage_per_horizon,
+    fit_conformal,
+)
+from .data.contract import PlantSchema, TagSpec, validate
+from .data.windows import (
+    Episode,
+    Standardizer,
+    WindowSet,
+    chronological_split,
+    episodes_from_blocks,
+    make_windows,
+    split_on_gaps,
+)
+from .export import export_rssm, onnx_rollout
+from .models.base import Rollout, WorldModel
+from .models.ensemble import ProbabilisticEnsemble
+from .models.rssm import RSSM
+from .models.rssm_ensemble import RSSMEnsemble
+from .planning import Plan, Planner, cvar_cost, imagination_gap, target_tracking_cost
+
+__version__ = "0.04.000"
+
+__all__ = [
+    "ConformalIntervals",
+    "Episode",
+    "Plan",
+    "Planner",
+    "PlantSchema",
+    "ProbabilisticEnsemble",
+    "RSSM",
+    "RSSMEnsemble",
+    "Rollout",
+    "Standardizer",
+    "TagSpec",
+    "WindowSet",
+    "WorldModel",
+    "__version__",
+    "calibration_report",
+    "chronological_split",
+    "coverage_per_horizon",
+    "cvar_cost",
+    "episodes_from_blocks",
+    "export_rssm",
+    "fit_conformal",
+    "imagination_gap",
+    "make_windows",
+    "onnx_rollout",
+    "split_on_gaps",
+    "target_tracking_cost",
+    "validate",
+]

latentplant-0.4.0/src/latentplant/calibrate.py

@@ -0,0 +1,187 @@
+"""Split-conformal calibration of rollout intervals.
+
+This module exists because of a measured failure, not because calibration is a
+nice property to have. On the thickener PDE case the RSSM produced by far the
+best POINT accuracy of any rung (37.5 percent better than persistence where the
+others managed about 5) and simultaneously the worst calibration: its 90 percent
+intervals covered 67.2 percent of outcomes. A model that is right about the
+trajectory and wrong about its own confidence is dangerous in exactly the way a
+process engineer cannot afford, because the interval is what decides whether the
+advice gets acted on.
+
+The method is conformalized quantile regression (Romano, Patterson and Candes,
+"Conformalized Quantile Regression", arXiv:1905.03222), applied per horizon step
+and per channel. The model's own predictive interval is taken as the starting
+point and widened by a constant learned on a held-out calibration split:
+
+    E_i     = max(lo_i - y_i, y_i - hi_i)          nonconformity, signed to be
+                                                    negative inside the interval
+    q       = ceil((n+1)(1-alpha)) / n  empirical quantile of E
+    [lo - q, hi + q]                                the calibrated interval
+
+Per horizon step matters: compounding error means step 24 needs a wider
+correction than step 1, and a single scalar would over-widen the near horizon to
+fix the far one. Per channel matters for the same reason across units.
+
+THE HONEST CAVEAT, which is stated here and must be repeated wherever these
+intervals are shown: split conformal prediction guarantees marginal coverage
+under EXCHANGEABILITY, and time series windows are not exchangeable. Overlapping
+windows share rows, and process regimes drift, so the finite-sample guarantee
+does not transfer. What this module actually delivers is a principled,
+distribution-free WIDENING RULE fitted on data the model never trained on. Its
+coverage is therefore something to MEASURE on a separate test split, never to
+assert from the theorem. `calibration_report` measures exactly that, and it
+reports the uncalibrated coverage next to the calibrated one so the correction
+can be seen rather than trusted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .models.base import Rollout
+
+
+@dataclass
+class ConformalIntervals:
+    """A fitted per-horizon, per-channel widening rule.
+
+    width : (horizon, n_obs) additive correction applied to both interval ends
+    level : the nominal coverage this was fitted for
+    """
+
+    width: np.ndarray
+    level: float
+    n_calibration: int
+
+    def apply(self, roll: Rollout) -> tuple[np.ndarray, np.ndarray]:
+        """Correct a rollout's own interval into the calibrated one.
+
+        The correction can be NEGATIVE, which tightens rather than widens. That
+        is deliberate: a model whose intervals are too wide should have them
+        narrowed, and a rule that could only widen would be a one-way ratchet
+        that eventually makes every interval useless. The only thing enforced is
+        that the interval does not invert.
+        """
+        lo, hi = roll.interval(self.level)
+        if lo.shape[1:] != self.width.shape:
+            raise ValueError(
+                f"calibration was fitted for horizon/channels {self.width.shape} "
+                f"but this rollout is {lo.shape[1:]}"
+            )
+        new_lo, new_hi = lo - self.width, hi + self.width
+        mid = (lo + hi) / 2.0
+        inverted = new_lo > new_hi
+        return np.where(inverted, mid, new_lo), np.where(inverted, mid, new_hi)
+
+
+def fit_conformal(
+    roll: Rollout,
+    obs_fut: np.ndarray,
+    *,
+    level: float = 0.9,
+    mask: np.ndarray | None = None,
+) -> ConformalIntervals:
+    """Fit the widening rule on a CALIBRATION split the model never trained on.
+
+    `mask` is the multi-rate freshness mask: on a case where the target is an
+    hourly assay repeated across minute rows, calibrating against the repeats
+    would measure how well the model copies a held value, which is not the
+    quantity anyone wants a confidence interval on. Stale entries are excluded
+    from the quantile.
+    """
+    y = np.asarray(obs_fut, dtype=float)
+    lo, hi = roll.interval(level)
+    scores = np.maximum(lo - y, y - hi)  # (n, horizon, n_obs)
+
+    horizon, n_obs = y.shape[1], y.shape[2]
+    width = np.zeros((horizon, n_obs))
+    kept = 0
+    for h in range(horizon):
+        for c in range(n_obs):
+            s = scores[:, h, c]
+            if mask is not None:
+                s = s[np.asarray(mask, dtype=bool)[:, h, c]]
+            s = s[np.isfinite(s)]
+            if s.size == 0:
+                # nothing fresh at this horizon and channel: widening by zero is
+                # the only honest choice, and the empty count is reported so the
+                # caller can see the rule was never actually fitted here
+                continue
+            kept = max(kept, int(s.size))
+            # the finite-sample conformal quantile, which is slightly above the
+            # plain empirical one and is what makes the rule conservative rather
+            # than exactly-nominal on the calibration set itself
+            rank = min(1.0, np.ceil((s.size + 1) * level) / s.size)
+            # NOT clamped at zero: a negative quantile means the model's own
+            # interval was already wider than it needed to be, and tightening it
+            # is the correct response. Clamping would make this a one-way
+            # widener and would over-cover on every well-calibrated rung.
+            width[h, c] = float(np.quantile(s, rank))
+
+    return ConformalIntervals(width=width, level=level, n_calibration=kept)
+
+
+def coverage_per_horizon(
+    lo: np.ndarray, hi: np.ndarray, obs_fut: np.ndarray, mask: np.ndarray | None = None
+) -> np.ndarray:
+    """Empirical coverage at each horizon step, averaged over windows and channels."""
+    y = np.asarray(obs_fut, dtype=float)
+    inside = (y >= lo) & (y <= hi)
+    if mask is None:
+        return inside.mean(axis=(0, 2))
+    m = np.asarray(mask, dtype=bool)
+    num = (inside & m).sum(axis=(0, 2))
+    den = np.maximum(m.sum(axis=(0, 2)), 1)
+    return num / den
+
+
+def mean_interval_width(lo: np.ndarray, hi: np.ndarray) -> np.ndarray:
+    """Average interval width at each horizon step.
+
+    Reported alongside coverage because widening always buys coverage: an
+    infinitely wide interval covers everything and says nothing. The pair
+    (coverage, width) is the only honest way to show a calibration worked.
+    """
+    return (hi - lo).mean(axis=(0, 2))
+
+
+def calibration_report(
+    conformal: ConformalIntervals,
+    roll: Rollout,
+    obs_fut: np.ndarray,
+    *,
+    mask: np.ndarray | None = None,
+) -> dict:
+    """Measure calibrated versus uncalibrated coverage on a TEST split.
+
+    Both are reported. The uncalibrated number is what the model believed and
+    the calibrated number is what the correction achieved, and showing only the
+    second would hide the size of the problem being corrected.
+    """
+    raw_lo, raw_hi = roll.interval(conformal.level)
+    cal_lo, cal_hi = conformal.apply(roll)
+
+    raw_cov = coverage_per_horizon(raw_lo, raw_hi, obs_fut, mask)
+    cal_cov = coverage_per_horizon(cal_lo, cal_hi, obs_fut, mask)
+    return {
+        "level": conformal.level,
+        "n_calibration": conformal.n_calibration,
+        "raw_coverage_per_horizon": raw_cov.tolist(),
+        "calibrated_coverage_per_horizon": cal_cov.tolist(),
+        "raw_coverage": float(raw_cov.mean()),
+        "calibrated_coverage": float(cal_cov.mean()),
+        "raw_width_per_horizon": mean_interval_width(raw_lo, raw_hi).tolist(),
+        "calibrated_width_per_horizon": mean_interval_width(cal_lo, cal_hi).tolist(),
+        "width_inflation": float(
+            mean_interval_width(cal_lo, cal_hi).mean()
+            / max(mean_interval_width(raw_lo, raw_hi).mean(), 1e-12)
+        ),
+        "caveat": (
+            "split conformal guarantees marginal coverage under exchangeability, "
+            "which time-series windows violate; these coverages are MEASURED on a "
+            "held-out split, not implied by the theorem"
+        ),
+    }