formative-ds 2.0.0__tar.gz → 2.2.0__tar.gz

formative_ds-2.2.0/.gitattributes

@@ -0,0 +1 @@
+site/** linguist-generated=true

{formative_ds-2.0.0 → formative_ds-2.2.0}/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
         run: uv sync --dev --group docs
 
       - name: Lint
-        run: uv run ruff check . && uv run ruff format --check .
+        run: uv run ruff check --exclude notebooks . && uv run ruff format --check --exclude notebooks .
 
       - name: Run tests
         run: uv run pytest --cov=formative --cov-report=term-missing --cov-fail-under=80

{formative_ds-2.0.0 → formative_ds-2.2.0}/CLAUDE.md

@@ -1,5 +1,7 @@
 # CLAUDE.md
 
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 ## Commands
 
 ```bash
@@ -7,9 +9,18 @@ uv sync --dev                          # install dependencies
 uv run pytest                          # run all tests
 uv run pytest tests/test_iv.py         # run one file
 uv run pytest tests/test_iv.py::TestIV2SLSEstimation::test_iv_recovers_true_effect  # run one test
-uv run --group docs sphinx-build -b html docs docs/_build  # build docs
+make lint                              # ruff check (excludes notebooks/)
+make fmt                               # ruff format
+make check                             # lint + format check + tests with coverage (CI requires ≥80%)
+make build-docs                        # sphinx with -W: warnings are errors in CI
 ```
 
+CI (`.github/workflows/ci.yml`) runs lint, format check, tests with `--cov-fail-under=80`, and the `-W` docs build on every PR — `make check` plus `make build-docs` reproduces it locally.
+
+Published on PyPI as `formative-ds`; the import name is `formative`. Releases: `make release BUMP=patch|minor|major` — bumps the version, rebuilds docs, snapshots them into `site/<major.minor>/` via `scripts/snapshot_docs.py`, and pushes with tags to trigger the PyPI publish workflow.
+
+Docs are versioned: `site/` holds one committed HTML snapshot per minor version plus `versions.json`; Vercel serves it statically (no build). Unversioned paths (including `/`) are rewritten — not redirected — to the latest snapshot via the catch-all rewrite in `vercel.json`, whose destination the snapshot script bumps each release. Never add a `site/index.html` (it would shadow the rewrite at the root), never edit `site/` by hand, and don't run the snapshot script outside a release. The version dropdown (`docs/_static/version_switcher.js`) fetches `versions.json` from the site root at runtime so old snapshots list newer versions too.
+
 ---
 
 ## Package structure
@@ -46,18 +57,24 @@ Called as `result.refute(df)` — always pass the same `df` used for `fit()`. Re
 - `_PLACEBO_TIME_SEED = 22222` — time permutation in DiD
 - `_PLACEBO_MODIFIER_SEED = 77777` — modifier permutation in CATE checks
 - `_RANDOM_MODIFIER_SEED = 31313` — noise modifier column in CATE checks
+- `_PLACEBO_POLICY_SEED = 88888` — feature permutation in policy checks
+- `_RANDOM_POLICY_MODIFIER_SEED = 46464` — noise feature column in policy checks
+- `_FOLD_SEED = 13579` — cross-fitting fold assignment in policy learning (not a refutation seed)
 - `_BOOTSTRAP_SEED = 42` — safe to reuse in matching's bootstrap (samples row indices, not independent values)
 
 Do not change `_RCC_SEED` or `_PLACEBO_SEED` to 42 — the generated noise collides with instrument/treatment data and produces a singular matrix in IV.
 
 **Heterogeneous effects (CATE)** — `OLSObservational` and `RCT` accept `effect_modifier=` (a discrete, pre-treatment column). `fit()` then returns `OLSCATEResult`/`RCTCATEResult` with `effect_by_group`, a homogeneity F-test, and `decide_by_group()`. The headline `effect` is the sample-share-weighted average of group effects (the raw treatment coefficient under interaction coding is only the reference group's effect). Shared machinery lives in `estimators/_cate.py`; DAG validation rejects modifiers that are descendants of the treatment (mediators) or not ancestors of the outcome.
 
+**Policy learning** — `RCTResult.learn_policy(df, modifiers=[...], cost=, benefit=, max_depth=1|2)` (design note: `docs/design/policy_learning.md`) does Athey–Wager doubly robust policy learning: cross-fitted AIPW scores, exhaustive shallow-tree search over discrete features, honest (out-of-fold) value reported as the advantage over the best constant policy. Returns `PolicyResult` (`rules`, `value`, `assign()`, `refute()`). Refutation checks test the honest *value*, not tree structure — in-sample search happily splits on noise within its depth budget, so structural checks would be flaky. Trees are simplified post-hoc by dropping splits that don't change the assignment (equal-value trees with redundant conditions can win the search on candidate order).
+
 **Package layout:**
 - `formative/causal/dag.py` — `DAG`, `_Node`
 - `formative/causal/_exceptions.py` — `IdentificationError`, `GraphError`
 - `formative/causal/estimators/_base.py` — `_BaseResult`, `_StatsmodelsResult` (shared result plumbing: effect stats via `_param`, `decide()`, assumptions footer)
 - `formative/causal/estimators/_cate.py` — `GroupEffect`, `_fit_cate`, `_CATEResultMixin`, modifier validation (shared by OLS/RCT and the CATE refutations)
 - `formative/causal/estimators/ols.py` — `OLSObservational`, `OLSResult`, `OLSCATEResult`
+- `formative/causal/estimators/policy.py` — `PolicyNode`, `PolicyResult`, `_fit_policy` (used by refutations), `_learn_policy` (entry from `RCTResult.learn_policy`)
 - `formative/causal/estimators/iv.py` — `IV2SLS`, `IVResult`
 - `formative/causal/estimators/matching.py` — `PropensityScoreMatching`, `MatchingResult`; exports `_propensity_scores`, `_att_from_ps` for use by refutations
 - `formative/causal/estimators/rct.py` — `RCT`, `RCTResult`, `RCTCATEResult`
@@ -68,6 +85,7 @@ Do not change `_RCC_SEED` or `_PLACEBO_SEED` to 42 — the generated noise colli
 - `formative/causal/refutations/iv.py` — `IVRefutationReport`, `_check_first_stage_f`, `_check_random_common_cause`
 - `formative/causal/refutations/matching.py` — `MatchingRefutationReport`, `_check_placebo_treatment`, `_check_random_common_cause`
 - `formative/causal/refutations/rct.py` — `RCTRefutationReport`, `_check_random_common_cause`
+- `formative/causal/refutations/policy.py` — `PolicyRefutationReport`, `_check_placebo_modifiers`, `_check_random_modifier` (import `_fit_policy` lazily — a module-level import is circular via `refutations/__init__`)
 - `formative/causal/refutations/cate.py` — `_check_placebo_modifier`, `_check_random_modifier`, `_check_random_common_cause` (used by `OLSCATEResult`/`RCTCATEResult`; reports reuse the OLS/RCT report classes)
 - `formative/causal/refutations/did.py` — `DiDRefutationReport`, `_check_placebo_group`, `_check_random_common_cause`
 - `formative/causal/refutations/rdd.py` — `RDDRefutationReport`, `_check_placebo_cutoff`, `_check_random_common_cause`
@@ -79,6 +97,8 @@ Do not change `_RCC_SEED` or `_PLACEBO_SEED` to 42 — the generated noise colli
 
 **Bootstrap-heavy tests:** matching tests use `setup_class` (not `setup_method`) so `.fit()` runs once per class. Use N=1_000 — larger N widens bootstrap SE faster than NN noise shrinks, causing refutation checks to fail even on well-specified data.
 
+**Benchmarks:** `notebooks/` holds Jupyter notebooks (LaLonde, Card–Krueger) that validate estimators against published results from famous studies; `docs/causal/benchmarks.rst` renders them as a docs page. Notebooks are excluded from ruff. Runnable per-estimator example scripts live in `examples/`.
+
 **Planned estimators:** the goal is to cover all methods in the causal inference decision tree at https://www.maxpagels.com/prototypes/causal-wizard. Remaining: **Synthetic Control**.
 
 ---

formative_ds-2.2.0/Makefile

@@ -0,0 +1,29 @@
+.PHONY: build-docs test lint fmt check release
+
+build-docs:
+	rm -rf docs/_build
+	uv run --group docs sphinx-build -W -b html docs docs/_build
+
+test:
+	uv run pytest --cov=formative --cov-report=term-missing --cov-fail-under=80
+
+lint:
+	uv run ruff check --exclude notebooks .
+
+fmt:
+	uv run ruff format --exclude notebooks .
+
+check: lint
+	uv run ruff format --check --exclude notebooks .
+	uv run pytest --cov=formative --cov-report=term-missing --cov-fail-under=80
+
+release:  # usage: make release BUMP=patch|minor|major
+	@test -n "$(BUMP)" || { echo "Usage: make release BUMP=patch|minor|major"; exit 1; }
+	@git diff --quiet && git diff --cached --quiet || { echo "Working tree not clean — commit or stash first."; exit 1; }
+	uv lock --check
+	uvx bump-my-version bump $(BUMP)
+	$(MAKE) build-docs
+	uv run python scripts/snapshot_docs.py
+	git add site vercel.json
+	git commit -m "Snapshot docs for $$(uv run python scripts/snapshot_docs.py --print-version)"
+	git push --follow-tags

{formative_ds-2.0.0 → formative_ds-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: formative-ds
-Version: 2.0.0
+Version: 2.2.0
 Summary: A Python library for quantitative reasoning.
 Project-URL: Homepage, https://getformative.dev
 Project-URL: Documentation, https://docs.getformative.dev
@@ -47,23 +47,28 @@ Comprehensive documentation is available at [docs.getformative.dev](https://docs
 
 ### Causal estimation
 
+Every analysis follows the same four steps: assume, estimate, refute, decide.
+
 ```python
 from formative.causal import DAG, OLSObservational
 
+# 1. Encode your causal assumptions as a DAG
 dag = DAG()
 dag.assume("ability").causes("education", "income")
 dag.assume("education").causes("income")
 
-result = OLSObservational(
-    dag,
-    treatment="education",
-    outcome="income"
-).fit(df)
-
+# 2. Estimate the causal effect
+result = OLSObservational(dag, treatment="education", outcome="income").fit(df)
 print(result.summary())
+
+# 3. Refute: stress-test the result's assumptions
+print(result.refute(df).summary())
+
+# 4. Decide: is the treatment worth acting on?
+print(result.decide(cost=8, benefit=15))
 ```
 
-Confounders declared in the DAG are controlled for automatically. If a confounder is absent from the dataframe, an `IdentificationError` is raised before any estimation runs.
+Confounders declared in the DAG are controlled for automatically. If a confounder is absent from the dataframe, an `IdentificationError` is raised before any estimation runs. Some estimators go further at step 4 — per-group decisions, or learning a treatment rule with `learn_policy()`.
 
 ### Decision rules
 
@@ -100,12 +105,16 @@ This creates a `.venv`, installs all dependencies, and installs the package in e
 ### Releasing a new version
 
 ```bash
-uvx bump-my-version bump patch   # 0.1.0 → 0.1.1 (bug fixes)
-uvx bump-my-version bump minor   # 0.1.0 → 0.2.0 (new features)
-uvx bump-my-version bump major   # 0.1.0 → 1.0.0 (breaking changes)
-git push --follow-tags            # triggers publish to PyPI
+make release BUMP=patch   # 0.1.0 → 0.1.1 (bug fixes)
+make release BUMP=minor   # 0.1.0 → 0.2.0 (new features)
+make release BUMP=major   # 0.1.0 → 1.0.0 (breaking changes)
 ```
 
+One command does everything: bumps the version in `pyproject.toml` and `uv.lock`
+(commit + tag), builds the docs, snapshots them into `site/<major.minor>/` (the versioned
+docs site Vercel serves statically), and pushes with tags — which triggers the publish to
+PyPI. It refuses to run if the working tree is dirty or `uv.lock` is out of date.
+
 ### Running tests
 
 ```bash

{formative_ds-2.0.0 → formative_ds-2.2.0}/README.md

@@ -20,23 +20,28 @@ Comprehensive documentation is available at [docs.getformative.dev](https://docs
 
 ### Causal estimation
 
+Every analysis follows the same four steps: assume, estimate, refute, decide.
+
 ```python
 from formative.causal import DAG, OLSObservational
 
+# 1. Encode your causal assumptions as a DAG
 dag = DAG()
 dag.assume("ability").causes("education", "income")
 dag.assume("education").causes("income")
 
-result = OLSObservational(
-    dag,
-    treatment="education",
-    outcome="income"
-).fit(df)
-
+# 2. Estimate the causal effect
+result = OLSObservational(dag, treatment="education", outcome="income").fit(df)
 print(result.summary())
+
+# 3. Refute: stress-test the result's assumptions
+print(result.refute(df).summary())
+
+# 4. Decide: is the treatment worth acting on?
+print(result.decide(cost=8, benefit=15))
 ```
 
-Confounders declared in the DAG are controlled for automatically. If a confounder is absent from the dataframe, an `IdentificationError` is raised before any estimation runs.
+Confounders declared in the DAG are controlled for automatically. If a confounder is absent from the dataframe, an `IdentificationError` is raised before any estimation runs. Some estimators go further at step 4 — per-group decisions, or learning a treatment rule with `learn_policy()`.
 
 ### Decision rules
 
@@ -73,12 +78,16 @@ This creates a `.venv`, installs all dependencies, and installs the package in e
 ### Releasing a new version
 
 ```bash
-uvx bump-my-version bump patch   # 0.1.0 → 0.1.1 (bug fixes)
-uvx bump-my-version bump minor   # 0.1.0 → 0.2.0 (new features)
-uvx bump-my-version bump major   # 0.1.0 → 1.0.0 (breaking changes)
-git push --follow-tags            # triggers publish to PyPI
+make release BUMP=patch   # 0.1.0 → 0.1.1 (bug fixes)
+make release BUMP=minor   # 0.1.0 → 0.2.0 (new features)
+make release BUMP=major   # 0.1.0 → 1.0.0 (breaking changes)
 ```
 
+One command does everything: bumps the version in `pyproject.toml` and `uv.lock`
+(commit + tag), builds the docs, snapshots them into `site/<major.minor>/` (the versioned
+docs site Vercel serves statically), and pushes with tags — which triggers the publish to
+PyPI. It refuses to run if the working tree is dirty or `uv.lock` is out of date.
+
 ### Running tests
 
 ```bash

formative_ds-2.2.0/docs/_static/version_switcher.css

@@ -0,0 +1,11 @@
+.wy-side-nav-search .version-switcher {
+  display: block;
+  width: 100%;
+  margin-top: 0.6em;
+  padding: 0.25em;
+  border: none;
+  border-radius: 3px;
+  font-size: 90%;
+  color: #404040;
+  background-color: #fcfcfc;
+}

formative_ds-2.2.0/docs/_static/version_switcher.js

@@ -0,0 +1,46 @@
+/* Version dropdown for the sidebar.
+ *
+ * Locates the site root from the current URL (pages live under
+ * /<major.minor>/, possibly below a subpath) and fetches versions.json from
+ * there at runtime, so even old, frozen snapshots list all versions published
+ * since. Fails silently when the file is unreachable (e.g. a local docs
+ * build opened directly), leaving the sidebar untouched.
+ */
+(function () {
+  function init() {
+    var match = window.location.pathname.match(/^(.*?)\/(\d+\.\d+)\//);
+    var root = match ? match[1] : "";
+    var current = match ? match[2] : null;
+
+    fetch(root + "/versions.json")
+      .then(function (r) {
+        return r.ok ? r.json() : null;
+      })
+      .then(function (data) {
+        if (!data || !data.versions || !data.versions.length) return;
+        var box = document.querySelector(".wy-side-nav-search");
+        if (!box) return;
+
+        var select = document.createElement("select");
+        select.className = "version-switcher";
+        select.setAttribute("aria-label", "Documentation version");
+        data.versions.forEach(function (v) {
+          var opt = document.createElement("option");
+          opt.value = root + v.url;
+          opt.textContent = "v" + v.version + (v.version === data.latest ? " (latest)" : "");
+          if (v.version === current) opt.selected = true;
+          select.appendChild(opt);
+        });
+        select.addEventListener("change", function () {
+          if (select.value) window.location.href = select.value;
+        });
+        box.appendChild(select);
+      })
+      .catch(function () {});
+  }
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", init);
+  } else {
+    init();
+  }
+})();