Merge v1.4.0 — Phase 1 continuous causal core

Author: raphaelrrcoelho

CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.4.0] - 2026-07-10
+
+Phase 1 — the continuous causal core: identification-aware estimation, partial identification for
+continuous / heavy-tailed / transported targets, finite-sample conformal wrappers, and continuous
+mechanisms with posterior abduction. Fully additive on top of 1.3.0; every new inferential routine
+returns a unified `Certificate`. No shipped signature or behaviour changed; the `certify_decision`
+byte-for-byte regression pin and the `bench_causal_core` fast-path guards are preserved.
+
+### Added
+- **`estimate/` — identification-aware DR/DML estimation** (§7.2): `certify_effect` compiles a graph
+  query into a back-door plan (`identify_effect` → `backdoor_adjustment_set`) and estimates the ATE
+  with plug-in, self-normalised IPW, AIPW, or cross-fitted DML (influence-function CIs), returning an
+  `IDENTIFIED` certificate. Non-identifiable or front-door/general-ID queries hedge (never a silent
+  point); destroyed positivity downgrades to a hedge (I3). Pure-NumPy default nuisances
+  (ridge/logistic) + sklearn-style pluggable — no scipy/sklearn hard dependency. `estimate_ate` /
+  `EffectEstimate` expose the estimators directly. `Certificate` gains an additive optional `ci`.
+- **`bounds/` — estimated-propensity MSM + heavy-tail/quantile targets** (§7.3):
+  `msm_sensitivity_bounds` bounds `E[Y(1)]` under Tan's MSM with *estimated* propensities (reduces
+  exactly to `ipw_sensitivity_bounds` on the known-propensity path); `moment_diagnostic` (Hill
+  tail-index + finite-variance) with `certify_mean` downgrading a mean request to a median on
+  infinite-variance data (I3); `certify_quantile` / `weighted_quantile` with percentile-bootstrap
+  CIs. The package re-exports the shipped nominal-propensity kernels.
+- **`conformal/` — finite-sample coverage** (§7.4): `conformal_quantile` (weighted, covariate-shift
+  aware), `split_conformal_interval`, `cqr_interval` (conformalized quantile regression), and
+  `certify_conformal_interval` (`EMPIRICAL`, exchangeability recorded). Marginal coverage ≥ 1 − α.
+- **`transport/` — data-plane transport estimation** (§7.5): `certify_transported_effect` decides
+  transportability via the shipped `transport_formula`, then estimates the transported mean from
+  source/target observational data (direct = the source interventional mean transfers; adjustment =
+  reweight source conditionals by the target covariate marginal); non-transportable → hedge.
+- **`scm/continuous/` — neural mechanisms + posterior abduction** (§7.1, torch): `MLPMechanism`,
+  the invertible `LocationScaleMechanism`, exact `abduct_location_scale`, the amortized-VI
+  `AmortizedGaussianAbduction`, and `certify_counterfactual` (`IDENTIFIED` for exact inversion,
+  `EMPIRICAL` for VI; a posterior-predictive check recorded as a checkable assumption).
+
+### Notes
+- No new dependencies: the estimation / bounds / conformal / transport layers are NumPy-only; the
+  continuous mechanisms use the existing `[torch]` extra.
+- Deferred to a later 1.x minor: conditional normalizing-flow mechanisms and NUTS/NumPyro abduction;
+  sequential DR / LTMLE and sequential-transport estimation; the 2.0 default-flip `FutureWarning`.
+
 ## [1.3.0] - 2026-07-10
 
 The 1.x consolidation: one unified certificate protocol and a columnar data plane that every later

docs/architecture-map.md

@@ -116,3 +116,31 @@ version is recorded, never a specific string.
 `experimental/ope.py` — `confounding_sensitivity_bounds(point, gamma)`, explicitly documented as a
 *qualitative, non-validated* sensitivity interval (not the published MSM bound). Phase 5's
 `experimental/cyclic/` lands here first.
+
+## 9. Phase 1 — continuous causal core (v1.4.0)
+
+Additive on 1.3.0; every new inferential routine returns a unified `Certificate`. NumPy-only except
+`scm/continuous/` (torch, `[torch]` extra). New leaf packages (re-export shims where they wrap
+shipped code, per plan §4):
+
+- `estimate/` (§7.2) — `certify_effect` (graph query → back-door plan via `identify_effect` +
+  `backdoor_adjustment_set` → DR/DML), `estimate_ate` / `EffectEstimate` (plug-in / IPW / AIPW /
+  cross-fit DML with influence-function CIs), pure-numpy nuisances (`RidgeRegressor` /
+  `LogisticRegressor`, sklearn-style pluggable). Non-identified / front-door / overlap-destroyed →
+  hedge (I3).
+- `bounds/` (§7.3) — shim re-exporting `identification.bounds` + `bounds/continuous.py`:
+  `msm_sensitivity_bounds` (estimated-`e` MSM; reduces to `ipw_sensitivity_bounds`),
+  `moment_diagnostic` / `tail_index_hill`, `certify_mean` (heavy-tail → median downgrade),
+  `certify_quantile` / `weighted_quantile` (percentile-bootstrap CIs).
+- `conformal/` (§7.4) — `conformal_quantile` (weighted), `split_conformal_interval`, `cqr_interval`,
+  `certify_conformal_interval` (`EMPIRICAL`). Marginal coverage ≥ 1 − α.
+- `transport/` (§7.5) — shim over `identification.transport` + `transport/estimate.py`:
+  `certify_transported_effect` (torch-free `transport_formula` decision + numpy g-computation),
+  `transport_gcomp`.
+- `scm/continuous/` (§7.1, torch) — `MLPMechanism`, invertible `LocationScaleMechanism`,
+  `abduct_location_scale` (exact inversion), `AmortizedGaussianAbduction` (ELBO VI),
+  `certify_counterfactual`. Tests `importorskip("torch.nn")` → CI-verified (torch.nn broken locally).
+
+`Certificate` gained an additive optional `ci: Interval | None` field (round-trips; no shipped field
+changed). The new public front doors are lazily exported from `causalrl.__init__` (torch-backed ones
+stay lazy, like `NeuralMechanism`).

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "causalrl"
-version = "1.3.0"
+version = "1.4.0"
 description = "Causal reinforcement learning: the 9-task causal RL taxonomy, made runnable."
 readme = "README.md"
 requires-python = ">=3.11"

src/causalrl/__init__.py

@@ -128,6 +128,27 @@
     "certify_decision": ("causalrl.identification.decision", "certify_decision"),
     "certify_estimate": ("causalrl.identification.decision", "certify_estimate"),
     "certify_policy": ("causalrl.scale", "certify_policy"),
+    "certify_effect": ("causalrl.estimate.compiler", "certify_effect"),
+    "estimate_ate": ("causalrl.estimate.estimators", "estimate_ate"),
+    "EffectEstimate": ("causalrl.estimate.estimators", "EffectEstimate"),
+    "msm_sensitivity_bounds": ("causalrl.bounds.continuous", "msm_sensitivity_bounds"),
+    "certify_sensitivity_bounds": ("causalrl.bounds.continuous", "certify_sensitivity_bounds"),
+    "certify_quantile": ("causalrl.bounds.continuous", "certify_quantile"),
+    "certify_mean": ("causalrl.bounds.continuous", "certify_mean"),
+    "moment_diagnostic": ("causalrl.bounds.continuous", "moment_diagnostic"),
+    "conformal_quantile": ("causalrl.conformal.core", "conformal_quantile"),
+    "split_conformal_interval": ("causalrl.conformal.core", "split_conformal_interval"),
+    "cqr_interval": ("causalrl.conformal.core", "cqr_interval"),
+    "certify_conformal_interval": ("causalrl.conformal.core", "certify_conformal_interval"),
+    "certify_transported_effect": ("causalrl.transport.estimate", "certify_transported_effect"),
+    "MLPMechanism": ("causalrl.scm.continuous.mechanisms", "MLPMechanism"),
+    "LocationScaleMechanism": ("causalrl.scm.continuous.mechanisms", "LocationScaleMechanism"),
+    "AmortizedGaussianAbduction": (
+        "causalrl.scm.continuous.abduction",
+        "AmortizedGaussianAbduction",
+    ),
+    "abduct_location_scale": ("causalrl.scm.continuous.abduction", "abduct_location_scale"),
+    "certify_counterfactual": ("causalrl.scm.continuous.abduction", "certify_counterfactual"),
     "DecisionCertificate": ("causalrl.identification.decision", "DecisionCertificate"),
     "PolicyValueContrast": ("causalrl.identification.estimate", "PolicyValueContrast"),
     "Certificate": ("causalrl.certify", "Certificate"),
@@ -224,6 +245,7 @@
     "PAG",
     "UCDTR",
     "Agent",
+    "AmortizedGaussianAbduction",
     "Assumption",
     "BehavioralCloning",
     "BenchmarkEstimate",
@@ -249,6 +271,7 @@
     "DeepDeconfoundedQ",
     "DictNoiseLedger",
     "Domain",
+    "EffectEstimate",
     "Estimand",
     "EstimandSpec",
     "ExogenousPosterior",
@@ -259,7 +282,9 @@
     "Interval",
     "Kind",
     "LinearGaussianMechanism",
+    "LocationScaleMechanism",
     "MABUCEnv",
+    "MLPMechanism",
     "Mechanism",
     "NaiveOffline",
     "NaivePOMISThompsonSampling",
@@ -290,6 +315,7 @@
     "UnverifiedAssumptionError",
     "Witness",
     "__version__",
+    "abduct_location_scale",
     "apply_potential_shaping",
     "as_certificate",
     "backdoor_adjustment_set",
@@ -298,13 +324,22 @@
     "causal_curriculum",
     "causal_potential",
     "causal_q_bounds",
+    "certify_conformal_interval",
+    "certify_counterfactual",
     "certify_decision",
+    "certify_effect",
     "certify_estimate",
+    "certify_mean",
     "certify_policy",
+    "certify_quantile",
+    "certify_sensitivity_bounds",
+    "certify_transported_effect",
     "conditional_mutual_information",
+    "conformal_quantile",
     "confounding_bias_bound",
     "confounding_bias_per_step_bounds",
     "counterfactual_expectation",
+    "cqr_interval",
     "cumulative_regret",
     "curriculum_q_learning",
     "decision_abstain_mask",
@@ -313,6 +348,7 @@
     "discover_interventional",
     "discover_latent",
     "effect_of_treatment_on_treated",
+    "estimate_ate",
     "estimate_effect",
     "estimate_effect_with_experiments",
     "estimate_transport_general",
@@ -343,10 +379,12 @@
     "mi_flip_threshold",
     "minimal_intervention_sets",
     "mixed_nash_equilibria",
+    "moment_diagnostic",
     "msm_contribution_bounds",
     "msm_per_step_bounds",
     "msm_policy_value_bounds",
     "msm_policy_value_bounds_certified",
+    "msm_sensitivity_bounds",
     "msm_stratified_bounds",
     "pivotality_certificate",
     "pomis",
@@ -358,6 +396,7 @@
     "run_confounded_chain_benchmark",
     "run_episodes",
     "run_frontdoor_benchmark",
+    "split_conformal_interval",
     "tipping_gamma",
     "transport_estimand",
     "transport_formula",

src/causalrl/bounds/__init__.py

@@ -0,0 +1,49 @@
+"""Partial-identification bounds (plan §4 leaf package).
+
+One ``causalrl.bounds`` home that re-exports the shipped nominal-propensity kernels from
+:mod:`causalrl.identification.bounds` alongside the continuous / estimated-propensity / heavy-tail
+additions in :mod:`causalrl.bounds.continuous`. The shipped module stays the source of truth; this
+package adds beside it without moving anything (re-export shim, per plan §4).
+"""
+
+from causalrl.bounds.continuous import (
+    MomentDiagnostic,
+    certify_mean,
+    certify_quantile,
+    certify_sensitivity_bounds,
+    moment_diagnostic,
+    msm_sensitivity_bounds,
+    tail_index_hill,
+    weighted_quantile,
+)
+from causalrl.identification.bounds import (
+    Interval,
+    causal_q_bounds,
+    ipw_sensitivity_bounds,
+    manski_bounds,
+    msm_contribution_bounds,
+    msm_per_step_bounds,
+    msm_policy_value_bounds,
+    msm_stratified_bounds,
+    tipping_gamma,
+)
+
+__all__ = [
+    "Interval",
+    "MomentDiagnostic",
+    "causal_q_bounds",
+    "certify_mean",
+    "certify_quantile",
+    "certify_sensitivity_bounds",
+    "ipw_sensitivity_bounds",
+    "manski_bounds",
+    "moment_diagnostic",
+    "msm_contribution_bounds",
+    "msm_per_step_bounds",
+    "msm_policy_value_bounds",
+    "msm_sensitivity_bounds",
+    "msm_stratified_bounds",
+    "tail_index_hill",
+    "tipping_gamma",
+    "weighted_quantile",
+]