docs(examples): finish residual 79 + repair runnability gate

Completes the docstring Examples campaign to 1027/1031 (99.6%):
- agent-native introspection (registry/help/_agent_docs), core
  exceptions + result base classes, 11 causal result classes — all
  real runnable examples (exceptions use try/except so they never
  raise; result classes mirror their parent function's verified DGP).
- bayes (17), neural_causal (13): illustrative examples with every
  heavy-dep line '# doctest: +SKIP' (PyMC/torch absent in [dev]/CI);
  pure-numpy policy_weight_* made genuinely runnable.

Repairs the runnability gate (was failing in any torch-less env):
sp.tarnet / sp.cfrnet / sp.dragonnet (function wrappers) and sp.DeepIV
had un-skipped .fit() calls that ImportError without torch — now
'# doctest: +SKIP' on the torch lines (data-construction stays live).
Adds the missed LLMAnnotatorResult example (direct construction).

Gates: examples_coverage missing 79 -> 4 (budget lowered to 4);
check_example_execution 1014 runnable / 0 failing (budget 0). The
residual 4 (anthropic_client, echo_client, openai_client,
particle_filter) carry Examples but are registered-yet-not-top-level-
exposed (sp.<name> raises) — an API-exposure decision deferred past
review, documented in the workflow + campaign log. Schema bundle
regenerated (3 result-class descriptions now human-readable). No new
citations.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: brycewang-stanford

.examples_campaign/CAMPAIGN.md

@@ -35,22 +35,34 @@
 | 1 | causal 头部:DML 配套 + RD 家族 + matching + DiD/SDID | 28 | ✅ 2026-06-12 |
 | 2 | CATE diag + forest + qte + DiD reporting + policy | 32 | ✅ 2026-06-12 |
 | 3 | inference/mht + diagnostics + RD 余量 + synth exports | 40 | ✅ 2026-06-12 |
-| 4 | panel(GLMM/feglm/fepois)+ survey + mediation/gformula | ~30 | pending |
-| 5 | output + postestimation + smart/agent | ~35 | pending |
-| 6 | decomposition + spatial | ~40 | pending |
-| 7 | mendelian + epi + dag + timeseries | ~45 | pending |
-| 8 | 其余长尾(conformal/neural/interference/…) | ~60 | pending |
-| 9 | class-style deferred tier 复盘(决定哪些值得加) | — | pending |
-| 10 | CI ratchet 收紧至最终值 + docs 同步 | — | pending |
+| 4-N | 余下全部(panel/output/decomp/spatial/mendelian/epi/dag/ts/…) | 大批 | ✅ 并行会话 Workflow 扫完 |
+| 残余 | agent/core/bayes/neural/result-class/validation 79 个 | 79 | ✅ 2026-06-14 本会话 6 agent |
+| 收尾 | runnability 门修复 + ratchet 收紧至 4/0 | — | ✅ 2026-06-14 |
 
 每批交付定义:示例运行验证 → `worklist.md` 勾选 → ratchet 预算下调 →
 单独 commit(`docs(examples): batch N — <范围>`)。
 
+## 最终状态(2026-06-14)
+
+- **覆盖率 1027/1031 = 99.6%**(presence gate `missing=4`)。
+- **runnability gate `ran_ok=1014 failed=0`**(每个非 `+SKIP` 示例实跑通过)。
+- 两道 CI 闸门预算:`examples_coverage --max-missing 4` +
+  `check_example_execution --max-failures 0`。
+- **残余 4 个**:`anthropic_client` / `echo_client` / `openai_client`
+  (causal_llm)+ `particle_filter`(assimilation)。这 4 个 docstring
+  **已带 Examples**,但它们 registered-在-registry 却**未在顶层暴露**
+  (`sp.echo_client` 抛 AttributeError),scanner 的 `getattr(sp, name)`
+  够不到其 docstring。这是 registry/export 不一致(应暴露还是应
+  de-register),属公开 API 决策——审稿期间不擅自改,留待用户拍板;
+  解决后预算可进一步降到 0。
+
 ## CI ratchet
 
-`parity-guards.yml` 的 registry-drift job 挂
-`scripts/examples_coverage.py --check --max-missing <budget>`。预算只
-降不升;新注册函数若不带 Examples 会撞预算失败。当前预算:**561**。
+`parity-guards.yml` 的 registry-drift job 挂两道:
+`scripts/examples_coverage.py --check --max-missing 4`(presence)+
+`scripts/check_example_execution.py --max-failures 0`(runnability)。
+预算只降不升;新注册函数若不带可运行 Examples 会撞门失败。当前预算:
+**presence 4 / runnability 0**。
 
 ## Log
 
@@ -105,3 +117,15 @@
   已知(非本批):`diagnostics/tests.py` 的 `diagnose` 有一个早已存在
   的失败 doctest(缺 import),按 additions-only 原则未动,留待后续
   专门修复。
+- **2026-06-14 残余收尾**(本会话,并行会话已扫完中段):用 6 个并行
+  agent(按模块分桶、零写竞争)补齐最后 79 个——agent 自省 API
+  (registry/help/_agent_docs,真可运行)、core 异常+结果类(try/except
+  保证不抛)、bayes 17 个(policy_weights 真可运行,估计器/结果类
+  `# doctest: +SKIP` 因 PyMC 不在 env/CI)、neural_causal 13 个(torch
+  不在 → 全 +SKIP)、11 个 causal 结果类(从父函数已有示例复制 DGP,真
+  可运行)、validation/llm/assimilation/gformula 杂项。**修复运行门 4 个
+  真失败**:`sp.tarnet`/`sp.cfrnet`/`sp.dragonnet`(函数版)+ `sp.DeepIV`
+  的 `.fit()` 调用先前未加 `+SKIP`,在无 torch 的 `[dev]` CI 里会
+  ImportError——已逐行 +SKIP 修复(数据构造行仍真跑)。补 `LLMAnnotatorResult`
+  示例(直接构造结果对象,真可运行)。收 14 行 bayes 超 79 字符。
+  presence 79 → 4,runnability failed → 0;ratchet 收紧 4/0。

.github/workflows/parity-guards.yml

@@ -82,21 +82,27 @@ jobs:
         # Ratchet, not target: the budget is the current number of
         # registered symbols whose docstring lacks an ``Examples``
         # section. The 2026-06 examples campaign drove this from 661
-        # (2026-06-12 baseline, 370/1031 covered) down to 79 (952/1031,
-        # 92.3%). The residual 79 are heavy-optional / infra categories
-        # (bayes, neural_causal, causal_llm, agent, core, validation).
-        # The budget must NEVER be raised: a new public function that
-        # ships without a docstring Examples section fails this gate
-        # (CLAUDE.md §4 requires Parameters/Returns/Examples/References).
+        # (2026-06-12 baseline, 370/1031 covered) down to 4 (1027/1031,
+        # 99.6%). The residual 4 — anthropic_client, echo_client,
+        # openai_client, particle_filter — DO carry Examples in their
+        # docstrings, but are registered in the registry yet not exposed
+        # at the top level (``sp.echo_client`` raises AttributeError), so
+        # the scanner's ``getattr(sp, name)`` cannot reach the docstring.
+        # That registry-vs-export inconsistency is an API-exposure
+        # decision (expose vs de-register) deferred past JOSS review; the
+        # budget can only drop further once it is resolved. The budget
+        # must NEVER be raised: a new public function that ships without a
+        # docstring Examples section fails this gate (CLAUDE.md §4 requires
+        # Parameters/Returns/Examples/References).
         run: |
-          python scripts/examples_coverage.py --check --max-missing 79
+          python scripts/examples_coverage.py --check --max-missing 4
       - name: check_example_execution (docstring Examples runnability)
         # Presence is necessary but not sufficient: an ``Examples`` block
         # that references an undefined ``df`` or a bare ``did(...)`` call
         # is documentation theatre. This gate extracts every example's
         # ``>>>`` source (dropping ``# doctest: +SKIP`` lines for
         # heavy-dep / external-data blocks) and executes it. The whole
-        # campaign was verified to 939 runnable / 0 failing; the ratchet
+        # campaign was verified to 1014 runnable / 0 failing; the ratchet
         # holds that line. A new example that does not run fails here.
         run: |
           python scripts/check_example_execution.py --quiet --max-failures 0

schemas/functions.json

@@ -18491,7 +18491,7 @@
     }
   },
   {
-    "description": "GenMatchResult(att: 'float', att_se: 'float', ci: 'tuple', pvalue: 'float', weights: 'np.ndarray', balance: 'pd.DataFrame', matches: 'np.ndarray', n_treated: 'int', n_obs: 'int', detail: 'Dict[str, Any]' = <factory>)",
+    "description": "Output of :func:`sp.genmatch` (Diamond-Sekhon genetic matching).",
     "name": "GenMatchResult",
     "parameters": {
       "properties": {
@@ -43487,7 +43487,7 @@
     }
   },
   {
-    "description": "CEVAEResult(ate: 'float', ite: 'np.ndarray', loss_history: 'list[float]', backend: 'str')",
+    "description": "Container for CEVAE estimates (ATE, unit-level ITE, loss history).",
     "name": "CEVAEResult",
     "parameters": {
       "properties": {
@@ -43875,7 +43875,7 @@
     }
   },
   {
-    "description": "ICEResult(strategy: 'list', value: 'float', se: 'float', ci: 'tuple[float, float]', method: 'str' = 'parametric-g-formula-ICE', per_timepoint_means: 'list[float]' = None)",
+    "description": "Result of the iterative conditional expectation (ICE) g-formula.",
     "name": "ICEResult",
     "parameters": {
       "properties": {

src/statspai/_agent_docs.py

@@ -77,6 +77,17 @@ def render_agent_block(name: str, *, header: bool = True) -> str:
     ------
     KeyError
         If ``name`` is not a registered function.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> md = sp.render_agent_block('did')
+    >>> isinstance(md, str)
+    True
+    >>> 'For Agents' in md
+    True
+    >>> 'For Agents' in sp.render_agent_block('did', header=False)
+    False
     """
     from .registry import agent_card as _card
 
@@ -154,6 +165,17 @@ def render_agent_blocks(
     -------
     str
         Markdown; empty if nothing to render.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> md = sp.render_agent_blocks(names=['did'])
+    >>> isinstance(md, str)
+    True
+    >>> 'For Agents' in md
+    True
+    >>> '### `sp.did`' in md
+    True
     """
     from .registry import agent_cards as _cards
 

src/statspai/bayes/_base.py

@@ -106,6 +106,19 @@ class BayesianCausalResult:
         Full posterior trace for downstream plotting / diagnostics.
     model_info : dict
         Misc. fit metadata (draws, tune, chains, priors, ...).
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> # Returned by every scalar-estimand Bayesian estimator, e.g.
+    >>> # bayes_rd / bayes_iv (requires the `bayes` extra:
+    >>> #   pip install 'statspai[bayes]').
+    >>> res = sp.bayes_rd(df, y='y', running='x', cutoff=0.0)  # doctest: +SKIP
+    >>> isinstance(res, sp.BayesianCausalResult)  # doctest: +SKIP
+    >>> res.posterior_mean, res.hdi_lower, res.hdi_upper  # doctest: +SKIP
+    >>> res.prob_positive   # posterior P(estimand > 0)  # doctest: +SKIP
+    >>> res.rhat, res.ess   # convergence diagnostics  # doctest: +SKIP
+    >>> res.tidy()  # doctest: +SKIP
     """
 
     method: str
@@ -383,6 +396,18 @@ class BayesianDIDResult(BayesianCausalResult):
     The ``cohort_labels`` field preserves the user's original cohort
     values in the order the model sampled them; iteration order is
     deterministic and matches the posterior variable axis.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> # Returned by bayes_did (requires the `bayes` extra:
+    >>> #   pip install 'statspai[bayes]'). Pass cohort=... to populate
+    >>> # the per-cohort posteriors.
+    >>> res = sp.bayes_did(df, y='y', treat='treat', post='post',
+    ...                    cohort='first_treat')  # doctest: +SKIP
+    >>> res.tidy()                       # pooled ATT row  # doctest: +SKIP
+    >>> res.tidy(terms='per_cohort')     # one row per cohort  # doctest: +SKIP
+    >>> res.cohort_summaries  # doctest: +SKIP
     """
 
     cohort_summaries: Dict[str, Dict[str, float]] = field(default_factory=dict)
@@ -470,6 +495,19 @@ class BayesianIVResult(BayesianCausalResult):
     populated by :func:`bayes_iv` when called with
     ``per_instrument=True``. When the dict is empty (default),
     behaviour matches v0.9.15 exactly.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> # Returned by bayes_iv (requires the `bayes` extra:
+    >>> #   pip install 'statspai[bayes]'). Pass per_instrument=True with
+    >>> # multiple instruments to populate the per-Z posteriors.
+    >>> res = sp.bayes_iv(df, y='y', treat='d',
+    ...                   instrument=['z1', 'z2'],
+    ...                   per_instrument=True)  # doctest: +SKIP
+    >>> res.tidy()                          # pooled LATE row  # doctest: +SKIP
+    >>> res.tidy(terms='per_instrument')  # doctest: +SKIP
+    >>> res.instrument_summaries  # doctest: +SKIP
     """
 
     instrument_summaries: Dict[str, Dict[str, float]] = field(default_factory=dict)
@@ -549,6 +587,17 @@ class BayesianHTEIVResult(BayesianCausalResult):
 
     Carries the average LATE (inherited) *plus* a table of CATE-slope
     posteriors — one row per effect modifier.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> # Returned by bayes_hte_iv (requires the `bayes` extra:
+    >>> #   pip install 'statspai[bayes]').
+    >>> res = sp.bayes_hte_iv(df, y='y', treat='d', instrument='z',
+    ...                       effect_modifiers=['age'])  # doctest: +SKIP
+    >>> res.posterior_mean  # doctest: +SKIP
+    >>> res.cate_slopes  # doctest: +SKIP
+    >>> res.predict_cate({'age': 40})  # doctest: +SKIP
     """
 
     cate_slopes: pd.DataFrame = field(default_factory=pd.DataFrame)
@@ -609,6 +658,19 @@ class BayesianMTEResult(BayesianCausalResult):
     full posterior over the MTE curve ``tau(u)`` on a user-specified
     grid, plus integrated summaries over the treated / untreated /
     average populations (ATT, ATU, ATE).
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> # Returned by bayes_mte (requires the `bayes` extra:
+    >>> #   pip install 'statspai[bayes]').
+    >>> res = sp.bayes_mte(df, y='y', treat='d',
+    ...                    instrument='z')  # doctest: +SKIP
+    >>> res.ate, res.att, res.atu  # doctest: +SKIP
+    >>> res.mte_curve  # doctest: +SKIP
+    >>> res.tidy(terms=['ate', 'att', 'atu'])  # doctest: +SKIP
+    >>> # Policy-relevant effect with a ready-made weight builder:
+    >>> res.policy_effect(sp.policy_weight_ate())  # doctest: +SKIP
     """
 
     mte_curve: pd.DataFrame = field(default_factory=pd.DataFrame)

src/statspai/bayes/did.py

@@ -233,6 +233,19 @@ def bayes_did(
     -------
     BayesianCausalResult
         Posterior summary of the ATT.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> import pandas as pd
+    >>> # Bayesian DiD with NUTS (requires the `bayes` extra:
+    >>> #   pip install 'statspai[bayes]'). draws/tune reduced here for
+    >>> # illustration; defaults are draws=2000, tune=1000, chains=4.
+    >>> res = sp.bayes_did(df, y='y', treat='treat', post='post',
+    ...                    unit='id', time='t',
+    ...                    draws=500, tune=500, chains=2)  # doctest: +SKIP
+    >>> print(res.summary())  # posterior ATT + R-hat / ESS  # doctest: +SKIP
+    >>> res.tidy()  # doctest: +SKIP
     """
     pm, _ = _require_pymc()
 

src/statspai/bayes/dml.py

@@ -124,6 +124,18 @@ def bayes_dml(
     Learning for Causal Inference." arXiv:2508.12688.
     (The underlying orthogonal-moments DML construction is due to
     Chernozhukov et al. 2018, Econometrics Journal.) [@ditraglia2025bayesian]
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> import pandas as pd
+    >>> # Conjugate mode (default) cross-fits sp.dml then applies a
+    >>> # Normal-Normal update; 'full' mode needs the `bayes` extra.
+    >>> res = sp.bayes_dml(df, y='y', treatment='d',
+    ...                    covariates=['x1', 'x2'],
+    ...                    prior_mean=0.0, prior_sd=1.0)  # doctest: +SKIP
+    >>> print(res.summary())                  # doctest: +SKIP
+    >>> res.posterior_mean, res.ci            # doctest: +SKIP
     """
     if mode not in ("conjugate", "full"):
         raise ValueError(f"mode must be 'conjugate' or 'full'; got {mode!r}.")

src/statspai/bayes/fuzzy_rd.py

@@ -111,6 +111,19 @@ def bayes_fuzzy_rd(
     -------
     BayesianCausalResult
         Posterior over the LATE.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> import pandas as pd
+    >>> # Fuzzy RD LATE = ITT_Y / ITT_D at the cutoff via NUTS
+    >>> # (requires the `bayes` extra: pip install 'statspai[bayes]').
+    >>> res = sp.bayes_fuzzy_rd(df, y='y', treat='d', running='x',
+    ...                         cutoff=0.0, poly=1, draws=500,
+    ...                         tune=500, chains=2)  # doctest: +SKIP
+    >>> print(res.summary())  # doctest: +SKIP
+    >>> # First-stage strength diagnostics live in model_info:
+    >>> res.model_info['first_stage_mean']  # doctest: +SKIP
     """
     pm, _ = _require_pymc()
 

src/statspai/bayes/hte_iv.py

@@ -140,6 +140,19 @@ def bayes_hte_iv(
     BayesianHTEIVResult
         `BayesianCausalResult` with a `cate_slopes` DataFrame and
         `predict_cate(values)` method.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> import pandas as pd
+    >>> # Bayesian IV with LATE that varies linearly in 'age'
+    >>> # (requires the `bayes` extra: pip install 'statspai[bayes]').
+    >>> res = sp.bayes_hte_iv(df, y='y', treat='d', instrument='z',
+    ...                       effect_modifiers=['age'],
+    ...                       draws=500, tune=500, chains=2)  # doctest: +SKIP
+    >>> res.cate_slopes        # one row per effect modifier  # doctest: +SKIP
+    >>> # Posterior CATE at a specific modifier value:
+    >>> res.predict_cate({'age': 40})  # doctest: +SKIP
     """
     pm, _ = _require_pymc()
     prep = _prepare_hte_iv_frame(

src/statspai/bayes/iv.py

@@ -144,6 +144,22 @@ def bayes_iv(
     -------
     BayesianCausalResult
         Posterior summary on the LATE coefficient.
+
+    Examples
+    --------
+    >>> import statspai as sp
+    >>> import pandas as pd
+    >>> # Bayesian IV jointly modelling first stage + structural eq.
+    >>> # (requires the `bayes` extra: pip install 'statspai[bayes]').
+    >>> res = sp.bayes_iv(df, y='y', treat='d', instrument='z',
+    ...                   covariates=['x1'],
+    ...                   draws=500, tune=500, chains=2)  # doctest: +SKIP
+    >>> print(res.summary())  # doctest: +SKIP
+    >>> # Multiple instruments with one LATE row per instrument:
+    >>> res2 = sp.bayes_iv(df, y='y', treat='d',
+    ...                    instrument=['z1', 'z2'],
+    ...                    per_instrument=True)  # doctest: +SKIP
+    >>> res2.tidy(terms='per_instrument')  # doctest: +SKIP
     """
     pm, _ = _require_pymc()