certflow 1.0.1__tar.gz → 1.0.2__tar.gz

{certflow-1.0.1 → certflow-1.0.2}/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to CERT-FLOW are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [1.0.2] - 2026-06-10
+
+Packaging and serialization fixes for the freshly published library.
+
+### Fixed
+- `pytest` now discovers the `src/`-layout package on a fresh checkout: the
+  `[tool.pytest.ini_options]` `pythonpath` was `["."]` (repo root, no package
+  there), so `python -m pytest` failed with `ModuleNotFoundError: certflow`
+  unless `PYTHONPATH=src` was set or the package was installed. Set to
+  `["src"]`.
+- `EpisodeResult.oracle_cost` is now serialized by `save_results` and restored
+  by `load_results`. It was dropped on save, so reloaded Tier-2 results came
+  back with `oracle_cost = nan` and any regret analysis silently reported NaN.
+  Legacy result files without the field still load (oracle_cost stays nan).
+
+### Added
+- `realworld` optional extra (`pip install 'certflow[realworld]'`) declaring
+  the `pandas` and `tables` dependencies the METR-LA / PEMS-BAY traffic
+  adapter needs. The core install stays numpy/scipy only; `_load_traffic` now
+  raises a clear `ImportError` pointing at the extra when pandas is absent.
+
 ## [1.0.1] - 2026-06-10
 
 First PyPI release (`pip install certflow`).
@@ -50,5 +71,6 @@ Planning under Drifting Costs (Extended Version)*.
   sum-aware certificate, impossibility of a tighter lower bound,
   decision-uniform validity, churn floor).
 
+[1.0.2]: https://github.com/Archerkattri/CERT-FLOW/releases/tag/v1.0.2
 [1.0.1]: https://github.com/Archerkattri/CERT-FLOW/releases/tag/v1.0.1
 [1.0.0]: https://github.com/Archerkattri/CERT-FLOW/releases/tag/v1.0.0

{certflow-1.0.1 → certflow-1.0.2}/CITATION.cff

@@ -2,6 +2,7 @@ cff-version: 1.2.0
 message: "If you use CERT-FLOW in your research, please cite it as below."
 type: software
 title: "CERT-FLOW: Certified Route Planning under Drifting Costs"
+version: 1.0.2
 authors:
   - family-names: Attri
     given-names: Krishi

{certflow-1.0.1 → certflow-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: certflow
-Version: 1.0.1
+Version: 1.0.2
 Summary: Certified route planning under drifting costs: conformal LB<=OPT<=UB certificates, certificate-directed sensing, proof-gated preprocessing
 Project-URL: Homepage, https://github.com/Archerkattri/CERT-FLOW
 Project-URL: Repository, https://github.com/Archerkattri/CERT-FLOW
@@ -26,13 +26,16 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Provides-Extra: fast
 Requires-Dist: numba; extra == 'fast'
+Provides-Extra: realworld
+Requires-Dist: pandas>=1.5; extra == 'realworld'
+Requires-Dist: tables>=3.7; extra == 'realworld'
 Description-Content-Type: text/markdown
 
 <p align="center"><img src="assets/banner.svg" alt="CERT-FLOW" width="100%"/></p>
 
 <p align="center">
   <a href="https://pypi.org/project/certflow/"><img alt="PyPI" src="https://img.shields.io/pypi/v/certflow?color=009E73"></a>
-  <a href="#reproducing-every-number"><img alt="tests" src="https://img.shields.io/badge/tests-223%20passing-0072B2"></a>
+  <a href="#reproducing-every-number"><img alt="tests" src="https://img.shields.io/badge/tests-227%20passing-0072B2"></a>
   <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-56B4E9">
   <img alt="license" src="https://img.shields.io/badge/license-MIT-1a7f37">
   <img alt="coverage claim" src="https://img.shields.io/badge/certificate%20coverage-1.000%20measured-D55E00">
@@ -107,8 +110,8 @@ To develop or reproduce the paper numbers, work from a clone:
 ```bash
 git clone https://github.com/Archerkattri/CERT-FLOW && cd CERT-FLOW
 python -m venv cert_env && source cert_env/bin/activate
-pip install -e ".[dev,fast]" pandas h5py tables
-pytest   # full suite: 223 with datasets; data-dependent tests skip cleanly without data/
+pip install -e ".[dev,fast,realworld]" h5py
+pytest   # full suite: 227 with datasets; data-dependent tests skip cleanly without data/
 ```
 
 ## Reproducing every number

{certflow-1.0.1 → certflow-1.0.2}/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <a href="https://pypi.org/project/certflow/"><img alt="PyPI" src="https://img.shields.io/pypi/v/certflow?color=009E73"></a>
-  <a href="#reproducing-every-number"><img alt="tests" src="https://img.shields.io/badge/tests-223%20passing-0072B2"></a>
+  <a href="#reproducing-every-number"><img alt="tests" src="https://img.shields.io/badge/tests-227%20passing-0072B2"></a>
   <img alt="python" src="https://img.shields.io/badge/python-3.10%2B-56B4E9">
   <img alt="license" src="https://img.shields.io/badge/license-MIT-1a7f37">
   <img alt="coverage claim" src="https://img.shields.io/badge/certificate%20coverage-1.000%20measured-D55E00">
@@ -77,8 +77,8 @@ To develop or reproduce the paper numbers, work from a clone:
 ```bash
 git clone https://github.com/Archerkattri/CERT-FLOW && cd CERT-FLOW
 python -m venv cert_env && source cert_env/bin/activate
-pip install -e ".[dev,fast]" pandas h5py tables
-pytest   # full suite: 223 with datasets; data-dependent tests skip cleanly without data/
+pip install -e ".[dev,fast,realworld]" h5py
+pytest   # full suite: 227 with datasets; data-dependent tests skip cleanly without data/
 ```
 
 ## Reproducing every number

{certflow-1.0.1 → certflow-1.0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "certflow"
-version = "1.0.1"
+version = "1.0.2"
 authors = [{name = "Krishi Attri", email = "krishiattriwork@gmail.com"}]
 license = {text = "MIT"}
 description = "Certified route planning under drifting costs: conformal LB<=OPT<=UB certificates, certificate-directed sensing, proof-gated preprocessing"
@@ -41,6 +41,7 @@ Issues = "https://github.com/Archerkattri/CERT-FLOW/issues"
 [project.optional-dependencies]
 fast = ["numba"]
 dev = ["pytest>=7.0"]
+realworld = ["pandas>=1.5", "tables>=3.7"]
 
 [build-system]
 requires = ["hatchling"]
@@ -61,5 +62,5 @@ include = [
 ]
 
 [tool.pytest.ini_options]
-pythonpath = ["."]
+pythonpath = ["src"]
 testpaths = ["tests"]

{certflow-1.0.1 → certflow-1.0.2}/src/certflow/__init__.py

@@ -26,7 +26,7 @@ from certflow.cert import CertPlanner, PlannerConfig
 from certflow.conformal import ACITracker, ConformalScorer
 from certflow.types import Certificate, EdgeBelief, World
 
-__version__ = "1.0.1"
+__version__ = "1.0.2"
 
 __all__ = [
     "ACITracker",

{certflow-1.0.1 → certflow-1.0.2}/src/certflow/harness.py

@@ -426,6 +426,7 @@ def _episode_result_to_dict(ep: EpisodeResult) -> dict[str, Any]:
         "travel_cost": _float_to_json(ep.travel_cost),
         "sense_cost": _float_to_json(ep.sense_cost),
         "reached_goal": ep.reached_goal,
+        "oracle_cost": _float_to_json(ep.oracle_cost),
     }
 
 
@@ -435,6 +436,8 @@ def _episode_result_from_dict(d: dict[str, Any]) -> EpisodeResult:
         travel_cost=float(_float_from_json(d["travel_cost"])),
         sense_cost=float(_float_from_json(d["sense_cost"])),
         reached_goal=bool(d["reached_goal"]),
+        # tolerate legacy files written before oracle_cost was serialised
+        oracle_cost=float(_float_from_json(d.get("oracle_cost", _NAN_SENTINEL))),
     )
 
 

{certflow-1.0.1 → certflow-1.0.2}/src/certflow/realworld.py

@@ -28,7 +28,14 @@ DATA_DIR = Path(__file__).resolve().parents[2] / "data"
 @lru_cache(maxsize=2)
 def _load_traffic(dataset: str) -> tuple[list[str], np.ndarray, dict[tuple[str, str], float]]:
     """(sensor_ids, speeds[bins x sensors] mph with missing filled, distances m)."""
-    import pandas as pd
+    try:
+        import pandas as pd
+    except ImportError as exc:  # pragma: no cover - exercised via a stubbed import
+        raise ImportError(
+            "The real-world traffic adapter (METR-LA / PEMS-BAY) needs pandas and "
+            "PyTables, which are not part of the core install. Install them with:\n"
+            "    pip install 'certflow[realworld]'"
+        ) from exc
 
     if dataset == "metr-la":
         h5, dist_csv = DATA_DIR / "metr-la/metr_la.h5", DATA_DIR / "metr-la/distances_la_2012.csv"

{certflow-1.0.1 → certflow-1.0.2}/tests/test_harness.py

@@ -368,6 +368,35 @@ class TestSaveLoad:
             path = save_results(result, tmp)
             assert path.name == f"{config.config_id()}.json"
 
+    def test_oracle_cost_round_trips(self):
+        """Tier-2 regret depends on oracle_cost surviving save/load (not nan)."""
+        config = ExperimentConfig(n_seeds=1, base_seed=0)
+        ep = EpisodeResult(
+            rounds=[],
+            travel_cost=12.5,
+            sense_cost=1.0,
+            reached_goal=True,
+            oracle_cost=9.75,
+        )
+        result = ExperimentResult(config=config, episodes=[ep], seeds=[7])
+        with tempfile.TemporaryDirectory() as tmp:
+            path = save_results(result, tmp)
+            loaded = load_results(path)
+
+        loaded_oracle = loaded.episodes[0].oracle_cost
+        assert not math.isnan(loaded_oracle)
+        assert math.isclose(loaded_oracle, 9.75)
+
+    def test_oracle_cost_nan_round_trips(self):
+        """Tier-1 episodes leave oracle_cost as nan; that must survive too."""
+        config = ExperimentConfig(n_seeds=1, base_seed=0)
+        ep = EpisodeResult(rounds=[], travel_cost=1.0, sense_cost=0.0, reached_goal=False)
+        result = ExperimentResult(config=config, episodes=[ep], seeds=[0])
+        with tempfile.TemporaryDirectory() as tmp:
+            path = save_results(result, tmp)
+            loaded = load_results(path)
+        assert math.isnan(loaded.episodes[0].oracle_cost)
+
     def test_sensed_edge_tuple_roundtrip(self):
         round_log = RoundLog(
             t=0.0,

{certflow-1.0.1 → certflow-1.0.2}/tests/test_realworld.py

@@ -1,11 +1,37 @@
 """Smoke tests for the METR-LA replay world (skipped if data absent)."""
-import math
+import builtins
 from pathlib import Path
 
 import pytest
 
 DATA = Path(__file__).resolve().parents[1] / "data/metr-la/metr_la.h5"
-pytestmark = pytest.mark.skipif(not DATA.exists(), reason="METR-LA not downloaded")
+
+
+def test_core_import_does_not_need_pandas():
+    """Importing certflow core (and realworld module) must not require pandas."""
+    import certflow  # noqa: F401
+    import certflow.realworld  # noqa: F401
+
+
+def test_load_traffic_clear_message_without_pandas(monkeypatch):
+    """If pandas is absent, the adapter points users at certflow[realworld]."""
+    from certflow import realworld
+
+    real_import = builtins.__import__
+
+    def _no_pandas(name, *args, **kwargs):
+        if name == "pandas" or name.startswith("pandas."):
+            raise ImportError("No module named 'pandas'")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", _no_pandas)
+    with pytest.raises(ImportError) as exc:
+        realworld._load_traffic("metr-la")
+    assert "certflow[realworld]" in str(exc.value)
+
+
+# The data-dependent smoke tests below skip cleanly when METR-LA is absent.
+_skip_no_data = pytest.mark.skipif(not DATA.exists(), reason="METR-LA not downloaded")
 
 
 @pytest.fixture(scope="module")
@@ -15,6 +41,7 @@ def world():
     return TrafficWorld(seed=0, n_bins=144)  # half a day
 
 
+@_skip_no_data
 def test_graph_and_costs_sane(world):
     n_edges = sum(len(nbrs) for nbrs in world.graph.values())
     assert n_edges > 500
@@ -26,6 +53,7 @@ def test_graph_and_costs_sane(world):
     assert abs(world.true_cost(e, 299.0) - world.true_cost(e, 301.0)) < 5.0
 
 
+@_skip_no_data
 def test_determinism_and_noise(world):
     from certflow.realworld import TrafficWorld
 
@@ -37,11 +65,13 @@ def test_determinism_and_noise(world):
     assert abs(sum(obs) / len(obs) - truth) < 2.0  # mean ~ truth (scale 5s)
 
 
+@_skip_no_data
 def test_a1_violation_rate_measured(world):
     # rho is the p95 of |dc/dt|: violations exist by construction (~5%)
     assert 0.0 < world.a1_violation_rate < 0.15
 
 
+@_skip_no_data
 def test_planner_runs_on_traffic(world):
     from certflow.cert import CertPlanner
     from certflow.realworld import far_endpoints, traffic_planner_config