refactor(core): extract shared safe_logit_fit/predict primitive (CLAUDE.md §4)

front_door and principal_strat carried byte-identical statsmodels-logit
wrappers (fit + predict). Consolidate into core/_glm_fit.py; the module-level
_logit_fit/_logit_safe/_logit_predict names stay as thin delegators (mockable).
Behavior-preserving (28 tests incl. A1 fallback tests pass). The custom-IRLS /
sklearn logits in censoring/gformula/longitudinal/ivmte_lp/tmle are
deliberately different solvers and are left for a parity-quiet unification.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: brycewang-stanford

README.md

@@ -895,6 +895,9 @@ With optional dependencies:
 ```bash
 pip install statspai[plotting]    # matplotlib, seaborn
 pip install statspai[fixest]      # pyfixest for high-dimensional FE
+pip install statspai[bayes]       # PyMC + ArviZ for Bayesian estimators
+pip install statspai[tune]        # Optuna for tuned meta-learners / Auto-CATE
+pip install statspai[rd-cct]      # rdrobust for exact CCT RD parity
 pip install statspai[deepiv]      # PyTorch for DeepIV
 pip install statspai[neural]      # PyTorch for TARNet/CFRNet/DragonNet
 pip install statspai[text]        # sentence-transformers for sbert text embeddings
@@ -909,7 +912,7 @@ installation.
 
 **Requirements:** Python >= 3.9
 
-**Core dependencies:** NumPy, SciPy, Pandas, statsmodels, scikit-learn, linearmodels, patsy, openpyxl, python-docx
+**Core dependencies:** NumPy, SciPy, Pandas, statsmodels, scikit-learn, linearmodels, formulaic, numba, patsy, openpyxl, xlsxwriter, python-docx, tabulate
 
 ---
 

SUPPORT.md

@@ -8,7 +8,7 @@ For "**how do I**", "**which estimator should I use**", "**why does my result di
 
 - **GitHub Discussions** — <https://github.com/brycewang-stanford/StatsPAI/discussions>
   - Best place for open-ended questions, methodological discussion, and Q&A that may help future users.
-  - Please search existing threads first — many common questions are already answered.
+  - Please search existing threads first — many common questions may already be answered.
 
 When asking, please include:
 

docs/getting-started.md

@@ -16,6 +16,8 @@ backends only when you want them:
 ```bash
 pip install "StatsPAI[plotting]"   # matplotlib / seaborn / plotly figures
 pip install "StatsPAI[bayes]"      # PyMC + ArviZ for Bayesian estimators
+pip install "StatsPAI[tune]"       # Optuna for tuned meta-learners / Auto-CATE
+pip install "StatsPAI[rd-cct]"     # rdrobust for exact CCT RD parity
 pip install "StatsPAI[performance]"# JAX backend for fast feols / bootstrap
 ```
 

docs/joss_reviewer_guide.md

@@ -8,7 +8,8 @@ checking representative functionality without running the full test suite.
 StatsPAI is a Python package for causal inference and applied econometrics. The
 core package is pip-installable, ships small teaching datasets, and can be
 tested offline. Optional extras cover plotting, pyfixest integration, neural
-causal estimators, JAX-backed workloads, and Bayesian workflows.
+causal estimators, JAX-backed workloads, Bayesian workflows, Optuna tuning,
+and exact Calonico-Cattaneo-Titiunik RD parity via `rdrobust`.
 
 ## Install
 
@@ -25,6 +26,12 @@ For review from a repository checkout:
 python -m pip install -e ".[dev,plotting]"
 ```
 
+The core install declares the runtime dependencies in `pyproject.toml`:
+NumPy, SciPy, Pandas, statsmodels, scikit-learn, linearmodels, formulaic,
+numba, patsy, openpyxl, xlsxwriter, python-docx, and tabulate. Optional extras
+are named `plotting`, `fixest`, `deepiv`, `neural`, `performance`, `bayes`,
+`tune`, `rd-cct`, `text`, and `docs`.
+
 ## Smoke Test
 
 ```bash

docs/joss_validation_dossier.md

@@ -81,10 +81,10 @@ and reviewer-verifiable examples rather than published downstream citations.
 ## Public Distribution And Community Signals
 
 StatsPAI is publicly distributed on PyPI and archived on Zenodo. The GitHub
-repository has public stars, forks, issue templates, discussions links,
-contribution instructions, support instructions, release notes, and CI status
-checks. These are treated as community-readiness and public-interest signals,
-not as evidence of independent scholarly adoption.
+repository has public stars, forks, issue templates, a dedicated support
+discussion channel, contribution instructions, support instructions, release
+notes, and CI status checks. These are treated as community-readiness and
+public-interest signals, not as evidence of independent scholarly adoption.
 
 The public fork list is available through GitHub at
 <https://github.com/brycewang-stanford/StatsPAI/forks>. As of 2026-05-29, the

docs/reference/index.md

@@ -6,6 +6,8 @@ namespace. Reference pages are grouped by methodological area:
 | Area | Page | Flagship functions |
 | --- | --- | --- |
 | Difference-in-differences | [did](did.md) | `callaway_santanna`, `aggte`, `sun_abraham`, `bjs`, `dcdh`, `etwfe`, `cs_report`, `honest_did`, `breakdown_m` |
+| Instrumental variables | [iv](iv.md) | `iv`, `ivreg`, `iv_diag`, `iv_compare`, `kernel_iv`, `continuous_iv_late`, `ivdml`, `npiv`, `mte` |
+| Matching / balancing | [matching](matching.md) | `match`, `ebalance`, `cbps`, `genmatch`, `sbw`, `overlap_weights`, `balance_diagnostics`, `love_plot` |
 | Regression discontinuity | [rd](rd.md) | `rdrobust`, `rd2d`, `rkd`, `rdit`, `rdhonest`, `rdrandinf`, `rdpower`, `rd_forest`, `rdsummary` |
 | Synthetic control | [synth](synth.md) | `synth`, `sdid`, `ascm`, `bayesian_synth`, `bsts_synth`, `penscm`, `synth_compare`, `synth_recommend`, `synth_report` |
 | Decomposition | [decomposition](decomposition.md) | `decompose`, `oaxaca`, `gelbach`, `ffl_decompose`, `dfl_decompose`, `machado_mata`, `shapley_inequality`, `gap_closing` |
@@ -18,6 +20,7 @@ namespace. Reference pages are grouped by methodological area:
 | Spatial econometrics | [spatial](spatial.md) | `spatial_weights`, `moran_i`, `geary_c`, `sar`, `sem`, `sdm`, `gwr`, `mgwr`, `spatial_panel`, `spatial_did` |
 | Time series | [timeseries](timeseries.md) | `arima`, `var`, `bvar`, `garch`, `cointegration`, `local_projections`, `structural_break` |
 | Survival | [survival](survival.md) | `cox`, `aft`, `frailty`, `kaplan_meier`, `log_rank_test`, `competing_risks` |
+| Agent-native workflows | [smart](smart.md) | `detect_design`, `preflight`, `audit`, `examples`, `session`, `brief`, `bib_for` |
 
 Every result object follows the same contract:
 

docs/reference/iv.md

@@ -106,3 +106,33 @@ The core requirements are **relevance** (a non-zero first stage),
 **exclusion** (the instrument affects the outcome only through the treatment),
 **exogeneity / independence** of the instrument, and — for a LATE
 interpretation — **monotonicity** (no defiers).
+
+## Method-level API
+
+The public top-level entry points used in examples and agent workflows are
+documented here explicitly; the exhaustive namespace listing remains available
+under [Full API reference -> iv](api/iv.md).
+
+### `sp.iv(...)`
+
+::: statspai.regression.iv.iv
+
+### `sp.ivreg(...)`
+
+::: statspai.regression.iv.ivreg
+
+### `sp.kernel_iv(...)`
+
+::: statspai.iv.kernel_iv
+
+### `sp.continuous_iv_late(...)`
+
+::: statspai.iv.continuous_iv_late
+
+### `sp.iv_diag(...)`
+
+::: statspai.iv.iv_diag
+
+### `sp.iv_compare(...)`
+
+::: statspai.iv.iv_compare

docs/reference/matching.md

@@ -0,0 +1,79 @@
+# Matching and balancing
+
+`statspai.matching` covers classical matching, balancing weights, diagnostics,
+and Love plots behind a unified `sp.match(...)` dispatcher plus standalone
+estimator functions for power users.
+
+See also the decision guide:
+[Choosing a matching estimator](../guides/choosing_matching_estimator.md), and
+the exhaustive auto-generated listing under
+[Full API reference -> matching](api/matching.md).
+
+## Choosing an entry point
+
+```python
+import statspai as sp
+
+# Default nearest-neighbour propensity-score matching.
+r = sp.match(
+    df,
+    y="earnings",
+    treat="training",
+    covariates=["age", "education", "earnings_pre"],
+)
+
+# Balancing-weight estimators are available through method=...
+r_ebal = sp.match(df, y="earnings", treat="training",
+                  covariates=["age", "education"], method="ebalance")
+
+# ...or as standalone functions with estimator-specific options.
+w = sp.overlap_weights(df, treat="training",
+                       covariates=["age", "education", "earnings_pre"])
+diag = sp.balance_diagnostics(df, treat="training",
+                              covariates=["age", "education"],
+                              weights=w.weights)
+```
+
+## Estimator families
+
+| Family | Functions | Typical use |
+| --- | --- | --- |
+| Classical matching | `sp.match(method="nearest" | "psm" | "mahalanobis" | "cem" | "stratify")` | Matched samples or subclassification with transparent design choices. |
+| Entropy / CBPS / SBW | `sp.ebalance`, `sp.cbps`, `sp.sbw` | Direct covariate balance by reweighting. |
+| Genetic matching | `sp.genmatch` | Automated balance search over covariate weights. |
+| Overlap weights | `sp.overlap_weights` | ATE-style overlap-population estimands with stable weights. |
+| Diagnostics | `sp.balance_diagnostics`, `sp.love_plot` | Standardised mean differences, variance ratios, and Love plots. |
+
+## Method-level API
+
+### `sp.match(...)`
+
+::: statspai.match
+
+### `sp.ebalance(...)`
+
+::: statspai.ebalance
+
+### `sp.cbps(...)`
+
+::: statspai.cbps
+
+### `sp.genmatch(...)`
+
+::: statspai.genmatch
+
+### `sp.sbw(...)`
+
+::: statspai.sbw
+
+### `sp.overlap_weights(...)`
+
+::: statspai.overlap_weights
+
+### `sp.balance_diagnostics(...)`
+
+::: statspai.balance_diagnostics
+
+### `sp.love_plot(...)`
+
+::: statspai.love_plot

docs/reference/smart.md

@@ -72,3 +72,37 @@ Calibration card: top-method `verify_score` is typically 85–95 on
 clean DGPs (RD lower at ≈ 74 due to local-polynomial bootstrap
 variance). `sp.verify_benchmark(...)` runs verify against synthetic
 DGPs to calibrate what threshold constitutes "trust it".
+
+## Agent-native method-level API
+
+These functions are guide-friendly, but they are also public API calls used by
+agents and notebook workflows. Their docstrings are exposed here so the
+Reference navigation includes method-level details.
+
+### `sp.detect_design(...)`
+
+::: statspai.detect_design
+
+### `sp.preflight(...)`
+
+::: statspai.preflight
+
+### `sp.audit(...)`
+
+::: statspai.audit
+
+### `sp.examples(...)`
+
+::: statspai.examples
+
+### `sp.session(...)`
+
+::: statspai.session
+
+### `sp.brief(...)`
+
+::: statspai.brief
+
+### `sp.bib_for(...)`
+
+::: statspai.bib_for

mkdocs.yml

@@ -120,6 +120,7 @@ nav:
       - "Overview": reference/index.md
       - "Difference-in-differences": reference/did.md
       - "Instrumental variables": reference/iv.md
+      - "Matching / balancing": reference/matching.md
       - "Panel data": reference/panel.md
       - "Regression discontinuity": reference/rd.md
       - "Synthetic control": reference/synth.md