CausalPy

# AGENTS

Agent workflow for working in this repo. For codebase design and conventions, read [ARCHITECTURE.md](ARCHITECTURE.md) before core code changes. Do **not** load [CONTRIBUTING.md](CONTRIBUTING.md) by default — it is a long human-contributor guide (setup, permissions, PR etiquette). Consult it only when the task is explicitly about contributor workflow or onboarding humans.

## Environment

**uv is the default environment manager.** Use `uv run <command>` for commands that import project code, run tests, build docs, or use repo tooling — there is no environment to activate. If the project has not been synced yet in the current checkout, run `uv sync --locked --extra dev --extra docs --extra test --extra lint` first (see the [python-environment skill](.agents/skills/python-environment/SKILL.md) for full setup instructions).

**Conda fallback:** if `uv` is unavailable, fall back to `mamba`, `micromamba`, or `conda` (in that preference order) against the `CausalPy` env described by `environment.yml`. Reuse an existing `CausalPy` env whenever possible; do not create or update an env unless the task needs the project environment and the existing env is missing, stale, or broken. Use `$CONDA_EXE run -n CausalPy <command>`; never use `$CONDA_EXE activate`. For simple text/JSON inspection helpers that do not import project code, any Python on `PATH` is fine.

- If `$CONDA_EXE run -n CausalPy ...` fails because the named env cannot be resolved, inspect `$CONDA_EXE env list` and retry with `$CONDA_EXE run -p <full-prefix> <command>`.
- In git worktrees, prefer reusing an existing uv `.venv` or conda env. Because the repo uses editable installs, rerun `uv sync` (or `make setup` / `make setup-conda`) in the current worktree only when that checkout has not been synced/installed into the env yet or when dependencies changed.

- Dependencies live in `pyproject.toml`; both `uv.lock` (canonical, default dev + CI) and `environment.yml` (conda alternative, generated by a prek hook) are derived from it — do not hand-edit either. The docs-only PyMC-Marketing release is pinned separately in `docs/requirements.txt`.
- **Development**: The default setup is `uv sync --locked` against `uv.lock`. The conda env (`environment.yml`) remains a fully supported alternative for contributors who prefer conda-forge builds. `pip install -e .[dev]` works but does not include `make`-only tooling; prefer `uv sync` or the conda alternative over a bare pip install.

## Testing

- Write all Python tests as `pytest` style functions, not unittest classes
- Use descriptive function names starting with `test_`
- Prefer fixtures over setup/teardown methods
- Use assert statements directly, not self.assertEqual
- Never create throwaway test scripts or ad hoc verification files
- If you need to test functionality, write a proper test in the test suite
- All tests go in the `causalpy/tests/` directory following the project structure
- Tests should be runnable with the rest of the suite (`python -m pytest`)
- Even for quick verification, write it as a real test that provides ongoing value
- Preference should be given to integration tests, but unit tests are acceptable for core functionality to maintain high code coverage.
- Tests should remain quick to run. Tests involving MCMC sampling with PyMC should use custom `sample_kwargs` to minimize the computational load.
- Tests that stay heavy even with light `sample_kwargs` get `@pytest.mark.nightly` (heavy doctests go in `NIGHTLY_DOCTESTS` in `causalpy/tests/doctest_sampling.py`). The default pytest addopts skip `nightly` and `correctness` tests; PR CI runs the `correctness` tests that are not also `nightly` in a separate step, and `.github/workflows/nightly.yml` runs everything. Run them locally with `make test-nightly` and `make test-correctness`. `slow` is descriptive only and does not change where a test runs.

## Sandbox and permissions

- **PyMC/PyTensor require filesystem access** outside the workspace (e.g. `~/.pytensor/compiledir_*` for C compilation cache, `~/.matplotlib` for font cache). The default Cursor sandbox blocks writes to these paths, causing misleading `ValueError` or `PermissionError` failures that look like real test errors but are not.
- **Always use `required_permissions: ["all"]`** when running `pytest`, `make doctest`, or any command that imports PyMC, PyTensor, or matplotlib. This avoids false negatives from sandbox restrictions.
- **If a test run shows `compiledir ... you don't have read, write or listing permissions`**, that is a sandbox problem, not a code problem. Re-run with `["all"]` permissions before investigating further.

## Documentation

- **Structure**: Notebooks (how-to examples) go in `docs/source/notebooks/`, knowledgebase (educational content) goes in `docs/source/knowledgebase/`
- **Notebook naming**: Use lowercase hyphen-separated words with the full method name spelled out, then the dataset/variant token (if any), then the backend (`pymc` or `sklearn`). Pattern: `{method}[-{variant}]-{backend}.ipynb` (e.g., `difference-in-differences-pymc.ipynb`, `regression-discontinuity-drinking-sklearn.ipynb`, `synthetic-control-brexit-pymc.ipynb`). Prefer descriptive words over acronyms for SEO: `interrupted-time-series` over `its`, `regression-discontinuity` over `rd`, `synthetic-control` over `sc`, `instrumental-variables` over `iv`. When renaming an existing notebook, update `docs/source/notebooks/gallery.yaml`, run `make gallery`, add an entry to `rediraffe_redirects` in `docs/source/conf.py`, and never remove older redirect keys.
- **MyST directives**: Use `:::{note}` and other MyST features for callouts and formatting
- **Glossary linking**: Link to glossary terms (defined in `glossary.rst`) on first mention in a file:
  - In Markdown files (`.md`, `.ipynb`): Use MyST syntax `{term}glossary term``
  - In RST files (`.rst`): Use Sphinx syntax `:term:`glossary term``
- **Cross-references**: For other cross-references in Markdown files, use MyST role syntax with curly braces (e.g., `{doc}path/to/doc`, `{ref}label-name`)
- **Citations**: Use `references.bib` for citations, cite sources in example notebooks where possible. Include reference section at bottom of notebooks using `:::{bibliography}` directive with `:filter: docname in docnames`
- **API documentation**: Sphinx autodoc generates members from docstrings. `docs/source/api/index.md` is the curated API manifest, not a manual reference; preserve its top-level `causalpy` `automodule` with `:members:`, `:undoc-members:`, and `:imported-members:`. Before promoting an export, follow the four-tier policy in `ARCHITECTURE.md`. `make check-exports` and the `check-public-exports` prek hook statically check Tier 1 bindings and Sphinx wiring; do not use importability or underscore heuristics.
- **Public callable signatures**: Use explicit named parameters; use keyword-only optional controls where the method's contract allows it, especially public plotting and plot-data APIs. Do not add bare `*args` or `**kwargs` to documented/exported CausalPy callables; a genuine dynamic or third-party forwarder must document its accepted forwarding surface under `Other Parameters` and have a narrow exemption in `causalpy/tests/test_public_signatures.py`. Use `python scripts/audit_public_signatures.py` to review the static documented-public inventory before changing a public signature.
- **Build**: Use `make html` to build documentation
- **Doctest**: Use `make doctest` to test that Python examples in doctests work
- **Notebook validation**: `prek run --all-files` runs `validate-notebooks` to catch invalid nbformat and docs notebook convention errors.
- **Notebook validation failure recovery**: Re-open and save (or re-run) in a notebook-aware editor; if it still fails, restore from `main` and reapply intended edits with notebook-aware tooling; rerun `prek run --all-files`; for docs notebook changes run `uv run make html` (or `$CONDA_EXE run -n CausalPy make html` on the conda fallback) before pushing.
- **Scratch files**: Put temporary notes and generated markdown in `.scratch/` (untracked). Move anything that should be kept into a tracked location.
  - **PR drafts**: Create PR summary markdown files in `.scratch/pr_summaries/` (untracked).
  - **Issue drafts**: Create issue draft markdown files in `.scratch/issue_summaries/` (untracked).
- **No hard line wrapping in prose-like text**: Do not hard-wrap lines in any prose context — Markdown files, long comments in code (TOML/YAML/Python/etc.), commit-message bodies, PR descriptions, issue descriptions, or GitHub comments. One paragraph = one line; rely on the viewer/editor to re-wrap. Hard wraps look ragged at different widths, make diffs noisy on every reflow, and mangle when copied or quoted. Code itself, code blocks inside Markdown, ASCII tables, and structured config values are exempt — those need their literal line structure.

### Adding new notebooks to the gallery

When creating a new example notebook:

1. **Place it** in `docs/source/notebooks/` using the hyphen-case naming pattern above (e.g. `difference-in-differences-pymc.ipynb`)
2. **Include at least one plot** in the notebook outputs (the first PNG image will be used as the thumbnail)
3. **Add an entry to `docs/source/notebooks/gallery.yaml`** in the appropriate category:
   - `title`: card title shown in the gallery grid
   - `notebook`: stem without extension (e.g. `difference-in-differences-pymc`)
   - `thumbnail: false` for non-notebook pages such as `sensitivity_checks.md`
4. **Regenerate the gallery index** with `make gallery`. This updates `index.md`, hidden toctrees for the left sidebar, and thumbnails.
5. **Test locally** with `make html` and check `docs/_build/notebooks/index.html`

**Important**: `gallery.yaml` is the source of truth. `index.md` is generated — do not edit it by hand. The `gallery-in-sync` prek hook fails if `gallery.yaml`, notebooks, and `index.md` drift apart.

### Legacy URL redirects (rediraffe)

Renamed or deleted how-to pages must keep a **permanent** entry in `rediraffe_redirects` in `docs/source/conf.py`. At docs build time, [sphinxext-rediraffe](https://sphinxext-rediraffe.readthedocs.io/) emits redirect HTML at the old RTD path so bookmarks and blog links keep working.

- **On rename**: add `"notebooks/old_stem": "notebooks/new-stem"` (no `.ipynb` suffix). Keep all prior keys; do not delete old entries when cleaning up.
- **On delete**: remove the card from `gallery.yaml`, run `make gallery`, then add a redirect from the old docname to the How-to gallery page (`"notebooks/old_stem": "notebooks/index"`) or to a closely related notebook if one supersedes it.
- **Does not cover**: GitHub raw links to `docs/source/notebooks/old_name.ipynb` — only built RTD HTML URLs.
- **CI**: `scripts/check_rediraffe_redirects.py` (prek hook `rediraffe-redirects`) fails if a notebook rename/delete since `main` lacks a redirect entry or if a redirect target is missing on disk.

## Code quality checks

- **Before committing**: Use `prek run` during iterative edits and run `prek run --all-files` before committing to ensure all checks pass (linting, formatting)
- **Type checking**: `mypy` is intentionally **not** in `prek` — it only says anything useful when the project dependencies are importable, and a hook environment does not have them (issue #1127). Run `uv run make typecheck` (or `$CONDA_EXE run -n CausalPy make typecheck` on the conda fallback); CI runs the same target from the test job. Scope and the per-module allowlist live in `[tool.mypy]` in `pyproject.toml`.
- **Patch coverage (milestones, not every commit)**: `make test-patch-cov` is intentionally **not** in `prek` — it runs the full test suite (~90s+) and needs the conda env. Run it at meaningful checkpoints when Python source or tests under `causalpy/` changed, not on every small commit:
  - A PR is ready for review, or you are about to push for CI
  - You finished a large or multi-file task touching production code
  - You are handing off to another person or agent
  - During iterative work, rely on `prek` and targeted `pytest` instead
  - Command: `uv run make test-patch-cov` (or `$CONDA_EXE run -n CausalPy make test-patch-cov` on the conda fallback)
  - The gate measures **production code only** (`causalpy/tests/*` excluded) at **96%**, approximating the remote Codecov patch check against `upstream/main` when available, falling back to `origin/main`. Override `DIFF_COVER_COMPARE_BRANCH`, `DIFF_COVER_FAIL_UNDER`, or `DIFF_COVER_EXCLUDE` only when the PR deliberately targets a different base or threshold.
- **Quick check**: Run `ruff check causalpy/` for fast linting feedback during development
- **Auto-fix**: Run `ruff check --fix causalpy/` to automatically fix many linting issues
- **Format**: Run `ruff format causalpy/` to format code according to project standards
- **Linting rules**: Project uses strict linting (F, B, UP, C4, SIM, I) to catch bugs and enforce modern Python patterns
- **Note**: Documentation notebooks in `docs/` are excluded from strict linting rules

## Type Checking

- **Tool**: MyPy
- **Configuration**: Integrated as a prek hook.
- **Scope**: Checks Python files within the `causalpy/` directory.
- **Settings**:
    - `ignore-missing-imports`: Enabled to allow for gradual adoption of type hints without requiring all third-party libraries to have stubs.
    - `additional_dependencies`: Includes `numpy` and `pandas-stubs` to provide type information for these libraries.
- **Execution**: Run automatically via `prek run --all-files` or on commit.
- **Style**: Use Python 3.10+ type hint syntax. Specifically: `X | None` not `Optional[X]`, lowercase `dict`, `list`, `tuple` not `Dict`, `List`, `Tuple` from `typing`, and `Literal` for constrained string parameters.

## GitHub Issue Workflows

Use the `github-issues` Skill in `.agents/skills/github-issues/` for issue
creation, bug reports, and issue evaluation workflows.

## Skills Location

Skills are split into two categories with separate homes:

- **Developer skills** live in `.agents/skills/`. This is the canonical shared location for repo-maintainer workflows such as environment setup, PR workflows, issue triage, and other maintainer tasks.
- **User skills** live in `causalpy/skills/` inside the source tree. They teach AI agents how to use CausalPy for causal inference tasks. They are **not** symlinked into the auto-discovery paths — a developer agent should not see experiment-design skills mixed in with PR review skills. User skills are distributed via [Decision AI Hub](https://hub.decision.ai).
- When user-facing skills change, include a PR note or follow-up task to update the distributed Decision AI Hub copy after merge.

If a developer's local tool does not yet discover `.agents/skills/`, they may create an uncommitted local compatibility symlink such as `.cursor/skills -> ../.agents/skills`, `.claude/skills -> ../.agents/skills`, or `.github/skills -> ../.agents/skills`. Do not commit those compatibility symlinks; keep `.agents/skills/` as the only tracked developer-skill home.

More agent context in pymc-labs/CausalPy

9 other files this repository gives its agents.