Skip to content

Commit 88658a4

Browse files
brycewang-stanfordclaude
brycewang-stanford
and
claude
committed
release: bump to v1.4.0 — docs + CausalForest deflake + CHANGELOG wire-up
Doc / release-note alignment for the v1.4.0 tag plus the CI flake fix that v1.4.0 carries forward: - pyproject.toml + __version__ bumped 1.3.0 → 1.4.0 (owner pre-set) - CHANGELOG.md: the pre-existing [1.4.0] section gains a Fixed entry recording the CausalForest parity-test deflake - README.md / README_CN.md: headline banner rewritten around Sprint-2 (panel shift-share, real-LLM adapters, particle-filter assimilation, 3 new guides), with "v1.3 stable foundation (carried forward)" row - docs/index.md: "Current release" callout + release-highlights table now lead with v1.4.0 - BibTeX version fields in README.md, README_CN.md, and docs/index.md bumped 1.3.0 → 1.4.0 so academic citations match CausalForest parity-test deflake - tests/external_parity/test_causalml_book.py:: test_forest_ate_recovers_average_tau was flaking on ubuntu-latest + Python 3.10 because only the data-gen RNG was seeded — the forest's bootstrap + honest splits were unseeded, so the ATE estimate varied ±0.3 across the matrix and the |ATE - 0.5| < 0.3 tolerance occasionally tripped. - Fixed by passing random_state=0 + n_estimators=300 and bumping n=600 → n=1500 so the test is reproducibly deterministic on every OS × Python combo. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 59eb3fc commit 88658a4

28 files changed

Lines changed: 2234 additions & 74 deletions

‎CHANGELOG.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,86 @@
22

33
All notable changes to StatsPAI will be documented in this file.
44

5+
## [1.4.0] — 2026-04-21 — v3-frontier sprint 2 (extensions + LLM SDK + docs)
6+
7+
Follow-up to v1.3.0 covering the four secondary items flagged at the
8+
end of Sprint 1.
9+
10+
### Added — panel-shift-share extension
11+
12+
- **`sp.shift_share_political_panel`** — multi-period extension of
13+
`sp.shift_share_political` per Park & Xu (2026) §4.2. Handles
14+
time-varying shares **and** time-varying shocks, runs pooled 2SLS
15+
with unit / time / two-way fixed effects, and reports a per-period
16+
event-study table plus aggregate Rotemberg top-K weights. Recovers
17+
τ = 0.30 within 0.003 on a 30 × 4 synthetic panel.
18+
[`bartik/political.py`]
19+
20+
### Added — real-LLM adapters for Causal MAS
21+
22+
- **`sp.causal_llm.openai_client`** — adapter over the `openai>=1.0`
23+
Python SDK; supports custom `base_url` for Azure / vLLM / Ollama.
24+
- **`sp.causal_llm.anthropic_client`** — adapter over the
25+
`anthropic>=0.30` Messages API; defaults to `claude-opus-4-7`.
26+
- **`sp.causal_llm.echo_client`** — deterministic scripted-response
27+
client for offline unit testing.
28+
- All three implement a single-method `LLMClient` protocol and
29+
integrate with `sp.causal_llm.causal_mas(client=...)` via the
30+
existing `chat(role, prompt)` interface. Lazy-imports the SDKs so
31+
the core package has zero new runtime dependencies.
32+
[`causal_llm/llm_clients.py`]
33+
34+
### Added — particle-filter assimilation backend
35+
36+
- **`sp.assimilation.particle_filter`** — bootstrap-SIR particle
37+
filter with systematic resampling (Gordon-Salmond-Smith 1993;
38+
Douc-Cappé 2005). Handles non-Gaussian priors, heavy-tailed
39+
observation noise, and nonlinear dynamics via pluggable
40+
`prior_sampler` / `transition_sampler` / `observation_log_pdf`
41+
callbacks. Agrees with the exact Kalman filter to ~0.003 under
42+
Gaussian DGPs.
43+
- **`sp.assimilative_causal(..., backend='particle')`** — the
44+
end-to-end wrapper now routes to the particle filter when
45+
`backend='particle'`.
46+
[`assimilation/particle.py`]
47+
48+
### Documentation
49+
50+
Three new MkDocs guides covering the v3-frontier estimators:
51+
52+
- `docs/guides/synth_experimental.md` — Abadie-Zhao inverse-SC workflow.
53+
- `docs/guides/harvest_did.md` — Borusyak-Hull-Jaravel harvesting DID.
54+
- `docs/guides/assimilative_ci.md` — Nature Comms 2026 streaming CI
55+
with both Kalman and particle backends.
56+
57+
All three are wired into `mkdocs.yml` nav under the *DID & Panel
58+
Methods* / guides section.
59+
60+
### Registry + agent schema
61+
62+
- 5 new hand-written `FunctionSpec` entries:
63+
`shift_share_political_panel`, `particle_filter`, `openai_client`,
64+
`anthropic_client`, `echo_client`.
65+
66+
### Code-quality pass (Sprint 1 audit)
67+
68+
- Removed 20 unused imports / shadow variables across the Sprint 1
69+
modules identified by `pyflakes` (`did/harvest.py`,
70+
`bcf/ordinal.py`, `bcf/factor_exposure.py`,
71+
`causal_llm/causal_mas.py`, `bartik/political.py`,
72+
`assimilation/kalman.py`, `target_trial/report.py`).
73+
74+
### Fixed
75+
76+
- `tests/external_parity/test_causalml_book.py::test_forest_ate_recovers_average_tau`
77+
was flaking on `ubuntu-latest + Python 3.10` because only the
78+
data-generating RNG was seeded — the causal forest's bootstrap +
79+
honest-split sampling was unseeded, so the ATE estimate varied
80+
by ±0.3 between OS / Python matrix entries and the
81+
`|ATE - 0.5| < 0.3` tolerance occasionally failed. Fixed by
82+
passing `random_state=0` + `n_estimators=300` + bumping `n` to
83+
1 500 so the test is fully deterministic across the matrix.
84+
585
## [1.3.0] — 2026-04-21 — v3-frontier sprint (Sprint 1 of the 知识地图 v3 roadmap)
686

787
Builds on top of the v1.2.0 doc-alignment work by implementing the

‎README.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,19 @@ StatsPAI is the **agent-native** Python package for causal inference and applied
1515

1616
It brings R's [Causal Inference Task View](https://cran.r-project.org/web/views/CausalInference.html) (fixest, did, rdrobust, gsynth, DoubleML, MatchIt, CausalImpact, ...) and Stata's core econometrics commands into a single, consistent Python API.
1717

18-
**🎉 NEW in v1.0.1 — Stable API release: research-frontier capstone + independent-review correctness pass**
18+
**🎉 NEW in v1.4.0 — v3-frontier Sprint 2: panel shift-share, real-LLM adapters, particle-filter assimilation, 3 new guides**
1919

20-
StatsPAI 1.0 is the capstone of three years of development. Semantic-versioning starts here: the public API is the set of names in `statspai.__all__` as of this tag. **Every Critical / High / Medium finding from the independent code-review-expert pass has been fixed and pinned by regression tests** — including the Katz RR SE, inverse-variance Cochran Q, PCMCI Fisher-z effective-sample-size, cluster-robust cohort-anchored DiD, TMLE regime-offset, real HDR conformal density, IPW-based EWM bridge, MVMR conditional F, BCF point/CI alignment, conformal-fair small-group fallback, and the LLM-prompt sanitization. v1.0.1 additionally closes the two `NEEDS_VERIFICATION` items with paper-grounded implementations (Abadie κ-weighted complier QTE and a real dual-path PCI bridge).
20+
StatsPAI 1.4 is Sprint 2 of the 知识地图 v3 roadmap. Closes the four secondary items flagged at the end of Sprint 1: multi-period Park-Xu political shift-share, real OpenAI / Anthropic LLM adapters for the Causal MAS discovery agent, a particle-filter backend for `causal_kalman` to handle non-Gaussian priors and nonlinear dynamics, and three new MkDocs guides covering the v3 frontier. 20 unused-import cleanups across Sprint 1 modules. One CI flake (CausalForest ATE parity test) deflaked by seeding the forest explicitly.
2121

22-
| Area | v1.0 Highlights |
22+
| Area | v1.4 Highlights |
2323
| --- | --- |
24-
| **Three-school completion** (v0.9.17 → v1.0) | `sp.epi` (OR / RR / Mantel-Haenszel / standardization / Bradford-Hill / ROC / kappa), `sp.longitudinal` (unified MSM / g-formula / IPW dispatcher + safe regime DSL), `sp.question` (estimand-first `causal_question()` DSL with `identify → estimate → report`), full MR suite (`mr_presso`, `mr_steiger`, `mr_radial`, `mr_mode`, `mr_f_statistic`, `mr_multivariable`, `mr_mediation`, `mr_bma`), DAG `recommend_estimator()`, unified `result.sensitivity()`, `preregister()` / `load_preregister()`. |
25-
| **Research-frontier capstone** (v1.0) | **`sp.bridge`** (6 bridging theorems: DiD≡SC, EWM≡CATE, CB≡IPW, KinkRDD, DR-calib, Surrogate≡PCI). **`sp.fairness`** (Kusner counterfactual fairness + demographic-parity / eq-odds / audit). **`sp.surrogate`** (Athey-Chetty surrogate index + Ghassami 2024 + Imbens-Kallus-Mao 2026). **Time-series causal discovery** (`pcmci`, `lpcmci`, `dynotears`). **Conformal frontiers** (debiased / density-HDR / fair / multi-DP). **Proximal frontiers** (fortified / bidirectional / MTP / proxy selection). **Sequential SDID**, **BCF longitudinal**, **LTMLE survival**, **ML bounds**. |
26-
| **Target Trial Emulation flagship** | JAMA 2022 7-component protocol + **JAMA/BMJ 2025 TARGET Statement 21-item reporting checklist** auto-filled from the protocol + result pair. `target_trial_report(result, fmt='markdown'/'latex'/'target')` renders a STROBE-compatible paper block. |
27-
| **Agent-native platform** | `sp.list_functions()` / `sp.describe_function()` / `sp.function_schema()` expose OpenAI/Anthropic tool-calling schemas for 785+ registered estimators. `sp.agent.mcp_server` ships a scaffold MCP server so external LLMs can call every StatsPAI function via natural-language tool invocation. |
28-
| **Independent review transparency** | 3 Critical + 5 High + 6 Medium + 2 Low findings from code-review-expert, documented and closed in the v1.0.0 + v1.0.1 commits. 2 706+ tests passing, zero regressions across the pre-existing suite. Pinning regression tests in `tests/test_v100_review_fixes.py` and `tests/test_v101_verified_fixes.py` lock every correctness fix. |
24+
| **Panel shift-share IV** | **`sp.shift_share_political_panel`** — Park-Xu (2026) §4.2 multi-period extension: time-varying shares + time-varying shocks, pooled 2SLS with unit / time / two-way FE, per-period event-study table + aggregate Rotemberg top-K. Recovers τ = 0.30 within 0.003 on synthetic 30×4 panels. |
25+
| **Real-LLM adapters (Causal MAS)** | **`sp.causal_llm.openai_client`** — OpenAI SDK ≥ 1.0 (supports Azure / vLLM / Ollama via `base_url`). **`sp.causal_llm.anthropic_client`** — Anthropic Messages API ≥ 0.30, defaults to `claude-opus-4-7`. **`sp.causal_llm.echo_client`** — deterministic scripted-response client for offline tests. Lazy-imported SDKs → zero new runtime deps on the core package. |
26+
| **Particle-filter assimilation** | **`sp.assimilation.particle_filter`** — bootstrap-SIR particle filter with systematic resampling (Gordon-Salmond-Smith 1993; Douc-Cappé 2005). Non-Gaussian priors, heavy-tailed observation noise, nonlinear dynamics via pluggable callbacks. Agrees with exact Kalman to ~0.003 under Gaussian DGPs. **`sp.assimilative_causal(..., backend='particle')`** routes the end-to-end wrapper. |
27+
| **Documentation (v3 frontier guides)** | `docs/guides/synth_experimental.md` (Abadie-Zhao inverse-SC workflow), `docs/guides/harvest_did.md` (Borusyak-Hull-Jaravel harvesting DID), `docs/guides/assimilative_ci.md` (Nature Comms 2026 streaming CI, Kalman + particle backends). Wired into `mkdocs.yml` nav. |
28+
| **v1.3 stable foundation (carried forward)** | 11 2025-2026 frontier methods from Sprint 1: `synth_experimental_design`, `rdrobust(..., bootstrap='rbc')`, `evidence_without_injustice`, `target_trial.to_paper(fmt='jama'/'bmj')`, `harvest_did`, `bcf_ordinal`, `bcf_factor_exposure`, `causal_mas`, `shift_share_political`, `causal_kalman`. All v1.0 capstone surfaces (`sp.bridge`, `sp.fairness`, `sp.surrogate`, `sp.epi`, `sp.longitudinal`, `sp.question`, full MR suite, TARGET checklist) remain intact. |
29+
| **Agent-native platform** | `sp.list_functions()` / `sp.describe_function()` / `sp.function_schema()` expose OpenAI/Anthropic tool-calling schemas for 874+ registered estimators. 5 new hand-written `FunctionSpec` entries this release. `sp.agent.mcp_server` MCP scaffold lets external LLMs call every StatsPAI function via natural-language tool invocation. |
30+
| **CI/CD hygiene** | `tabulate` hard-dep from v1.3.0 carried forward. Deflaked `test_forest_ate_recovers_average_tau` by seeding the forest explicitly (`random_state=0`, `n_estimators=300`, larger `n`). 2 699+ tests passing across all OS × Python matrix entries. |
2931

3032
**Previously in v0.9.2 — Decomposition Analysis**: **18 first-class decomposition methods across 13 modules (~6,200 LOC, 54 tests)**, unified under `sp.decompose(method=...)`. Mean (Blinder-Oaxaca/Gelbach/Fairlie/Bauer-Sinning/Yun), distributional (RIF/FFL/DFL/Machado-Mata/Melly/CFM), inequality (Theil/Atkinson/Dagum/Shapley/Lerman-Yitzhaki), demographic (Kitagawa/Das-Gupta), and causal (gap_closing/mediation_decompose/disparity_decompose). Closed-form influence functions for Theil/Atkinson, weighted O(n log n) Dagum Gini, cross-method consistency checks.
3133

@@ -968,7 +970,7 @@ pytest
968970
author={Wang, Biaoyue},
969971
year={2026},
970972
url={https://github.com/brycewang-stanford/statspai},
971-
version={1.0.1}
973+
version={1.4.0}
972974
}
973975
```
974976

‎README_CN.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,19 @@ StatsPAI 是一个**面向 AI Agent** 的 Python 因果推断与应用计量经
1515

1616
它将 R 的 [Causal Inference Task View](https://cran.r-project.org/web/views/CausalInference.html)（fixest、did、rdrobust、gsynth、DoubleML、MatchIt、CausalImpact、sfaR、lme4、oaxaca、ddecompose……）和 Stata 的核心计量命令（`frontier`、`xtfrontier`、`mixed`、`meglm`、`mixlogit`、`ivqreg`……），统一到一个一致的 Python API 中。
1717

18-
**🎉 v1.0.1 新版本 — 正式稳定版：研究前沿 capstone + 独立代码审查正确性修复**
18+
**🎉 v1.4.0 新版本 — v3 前沿 Sprint 2：面板 shift-share、真·LLM 适配器、粒子滤波同化、3 篇新指南**
1919

20-
StatsPAI 1.0 是三年研发的 capstone 版本。语义化版本号从这里开始：公开 API 是 `statspai.__all__` 在此 tag 时点的符号集合。**独立 code-review-expert 审查发现的全部 Critical / High / Medium 问题已全部修复并由回归测试锁死**，包括 Katz RR 标准误、逆方差加权 Cochran Q、PCMCI Fisher-z 有效样本量、cluster-robust 队列锚定 DiD、TMLE regime-offset、真正的 HDR 条件密度 conformal、基于 IPW 的 EWM bridge、MVMR 条件 F 统计量、BCF 点估计/CI 对齐、fair-conformal 小群 fallback 以及 LLM prompt 注入清洗。v1.0.1 额外关闭了两项 `NEEDS_VERIFICATION` 标记的遗留项（Abadie κ-加权 complier QTE 与真正的对偶路径 PCI bridge）。
20+
StatsPAI 1.4 是知识地图 v3 路线图的 Sprint 2，关闭了 Sprint 1 末尾的 4 个次要项：Park-Xu 政治 shift-share 多期扩展、Causal MAS 发现 Agent 的真·OpenAI/Anthropic 适配器、`causal_kalman` 的粒子滤波后端（处理非高斯先验与非线性动力学），以及 3 篇覆盖 v3 前沿的 MkDocs 指南。Sprint 1 模块的 20 处 unused-import 清理。CI 上 1 个 CausalForest ATE parity 测试的 flake 通过显式播种修复。
2121

22-
| 模块 | v1.0 亮点 |
22+
| 模块 | v1.4 亮点 |
2323
| --- | --- |
24-
| **三派融合** (v0.9.17 → v1.0) | `sp.epi`（OR / RR / Mantel-Haenszel / 标准化 / Bradford-Hill / ROC / kappa）、`sp.longitudinal`（MSM / g-formula / IPW 统一调度 + 安全 regime DSL）、`sp.question`（estimand-first `causal_question()` DSL，`identify → estimate → report` 三段式）、MR 全家桶（`mr_presso`、`mr_steiger`、`mr_radial`、`mr_mode`、`mr_f_statistic`、`mr_multivariable`、`mr_mediation`、`mr_bma`）、DAG `recommend_estimator()`、统一 `result.sensitivity()`、`preregister()` / `load_preregister()` 预注册。 |
25-
| **研究前沿 capstone** (v1.0) | **`sp.bridge`**（6 个 bridging theorem：DiD≡SC、EWM≡CATE、CB≡IPW、KinkRDD、DR-calib、Surrogate≡PCI）。**`sp.fairness`**（Kusner 反事实公平性 + demographic-parity / eq-odds / 审计）。**`sp.surrogate`**（Athey-Chetty 代理指数 + Ghassami 2024 + Imbens-Kallus-Mao 2026）。**时序因果发现**（`pcmci`、`lpcmci`、`dynotears`）。**conformal 前沿**（debiased / density-HDR / fair / multi-DP）。**proximal 前沿**（fortified / bidirectional / MTP / proxy selection）。**Sequential SDID**、**BCF 纵向**、**LTMLE 生存**、**ML bounds**。 |
26-
| **Target Trial Emulation flagship** | JAMA 2022 7-component protocol + **JAMA/BMJ 2025 TARGET Statement 21-item 报告清单**从 protocol+result 自动填充。`target_trial_report(result, fmt='markdown'/'latex'/'target')` 生成 STROBE 合规的论文 Methods + Results 段落。 |
27-
| **Agent-native 平台** | `sp.list_functions()` / `sp.describe_function()` / `sp.function_schema()` 为 785+ 个已注册的估计量提供 OpenAI/Anthropic tool-calling schema。`sp.agent.mcp_server` 提供 MCP 服务器脚手架，外部 LLM 可通过自然语言工具调用每个 StatsPAI 函数。 |
28-
| **独立审查透明度** | 3 Critical + 5 High + 6 Medium + 2 Low 全部记录并在 v1.0.0 + v1.0.1 commits 中闭环。**2 706+ 测试全部通过，已有测试零回归**。所有正确性修复均由 `tests/test_v100_review_fixes.py` 与 `tests/test_v101_verified_fixes.py` pinning 回归测试锁死。 |
24+
| **面板 shift-share IV** | **`sp.shift_share_political_panel`** — Park-Xu（2026）§4.2 多期扩展：时变 shares + 时变 shocks、单元/时间/双向 FE 池化 2SLS、按期 event-study 表 + 总体 Rotemberg top-K。30×4 合成面板上恢复 τ = 0.30 误差 0.003。 |
25+
| **真·LLM 适配器（Causal MAS）** | **`sp.causal_llm.openai_client`** — OpenAI SDK ≥ 1.0（通过 `base_url` 支持 Azure / vLLM / Ollama）。**`sp.causal_llm.anthropic_client`** — Anthropic Messages API ≥ 0.30，默认 `claude-opus-4-7`。**`sp.causal_llm.echo_client`** — 离线单测用的确定性脚本客户端。SDK lazy-import → 核心包零新增运行时依赖。 |
26+
| **粒子滤波同化** | **`sp.assimilation.particle_filter`** — 带系统重采样的 bootstrap-SIR 粒子滤波（Gordon-Salmond-Smith 1993；Douc-Cappé 2005）。非高斯先验、重尾观测噪声、非线性动力学通过可插拔回调实现。高斯 DGP 下与精确 Kalman 一致到 ~0.003。**`sp.assimilative_causal(..., backend='particle')`** 端到端 wrapper 路由到粒子滤波。 |
27+
| **文档（v3 前沿指南）** | `docs/guides/synth_experimental.md`（Abadie-Zhao 反向 SC 流程）、`docs/guides/harvest_did.md`（Borusyak-Hull-Jaravel harvest DID）、`docs/guides/assimilative_ci.md`（Nature Comms 2026 流式 CI，Kalman + 粒子后端）。已挂到 `mkdocs.yml` 导航。 |
28+
| **v1.3 稳定基础（延续）** | Sprint 1 的 11 个 2025-2026 前沿方法：`synth_experimental_design`、`rdrobust(..., bootstrap='rbc')`、`evidence_without_injustice`、`target_trial.to_paper(fmt='jama'/'bmj')`、`harvest_did`、`bcf_ordinal`、`bcf_factor_exposure`、`causal_mas`、`shift_share_political`、`causal_kalman`。所有 v1.0 capstone 面（`sp.bridge`、`sp.fairness`、`sp.surrogate`、`sp.epi`、`sp.longitudinal`、`sp.question`、MR 全家桶、TARGET 清单）保持不变。 |
29+
| **Agent 平台** | `sp.list_functions()` / `sp.describe_function()` / `sp.function_schema()` 为 874+ 估计量提供 OpenAI/Anthropic tool-calling schema。本版本新增 5 个手工 `FunctionSpec`。`sp.agent.mcp_server` MCP 脚手架让外部 LLM 可自然语言调用每个函数。 |
30+
| **CI/CD 卫生** | v1.3.0 的 `tabulate` 硬依赖延续。通过显式播种（`random_state=0`、`n_estimators=300`、扩 `n`）修复 `test_forest_ate_recovers_average_tau` flake。2 699+ 测试在所有 OS × Python matrix 上通过。 |
2931

3032
**v0.6 新功能**：`sp.interactive(fig)` —— 类似 Stata Graph Editor 的 WYSIWYG 图表编辑器，支持 29 种学术主题、实时预览、自动生成可复现代码。
3133

@@ -362,7 +364,7 @@ pytest
362364
author={Wang, Biaoyue},
363365
year={2026},
364366
url={https://github.com/brycewang-stanford/statspai},
365-
version={1.0.1}
367+
version={1.4.0}
366368
}
367369
```
368370

0 commit comments

Comments
 (0)