brycewang-stanford
diff --git a/‎CHANGELOG.md‎
Lines changed: 81 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 81 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 14 additions & 3 deletions b/‎README.md‎
Lines changed: 14 additions & 3 deletions
diff --git a/‎README_CN.md‎
Lines changed: 14 additions & 3 deletions b/‎README_CN.md‎
Lines changed: 14 additions & 3 deletions
diff --git a/‎docs/guides/causal_mas.md‎
Lines changed: 199 additions & 0 deletions b/‎docs/guides/causal_mas.md‎
Lines changed: 199 additions & 0 deletions
@@ -2,6 +2,87 @@
 
 All notable changes to StatsPAI will be documented in this file.
 
+## [1.4.1] — 2026-04-21 — v3-frontier sprint 3 (AKM SE + Claude thinking + parity suites + docs)
+
+Additive follow-up to v1.4.0.  All v1.4.0 APIs remain stable; new
+functionality is exposed through additive kwargs on existing entry
+points.
+
+### Added — shock-clustered SE for panel shift-share
+
+- **`sp.shift_share_political_panel(..., cluster='shock')`** — new
+  option computes the panel-extended Adão-Kolesár-Morales (2019)
+  variance estimator recommended by Park-Xu (2026) §4.2:
+
+  ```text
+  u_k = Σ_{i, t} s_{ikt} · Z̃_{it} · ε̂_{it}
+  Var(β̂) = Σ_k u_k² / (D̂'_fit · D̃)²
+  ```
+
+  Typically 3× tighter than unit-clustered SEs in settings with 10–100
+  industries.  `diagnostics['akm_se']` exposes the value alongside the
+  chosen cluster type, and `diagnostics['cluster']` is now a
+  human-readable label (`"shock (AKM 2019)"` when the shock estimator
+  is active).
+  [`bartik/political.py`]
+
+### Added — Claude extended-thinking support for Causal MAS
+
+- **`sp.causal_llm.anthropic_client(..., thinking_budget=N)`** — opt
+  into the Claude 4.5 / Opus 4.7 **extended-thinking** API.  The
+  reasoning trace is captured on `client.history[-1]['thinking']` for
+  auditability but is NOT included in the public answer parsed by
+  `causal_mas`.  Compatible with Anthropic's `thinking` /
+  `redacted_thinking` content blocks; both are handled cleanly.
+  Validates `thinking_budget >= 1024` and `< max_tokens` eagerly, so
+  misconfiguration fails loudly before the first API call.
+  [`causal_llm/llm_clients.py`]
+
+### Added — parity + integration test suites
+
+- **`tests/reference_parity/test_assimilation_parity.py`** — 10 checks
+  on the Kalman / particle backends:
+  - static-effect posterior recovery (both backends)
+  - Kalman ↔ particle agreement on three seeds (point + SD within 15%)
+  - monotone posterior variance under `process_var = 0`
+  - particle-filter ESS stays above threshold after resampling
+  - Student-t particle beats Kalman on a contaminated stream
+  - drift tracking without variance blow-up
+  - `assimilative_causal(backend=...)` matches direct-backend calls
+
+- **`tests/integration/test_causal_mas_with_fake_llm.py`** — 11
+  end-to-end integration tests using the deterministic `echo_client`
+  to drive the proposer / critic / domain-expert / synthesiser loop:
+  proposer parsing (newlines + bullets), critic rejection,
+  domain-expert endorsement lifting confidence, transcript
+  auditability, confidence scaling with rounds, role overrides, DAG
+  interop via `sp.dag(...)`, plus three Claude-thinking content-block
+  splitter tests that mock Anthropic responses without requiring the
+  `anthropic` SDK at test time.
+
+### Documentation
+
+Two new MkDocs guides, wired into `mkdocs.yml` nav under
+*DID & Panel Methods* / guides:
+
+- `docs/guides/shift_share_political_panel.md` — full panel-IV recipe
+  including AKM shock-cluster guidance and pretrend workflow.
+- `docs/guides/causal_mas.md` — multi-agent LLM causal discovery,
+  real-SDK integration, Claude thinking-mode walkthrough, and
+  end-to-end pipe into `sp.dag` / `sp.identify`.
+
+### Fixed
+
+- Integration test used `dag.edges()` but `DAG.edges` is a list-of-
+  tuples **attribute** (not a method).  Corrected to `dag.edges`.
+
+### Backwards compatibility
+
+- All v1.4.0 APIs remain stable.  The only new surface is additive
+  kwargs:
+  - `sp.shift_share_political_panel(cluster='shock')`
+  - `sp.causal_llm.anthropic_client(thinking_budget=N)`
+
 ## [1.4.0] — 2026-04-21 — v3-frontier sprint 2 (extensions + LLM SDK + docs)
 
 Follow-up to v1.3.0 covering the four secondary items flagged at the
 
@@ -15,9 +15,20 @@ StatsPAI is the **agent-native** Python package for causal inference and applied
 
 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.
 
-**🎉 NEW in v1.4.0 — v3-frontier Sprint 2: panel shift-share, real-LLM adapters, particle-filter assimilation, 3 new guides**
+**🎉 NEW in v1.4.1 — v3-frontier Sprint 3: AKM shock-clustered SE, Claude extended thinking, parity + integration suites, 2 new guides**
 
-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.
+StatsPAI 1.4.1 is an additive follow-up to 1.4.0 that closes the Sprint 3 items:
+
+- **AKM shock-clustered SE** — `sp.shift_share_political_panel(cluster='shock')` computes the panel-extended Adão-Kolesár-Morales (2019) variance estimator recommended by Park-Xu (2026) §4.2 — typically 3× tighter than unit-clustered SEs in settings with 10–100 industries. `diagnostics['akm_se']` and a human-readable `diagnostics['cluster']` label surface the result.
+- **Claude extended thinking for Causal MAS** — `sp.causal_llm.anthropic_client(thinking_budget=N)` opts into the Claude 4.5 / Opus 4.7 extended-thinking API. The reasoning trace is captured on `client.history[-1]['thinking']` for auditability but is not returned to `causal_mas`. Handles both `thinking` and `redacted_thinking` content blocks.
+- **Parity + integration test suites** — `tests/reference_parity/test_assimilation_parity.py` (10 checks on the Kalman / particle backends, incl. Kalman↔particle agreement and Student-t contamination robustness) and `tests/integration/test_causal_mas_with_fake_llm.py` (11 end-to-end MAS tests using `echo_client` + 3 Claude thinking block-splitter tests mocking the Anthropic SDK).
+- **Two new MkDocs guides** — `docs/guides/shift_share_political_panel.md` (full panel-IV recipe incl. AKM shock-cluster) and `docs/guides/causal_mas.md` (multi-agent LLM causal discovery walkthrough).
+
+All v1.4.0 APIs remain stable; the new surface is strictly additive kwargs.
+
+**Previously in v1.4.0 — v3-frontier Sprint 2: panel shift-share, real-LLM adapters, particle-filter assimilation, 3 new guides**
+
+StatsPAI 1.4.0 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.
 
 | Area | v1.4 Highlights |
 | --- | --- |
@@ -970,7 +981,7 @@ pytest
   author={Wang, Biaoyue},
   year={2026},
   url={https://github.com/brycewang-stanford/statspai},
-  version={1.4.0}
+  version={1.4.1}
 }
 ```
 
 
@@ -15,9 +15,20 @@ StatsPAI 是一个**面向 AI Agent** 的 Python 因果推断与应用计量经
 
 它将 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 中。
 
-**🎉 v1.4.0 新版本 — v3 前沿 Sprint 2：面板 shift-share、真·LLM 适配器、粒子滤波同化、3 篇新指南**
+**🎉 v1.4.1 新版本 — v3 前沿 Sprint 3：AKM 冲击聚类 SE、Claude 扩展思考、对齐与集成测试套件、2 篇新指南**
 
-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 通过显式播种修复。
+StatsPAI 1.4.1 在 1.4.0 基础上做增量更新，关闭 Sprint 3 的 4 项工作：
+
+- **AKM 冲击聚类 SE**：`sp.shift_share_political_panel(cluster='shock')` 实现 Park-Xu（2026）§4.2 推荐的 Adão-Kolesár-Morales（2019）面板扩展方差估计，在 10–100 个行业的设定下通常比单元聚类 SE 紧 3×。`diagnostics['akm_se']` 与可读 `diagnostics['cluster']` 标签同时返回。
+- **Causal MAS 的 Claude 扩展思考**：`sp.causal_llm.anthropic_client(thinking_budget=N)` 接入 Claude 4.5 / Opus 4.7 扩展思考 API。推理轨迹写入 `client.history[-1]['thinking']` 以便审计，但不会出现在 `causal_mas` 解析的正文里。同时处理 `thinking` 与 `redacted_thinking` 两类 content block。
+- **对齐与集成测试套件**：`tests/reference_parity/test_assimilation_parity.py`（10 项 Kalman / 粒子后端校验，含 Kalman↔粒子一致性与 Student-t 污染鲁棒性）与 `tests/integration/test_causal_mas_with_fake_llm.py`（11 个基于 `echo_client` 的 MAS 端到端测试 + 3 个 mock Anthropic SDK 的 Claude thinking block 解析测试）。
+- **两篇新 MkDocs 指南**：`docs/guides/shift_share_political_panel.md`（含 AKM 冲击聚类的完整面板 IV 流程）与 `docs/guides/causal_mas.md`（多智能体 LLM 因果发现完整走查）。
+
+v1.4.0 的所有公开 API 保持稳定；新增面只是附加 kwargs。
+
+**v1.4.0 — v3 前沿 Sprint 2：面板 shift-share、真·LLM 适配器、粒子滤波同化、3 篇新指南**
+
+StatsPAI 1.4.0 是知识地图 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 通过显式播种修复。
 
 | 模块 | v1.4 亮点 |
 | --- | --- |
@@ -364,7 +375,7 @@ pytest
   author={Wang, Biaoyue},
   year={2026},
   url={https://github.com/brycewang-stanford/statspai},
-  version={1.4.0}
+  version={1.4.1}
 }
 ```
 
 
@@ -0,0 +1,199 @@
+# Causal MAS — Multi-Agent LLM Causal Discovery
+
+> arXiv:2509.00987 (September 2025): *Causal MAS — A Survey of Large
+> Language Model Architectures for Discovery and Effect Estimation.*
+
+## 1. Why multi-agent?
+
+Single-prompt LLM causal-discovery pipelines (Kiciman-Sharma 2025) are
+brittle: one model run produces one DAG, and you have no audit trail
+to tell a confident but wrong edge from a cautious correct one.
+
+Causal MAS flips the architecture:
+
+```
+  Proposer  ──► list of candidate edges
+  Critic    ──► rejects edges violating time-order / exclusion / DAG axioms
+  Domain    ──► endorses edges consistent with substantive knowledge
+  Synthesiser ─► accumulates per-edge votes over N rounds
+```
+
+After `N` rounds every edge has a confidence in `[0, 1]`: the fraction
+of rounds in which it survived critic rejection plus a half-point per
+domain endorsement.  The final DAG keeps edges above
+`final_threshold`.
+
+## 2. Quick-start (offline, no API key)
+
+```python
+import statspai as sp
+
+res = sp.causal_llm.causal_mas(
+    variables=['age', 'sex', 'income', 'treatment', 'mortality'],
+    domain='observational mortality cohort',
+    rounds=3,
+    final_threshold=0.5,
+)
+print(res.summary())
+print(res.to_dag_string())
+```
+
+The default backend is the **deterministic heuristic** shipped with
+StatsPAI — it uses the same variable-name pattern matcher as
+`sp.causal_llm.llm_dag_propose`.  You get reproducible output with no
+API key, no network, and no surprises.
+
+## 3. Plugging in a real LLM
+
+```python
+# OpenAI-compatible (default gpt-4o-mini, set OPENAI_API_KEY)
+openai_cli = sp.causal_llm.openai_client(
+    model='gpt-4o-mini',
+    temperature=0.0,     # deterministic for reproducibility
+)
+
+# Anthropic (default claude-opus-4-7, set ANTHROPIC_API_KEY)
+claude_cli = sp.causal_llm.anthropic_client(
+    model='claude-opus-4-7',
+    temperature=0.0,
+)
+
+res = sp.causal_llm.causal_mas(
+    variables=['age', 'sex', 'treatment', 'ldl', 'mi'],
+    domain='cardiovascular prevention in type-2 diabetes',
+    client=claude_cli,
+    rounds=4,
+)
+```
+
+Both clients expose the `LLMClient.chat(role, prompt) -> str`
+interface, so you can supply any other model by wrapping it yourself:
+
+```python
+class MyClient(sp.causal_llm.LLMClient):
+    name = 'my-local-llm'
+    def chat(self, role, prompt):
+        return my_inference_server(role, prompt)  # whatever you have
+```
+
+## 4. Claude extended thinking
+
+Claude 4.5 / Opus 4.7 support extended thinking — the model reasons
+privately for a configurable token budget before producing its public
+answer.  For causal discovery this frequently lifts edge accuracy on
+ambiguous domains (Kiciman-Sharma 2025 §5).
+
+```python
+claude_thinking = sp.causal_llm.anthropic_client(
+    model='claude-opus-4-7',
+    thinking_budget=4096,     # reasoning tokens
+    max_tokens=8192,          # total (must exceed thinking_budget)
+)
+res = sp.causal_llm.causal_mas(
+    variables=[...], client=claude_thinking, rounds=3,
+)
+
+# Inspect the private reasoning trace for audit:
+for entry in claude_thinking.history:
+    if 'thinking' in entry:
+        print(f"[{entry['role']}] thought for "
+              f"{len(entry['thinking'])} chars before answering.")
+```
+
+The reasoning text is stored on `client.history[-1]['thinking']`; it is
+**never** included in the public answer that `causal_mas` parses — so
+your DAG construction is unaffected by the thinking text, you just get
+optional auditability.
+
+## 5. The debate transcript
+
+Every MAS run produces a full `transcript` for auditability:
+
+```python
+for entry in res.transcript[:8]:
+    print(f"[round={entry['round']}] {entry['agent']}:{entry['action']}: "
+          f"{entry['payload']}")
+```
+
+Four entries per round: `propose` (proposer), `reject` (critic),
+`endorse` (domain expert), `score` (synthesiser).  The `score` entry
+records the running edge-count map, so you can replay how confidence
+accumulated.
+
+## 6. Reading the result
+
+```python
+res.edges          # -> list[(parent, child)] surviving final_threshold
+res.confidence     # -> dict{edge -> float in [0, 1]}
+res.roles          # -> dict{variable -> 'treatment' | 'outcome' | 'confounder' | ...}
+res.transcript     # -> list of round-by-round debate events
+res.backend        # -> 'heuristic' | 'openai' | 'anthropic' | 'echo' | user's name
+res.to_dag_string()  # -> 'A -> B; C -> D' for sp.dag(...)
+```
+
+## 7. Pipe into `sp.dag` for identification
+
+```python
+dag_str = res.to_dag_string()
+dag = sp.dag(dag_str)
+
+# Identify the causal effect of 'treatment' on 'mortality':
+ident = sp.identify(dag, treatment='treatment', outcome='mortality')
+print(ident.summary())
+```
+
+If the MAS DAG identifies the effect, `ident` will include an
+adjustment set.  If the DAG has cycles or incomplete roles, the
+`identify` call will tell you which edges to challenge — typically a
+useful signal that the critic round didn't reject enough.
+
+## 8. Role overrides vs. the heuristic
+
+The heuristic variable-name classifier is a starting guess.  Override
+it whenever you know better:
+
+```python
+res = sp.causal_llm.causal_mas(
+    variables=['A', 'B', 'C', 'D'],   # all opaque names
+    treatment='B',
+    outcome='D',
+    confounders=['A'],
+    instruments=['C'],
+    client=my_client,
+    rounds=3,
+)
+```
+
+Explicit kwargs always win over the name heuristic.
+
+## 9. Integration with the rest of StatsPAI
+
+| Use case                                            | Pipeline                                                         |
+|-----------------------------------------------------|------------------------------------------------------------------|
+| Propose a DAG, identify effects, estimate, robustness | `causal_mas` → `sp.dag` → `sp.identify` → `sp.smart.recommend` → `sp.dml` |
+| Build an E-value under unobserved confounding       | `causal_mas` → `sp.causal_llm.llm_unobserved_confounders` → `sp.evalue` |
+| Cross-examine against a domain DAG                  | `causal_mas` → diff `res.edges` with the experts' DAG             |
+| Streaming update of the DAG as new data arrive       | Run `causal_mas` per batch, combine via `sp.dag` edge intersection |
+
+## 10. When *not* to use this
+
+- **High-stakes clinical or legal decisions.**  The heuristic backend
+  is not a substitute for a domain-expert DAG review.  Treat the
+  output as a *proposal* to be audited, not a ground truth.
+- **Very large variable sets (≥ 50 nodes).**  Token budgets and
+  combinatorial explosion of edge proposals degrade quality; cluster
+  the variables first or use a structured DAG-learning algorithm
+  like `sp.pcalg` or `sp.ges`.
+- **Quantitative effect estimation.**  Causal MAS only produces a DAG.
+  For effect magnitudes pipe the DAG into `sp.dml`, `sp.causal_forest`,
+  `sp.metalearner`, etc.
+
+## 11. References
+
+- arXiv:2509.00987 (2025/09).
+  *Causal MAS: A Survey of Large Language Model Architectures for
+  Discovery and Effect Estimation.*
+- Kiciman, E. & Sharma, A. (2025).
+  *Causal Reasoning with Large Language Models.*  arXiv:2402.11068.
+- Anthropic (2025).
+  *Extended Thinking in Claude 4.5 / Opus 4.7.*  Technical report.