feat(agent): expand agent-native tooling and schemas

Author: brycewang-stanford

CHANGELOG.md

@@ -32,6 +32,15 @@ All notable changes to StatsPAI will be documented in this file.
   `sp.llm_dag_propose` (and friends) can reuse the connected agent's own
   model with no extra API key, falling back to the deterministic heuristic
   when sampling is unavailable.
+- **`interpret_result` MCP tool** — natural-language explanation of a
+  fitted result from its cached handle. Wires `resolve_llm_client()` into
+  the server's tool-dispatch path: when the client advertised sampling it
+  reuses the agent's own model (grounded in the result's own numbers — the
+  model is told not to invent estimates), and degrades to a deterministic
+  structured brief otherwise. Mid-call sampling failures fall back loudly
+  (the error is surfaced in `sampling_error`, never swallowed). Optional
+  `question` / `audience` knobs; exposed as a dataless tool so strict-schema
+  clients dispatch it without a `data_path`.
 - **Auto-tool citation enrichment** — `_enrichment.build_citations` now
   falls back to verified citation tokens in a function's registry
   `reference` field, so hundreds of carded estimators carry citations in

docs/agent_cards_spec.md

@@ -196,7 +196,7 @@ nothing.
 The floor in
 [`scripts/agent_card_coverage_floor.json`](../scripts/agent_card_coverage_floor.json)
 tracks 15 counters: per-tier totals + per-field counts + per-validation-status
-counts for `certified` / `validated`.  Each may only go up.  To
+counts for `certified` / `validated-or-better`.  Each may only go up.  To
 intentionally raise the bar, run:
 
 ```bash

docs/cookbook.md

@@ -0,0 +1,137 @@
+# Cookbook — recipes by research question
+
+Find the method by the question you are actually asking, not by its textbook
+name. Each recipe is a minimal, runnable starting point; follow the linked
+guide or [API reference](reference/api/index.md) for the full options.
+
+!!! tip "Let StatsPAI choose"
+    If you are unsure, `sp.recommend(df, y=..., treat=...)` and
+    `sp.detect_design(df)` will suggest an estimator from the data shape.
+
+---
+
+## "A policy turned on for different units at different times"
+
+Staggered-adoption difference-in-differences. Two-way fixed effects is biased
+here; use a heterogeneity-robust estimator.
+
+```python
+import statspai as sp
+df = sp.datasets.mpdta()
+r = sp.callaway_santanna(df, y="lemp", g="first_treat", t="year", i="countyreal")
+r.summary()
+```
+
+→ [Choosing a DID estimator](guides/choosing_did_estimator.md) ·
+[Callaway–Sant'Anna guide](guides/callaway_santanna.md)
+
+## "One unit got treated and I have many untreated comparison units"
+
+Synthetic control — build a weighted combination of donors that tracks the
+treated unit before treatment.
+
+```python
+r = sp.synth(df, y="outcome", unit="state", time="year",
+             treated="California", treat_period=1989)
+r.plot()
+```
+
+→ [Synthetic control guide](guides/synth.md) ·
+[`sp.synth` family](reference/synth.md)
+
+## "Treatment is endogenous but I have an instrument"
+
+Instrumental variables. Check the first stage before trusting the estimate.
+
+```python
+data = sp.datasets.card_1995()
+r = sp.ivreg("lwage ~ (educ ~ nearc4) + exper + black + south", data=data)
+r.summary()
+# weak-instrument-robust reporting bundle:
+sp.iv_diag(data, y="lwage", endog="educ", instruments="nearc4")
+```
+
+→ [Choosing an IV estimator](guides/choosing_iv_estimator.md) ·
+[IV reference](reference/iv.md)
+
+## "Treatment is assigned by a cutoff on a running variable"
+
+Regression discontinuity.
+
+```python
+data = sp.datasets.lee_2008_senate()
+r = sp.rdrobust(data["vote_t1"], data["margin"], c=0.0)
+r.summary()
+```
+
+→ [Choosing an RD estimator](guides/choosing_rd_estimator.md) ·
+[RD reference](reference/rd.md)
+
+## "I want the effect for everyone, not just the average (heterogeneity)"
+
+Conditional average treatment effects (CATE) via meta-learners, causal
+forest, or double ML.
+
+```python
+r = sp.dml(df, y="y", treat="d", covariates=["x1", "x2", "x3"], model="irm")
+cate = sp.auto_cate(df, y="y", treat="d", covariates=["x1", "x2", "x3"])
+```
+
+→ [Choosing an ML causal estimator](guides/choosing_ml_causal_estimator.md)
+
+## "I have rich confounders and want a robust observational estimate"
+
+Double/debiased ML or TMLE — both doubly robust, both need overlap.
+
+```python
+r = sp.dml(df, y="y", treat="d", covariates=[...], model="irm", ml_g="rf", ml_m="rf")
+r = sp.tmle(df, y="y", treat="d", covariates=[...])
+```
+
+→ [`sp.dml` vs DoubleML](guides/sp_dml_vs_doubleml.md)
+
+## "Why is the gap between two groups what it is?" (decomposition)
+
+Oaxaca–Blinder and RIF/recentered-influence-function decompositions.
+
+```python
+r = sp.decompose(df, y="wage", group="female", covariates=["edu", "exp"],
+                 method="oaxaca")
+```
+
+→ [Decomposition family](guides/decomposition_family.md) ·
+[Decomposition reference](reference/decomposition.md)
+
+## "Match treated and control units on covariates"
+
+Propensity-score / entropy-balancing / optimal matching.
+
+```python
+ps = sp.propensity_score(df, treat="d", covariates=["x1", "x2"])
+w  = sp.ebalance(df, treat="d", covariates=["x1", "x2"])   # entropy balancing
+sp.love_plot(sp.balance_diagnostics(df, treat="d", covariates=["x1", "x2"]))
+```
+
+→ [Choosing a matching estimator](guides/choosing_matching_estimator.md)
+
+## "Panel regression with many fixed effects"
+
+reghdfe-style high-dimensional fixed effects.
+
+```python
+r = sp.hdfe_ols("y ~ x1 + x2 | firm + year", data=df, cluster="firm")
+```
+
+→ [Panel reference](reference/panel.md)
+
+---
+
+## After any estimate: the agent-native follow-ups
+
+```python
+r.summary()        # human-readable
+r.to_dict()        # structured payload for agents
+sp.audit(r)        # what robustness checks are missing?
+r.cite()           # verified BibTeX
+r.to_latex(...)    # publication export
+```

docs/faq.md

@@ -0,0 +1,125 @@
+# FAQ & troubleshooting
+
+## Installation & imports
+
+**Do I need PyTorch / JAX / PyMC?**
+No. The core install has no heavy ML dependencies. Those back specific
+estimators and are lazily imported, so you only hit an `ImportError` if you
+call an estimator that needs an extra you have not installed. The error tells
+you which extra to add, e.g.:
+
+```bash
+pip install "StatsPAI[bayes]"     # PyMC + ArviZ
+pip install "StatsPAI[neural]"    # PyTorch (neural causal, DeepIV)
+pip install "StatsPAI[performance]"  # JAX
+```
+
+**`import statspai as sp` — is there a second import I need?**
+No. Every public function is reachable as `sp.<name>`. If you cannot find
+something, `sp.search_functions("keyword")` or `sp.help(search="keyword")`
+will locate it.
+
+## Discovering functionality
+
+**How do I find the right function?**
+
+```python
+sp.recommend(df, y="y", treat="d")   # suggest an estimator from the data
+sp.detect_design(df)                  # what study design is this?
+sp.search_functions("synthetic control")
+sp.help("did")                        # category / function help
+```
+
+**How do I see a function's assumptions before I run it?**
+
+```python
+sp.agent_card("callaway_santanna")    # assumptions, pre-conditions, failure modes
+sp.function_schema("did", agent_native=True)   # same, as an LLM tool schema
+```
+
+## Reading the output
+
+**What do the warnings mean?**
+StatsPAI fails loudly rather than returning silent `NaN`s. Common warnings:
+
+- `AssumptionWarning` / `AssumptionViolation` — an identifying assumption looks
+  violated (e.g. pre-trends, overlap). Inspect `result.diagnostics`.
+- `ConvergenceWarning` — an iterative/MCMC fit did not converge cleanly
+  (e.g. `rhat > 1.01` or low ESS for Bayesian estimators). Increase
+  iterations/draws.
+- `WorkflowDegradedWarning` — an orchestration step (`sp.paper`, `smart`
+  workflows) degraded a section; the reason is recorded in
+  `result.degradations`.
+
+**My DiD pre-trends look violated — now what?**
+Quantify how sensitive the conclusion is with Rambachan–Roth honest bounds:
+
+```python
+sp.honest_did(r)
+```
+
+→ [Sensitivity analysis guide](guides/honest_did.md)
+
+**My IV estimate has a huge confidence interval.**
+Almost always a weak first stage. Check it and switch to weak-instrument-robust
+inference:
+
+```python
+sp.iv_diag(data, y="y", endog="d", instruments="z")  # effective F + AR interval
+```
+
+**"Poor overlap" / extreme propensity scores.**
+Treated and control covariate distributions barely overlap. Trim or restrict
+to the common-support region:
+
+```python
+sp.trimming(df, treat="d", covariates=[...])
+sp.overlap_plot(sp.ps_balance(df, treat="d", covariates=[...]))
+```
+
+## Reproducibility
+
+**How do I make results deterministic?**
+
+```python
+with sp.session(seed=42):
+    r = sp.callaway_santanna(df, y="lemp", g="first_treat", t="year", i="countyreal")
+```
+
+`sp.session` fixes the global RNG state for bootstrap / permutation / MCMC
+draws inside the block.
+
+## Citations
+
+**How do I cite an estimator correctly?**
+
+```python
+r.cite()                  # verified BibTeX for the method you ran
+sp.bib_for(r)             # structured citation payload
+```
+
+StatsPAI never invents references — every citation is verified against
+`paper.bib`.
+
+## Using StatsPAI from an agent / LLM
+
+Every function returns structured results and carries a self-describing
+schema. The typical agent loop:
+
+```python
+sp.detect_design(df)                       # 1. identify the design
+sp.preflight(df, method="callaway_santanna")  # 2. will it run?
+r = sp.callaway_santanna(df, ...)          # 3. fit
+r.to_dict(detail="agent")                  # 4. structured payload
+sp.audit(r)                                # 5. missing robustness checks
+r.cite()                                   # 6. verified citation
+```
+
+→ [Agent-native API surface](guides/agent_api.md)
+
+## Numerical correctness
+
+**Did the numbers change between versions?**
+Correctness fixes are flagged with **⚠️ correctness** in the
+[changelog](changelog.md) and recorded in `MIGRATION.md`. If you are
+reproducing an older analysis, check those notes for the modules you use.

docs/getting-started.md

@@ -0,0 +1,105 @@
+# Getting started — your first analysis in 5 minutes
+
+This page takes you from `pip install` to a publication-ready difference-in-
+differences estimate, with citation, in well under five minutes. Every code
+block below is runnable as-is against a bundled dataset.
+
+## 1. Install
+
+```bash
+pip install StatsPAI
+```
+
+That is all you need for the core estimators. Optional extras pull in heavier
+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[performance]"# JAX backend for fast feols / bootstrap
+```
+
+## 2. One import
+
+```python
+import statspai as sp
+```
+
+Everything lives under `sp.` — there is no second-level import to remember.
+`sp.list_functions()` enumerates all 1,000+ registered functions.
+
+## 3. Load bundled data
+
+StatsPAI ships the canonical teaching datasets so you can run real analyses
+with zero setup:
+
+```python
+df = sp.datasets.mpdta()          # Callaway–Sant'Anna county teen employment
+df.head()
+#    countyreal  year      lemp  first_treat  treat
+# 0           0  2003  8.162509         2004      0
+# 1           0  2004  8.275744         2004      1
+```
+
+`sp.datasets.list_datasets()` shows the rest (Card 1995 schooling, Lee 2008
+Senate RD, California Prop 99 synthetic control, LaLonde/NSW, …).
+
+## 4. Let StatsPAI read the study design
+
+Not sure which estimator fits? Ask:
+
+```python
+sp.detect_design(df)["design"]
+# 'panel'
+```
+
+`sp.detect_design` inspects the data shape (cross-section / panel / RD / …)
+and `sp.recommend(...)` suggests an estimator. This is the same machinery an
+LLM agent uses to plan an analysis.
+
+## 5. Estimate
+
+`first_treat` is the year each county was first treated (the cohort), `year`
+is time, `countyreal` is the unit, and `lemp` is log employment. That is a
+staggered-adoption DiD, so use the heterogeneity-robust Callaway–Sant'Anna
+estimator:
+
+```python
+r = sp.callaway_santanna(df, y="lemp", g="first_treat", t="year", i="countyreal")
+print(r.summary())
+# ==============================================================================
+#   Callaway and Sant'Anna (2021)
+# ==============================================================================
+#   ATT:         -0.032977 ***
+#   Std. Error:  (0.007740)
+#   [95% CI]:    [-0.048146,  -0.017807]
+#   P-value:      0.0
+```
+
+## 6. Check assumptions and sensitivity
+
+```python
+sp.agent_card("callaway_santanna")["assumptions"]
+# ['Parallel trends conditional on X ...', 'No anticipation', 'SUTVA', ...]
+
+sp.audit(r)            # which robustness checks are still missing?
+sp.honest_did(r)       # Rambachan–Roth bounds on parallel-trends violations
+```
+
+## 7. Export for the paper
+
+Every result object speaks the same export protocol:
+
+```python
+r.to_latex("att.tex")     # publication table
+r.to_word("att.docx")
+r.cite()                  # verified BibTeX for the estimator
+```
+
+## Where to next
+
+- **[Cookbook](cookbook.md)** — recipes organised by research question.
+- **[Choosing a DID estimator](guides/choosing_did_estimator.md)** and the
+  other decision guides.
+- **[FAQ](faq.md)** — common errors and how to read the diagnostics.
+- **[Full API reference](reference/api/index.md)** — all 86 sub-packages.