Metadata-Version: 2.4
Name: transport-runtime
Version: 0.6.0
Summary: Zero-label deployment runtime for fitted classifiers under transport drift
Author-email: Shengjie Zhang <2142024286@qq.com>, Wenhao Tian <2144767610@qq.com>
License-Expression: MIT
Keywords: transportability,calibration,conformal prediction,distribution shift,drift audit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=1.5
Requires-Dist: scipy>=1.10
Provides-Extra: xgb
Requires-Dist: xgboost>=1.7; extra == "xgb"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: xgboost>=1.7; extra == "test"
Dynamic: license-file

# Transport Runtime

Zero-label deployment for any fitted probabilistic classifier.

Models are trained on one distribution and executed on another. Transport Runtime wraps any
fitted classifier with a transport layer: a hot-swappable level interface (exact per-channel
calibration from public prevalences only), a drift-law audit (three-line report + level
contamination index), and conformal certificates.

```python
from transport_runtime import TransportLayer

layer = TransportLayer(model).fit_calibration(X_src, y_src, channels_src)
layer.audit(X_new, channels_new, y_new)            # three-line drift report + HCI
deployed = layer.deploy(pi_public, X_unlab, ch)    # zero-label deployment
deployed.predict_proba(X_new, channels_new)        # per-channel exact level (Prop 1)
conf = layer.conformal(X_unlab, ch, pi_public, alpha=0.1, per_channel=True)
conf.predict_set(X_new, channels_new)              # prediction sets with certificates
```

## Theorem index (each function is one theorem, with citation and validation record)

| Function | Theorem | Source | Validation |
|---|---|---|---|
| `moment_delta` / `deploy` | Prop 1: per-channel moment identity — deployed level error identically zero | this project (docs/pilevel_theory.md) | results/pilevel_v08_seeds10.csv, v09 (10 seeds, O/E=1.0000 ×10/10) |
| `audit` (intercept share, warning) | Drift law: level/slope share decomposition | this project (case series, docs/case_*/DRIFTLAW.md) | six case CSVs in results/ |
| `hci` | HCI: level-contamination index (slope of per-channel mean margin on logit prevalence) | this project (docs/levelfree_theory.md) | XGB 1.041 vs randomized-training 1.066 (LevelFree falsification record) |
| `conformal(weighted=True)` | Weighted conformal under covariate shift | Tibshirani et al. 2019 | results/transport_cert_v01.csv (marginal coverage ≥ nominal; per-channel gaps persist) |
| `conformal(per_channel=True)` | Per-channel thresholds (two-tier: level layer + residual slope share) | this project | results/transport_cert_v02.csv (T3 per-channel coverage 0.896–0.897 flat) |
| `ot_gap.cdf_l1_gap` | Total coverage gap = ∫p(t)\|F_P−F_Q\|dt (change of variables) + DKW | Correia & Louizos 2025 (arXiv:2507.10425) Thm 3.2/A.2 | synthetic 0.2545 vs 0.2544; T1 real 0.0485 vs empirical 0.0415 |
| `ot_gap.label_free_gap` | Label-free bound via auxiliary score distributions | Correia & Louizos 2025 Thm 3.3 | validity depends on dominance: `aux_minmax` always valid; `aux_uniform/aux_model` require model accuracy — checked via `check_dominance` |
| `fit_channel_affine` / `channel_affine_repair` | Prop 4(iii)/(iv): mean-one slope-repair boundary (audited families keep E[M]=1; no universal guarantee) | this project | results/prop4iii_boundary_audit_summary.csv, results/brfss_slope_repair_v01_summary.csv |
| `decision_curve` / `clinical_threshold_audit` | Net-benefit decision-curve transport evidence | this project | results/*_dca_v01_summary.csv (13 outcome lines) |
| `transportability_id` / `valid_backdoor_set` / `s_admissible` | Conservative transport-by-adjustment identification: backdoor validity + S-admissibility on explicit DAGs | Pearl–Bareinboim selection-diagram programme; implementation is **not** a complete mz-transportability algorithm | `transport_runtime/tests/test_identify.py` |

## Design principles

1. **Zero-label deployment**: target side needs only unlabeled features + public per-channel prevalences.
2. **Two-tier certificates mirror the drift law**: level (intercept) share → moment-matched level
   layer; residual slope share → per-channel conformal thresholds.
3. **Negative results are documented**: audited training-time level-intervention families fail to remove level
   content (impossibility duality, docs/theory_impossibility.md, Props 4–5, bounded to audited families) — within those audited families the runtime is the
   complete solution set, which is why this is a runtime and not a training method.
4. **Honest bounds**: certificates widen/fail visibly under slope corruption (Prop 2′) rather
   than failing silently.

## Scope and limits

- Within-channel ranking must transport (Prop 2′: residual ≤ ECE_w + L·τ). If discrimination
  itself collapses, no level layer can repair it — audit will say so.
- Small channels: level offsets are shrunk toward a global delta (kappa=200); per-channel
  conformal degrades in small/rare-event channels (empirical: T2 band 0).
- The package does not improve iid performance; its ceiling is parity (that is a theorem, not
  a limitation of implementation).

## Roadmap

- [x] `identify` module: conservative transportability / S-admissibility checker for explicit DAGs (Pearl–Bareinboim adjustment formula; not a complete mz-transportability engine)
- [ ] OT weight-learning (Correia & Louizos 2025 Sec. 4)
- [x] transport-suite v1 step A: aggregator over audited `results/*.csv` → `results/transport_suite_v01_summary.csv` and `results/transport_suite_v01_cert_summary.csv`
- [x] transport-suite v1 step B: low-compute synthetic regression runner (`scripts/transport_suite_v01_runner.py` → `results/transport_suite_v01_runner.csv`)
- [x] robust layer v0.4: EB uncertainty-aware repair + interval bounds (`transport_runtime.robust`)
- [x] compiler layer v0.4: TransportCompiler / DeploymentContract with adaptive point-vs-EB repair gating and archive manifest input fingerprints
- [x] channelization layer v0.4: automatic score-channel discovery from unlabeled covariates and fitted model scores
- [x] channel selection layer v0.4: transport-aware candidate channel selection balancing level structure and shift risk, with bootstrap stability selection
- [x] slope-risk + repair layer v0.4: within-channel score-shift / KS diagnosis, limited-label channel-affine repair, validation-based repair-value estimation, and threshold sensitivity analysis
- [x] slope uncertainty certificate (post-v0.5 working tree): `bootstrap_channel_affine` returns per-channel slope/intercept percentile CIs and success rates; `channel_affine_margin_interval` converts those coefficient CIs into repaired-margin intervals. This quantifies finite-label fitting uncertainty; it is not a proof of target-domain calibration.
- [x] system demo: end-to-end compiler contract generation with archive manifest, slope repair value estimation, slope repair, certificate replay, and verification (`scripts/ncs_system_v01.py`)
- [x] verification layer v0.4: contract self-checks for prevalence validity, certificate alpha, slope-risk finiteness, and input fingerprint matching
- [x] certificate recommendation + replay layer v0.4: risk-aware policy selection and labeled-target coverage evaluation; post-v0.5 `summarize_slope_uncertainty` incorporates finite-label slope-repair CI widths into certificate policy recommendation, `recommend_certificate_from_audit_pack` consumes audit packs directly, and `summarize_channel_clinical_risk` lets recommendations respond to channel-level clinical losses
- [x] audit pack layer v0.4: standardized JSON artifact combining manifest, slope risk, verification, and certificate evaluation; post-v0.5 `slope_boot=True` adds finite-label slope-repair coefficient CIs and repaired-margin interval summaries, `clinical=True` adds global threshold-specific net-benefit summaries, and `channel_clinical=True` adds per-channel clinical utility summaries
- [x] clinical decision-curve layer (post-v0.5 working tree): `decision_curve`, `compare_decision_curves`, `clinical_threshold_audit`, and `channel_clinical_audit` evaluate threshold-specific net benefit for unrepaired vs repaired deployment outputs
- [x] release artifact builder with SHA256 checksums (`scripts/release_v01.py`; current built version `0.5.0`)
- [x] contract diff layer v0.4: explicit version-to-version comparison for deployment contracts
- [x] full-system benchmark v0.4: 10-seed clean/level/slope/level+slope scenarios with contract, flagged-only slope repair, and risk-proportional label allocation (`scripts/ncs_fullsystem_v01.py`)
- [x] figure generation: NCS-oriented benchmark figures and interface schematic (`scripts/ncs_figures_v01.py`, `scripts/ncs_schematic_v01.py` → `results/figs/`)
- [ ] PyPI release

## Citation

Transport Runtime. Shengjie Zhang, Shihezi University School of Medicine. ORCID 0009-0000-3975-6954.
Archived at ScienceDB (DOI pending). License: MIT.
