From bb4cebfc61741febb673d98c3ffefb03e887fbcf Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Mon, 22 Jun 2026 20:24:20 +0100 Subject: [PATCH] docs: consolidate agent instructions into canonical AGENTS.md Merge the parallel CLAUDE.md/AGENTS.md into one agent-agnostic AGENTS.md (uniform skeleton) and reduce CLAUDE.md to an @AGENTS.md import stub. State import direction (autoconf only), the real CI matrix (3.12 + 3.13, black advisory), requires-python >=3.9, Configuration & defaults, and the [nss] handley-lab blackjax-fork footgun. Drop dependency version-pin lists and the /mnt/c narrative. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 128 ++++++++++++++++++++++++++++++++++-------------------- CLAUDE.md | 100 +++--------------------------------------- 2 files changed, 85 insertions(+), 143 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d0811a797..692f75fdf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,68 +1,100 @@ # PyAutoFit — Agent Instructions -**PyAutoFit** is a Python probabilistic programming language for model fitting and Bayesian inference. +Canonical, agent-agnostic instructions for this repo. `CLAUDE.md` imports this +file; any tool that does not process `@`-imports should read this directly. -## Setup +## What this repo is -```bash -pip install -e ".[dev]" -``` +**PyAutoFit** (package `autofit`) is a probabilistic programming language for +model composition, non-linear search, and Bayesian inference: `af.Model` / +`af.Collection`, the `af.Analysis` interface, MCMC / nested-sampling / MLE +searches, samples, aggregator, and a SQLAlchemy results database. + +Dependency direction: autofit depends on **autoconf** only. It does **not** +import `autoarray`, `autogalaxy`, or `autolens` — never add such an import. +Shared utilities (e.g. `test_mode`, `jax_wrapper`) belong in autoconf. + +## Related repos + +- **Source siblings:** PyAutoConf (upstream). PyAutoGalaxy / PyAutoLens are + downstream consumers (they build `Analysis` subclasses on autofit). +- **autofit_workspace** — runnable tutorials/examples (`../autofit_workspace`). +- **autofit_workspace_test** — integration + JAX/likelihood parity scripts. +- **HowToFit** — the lecture-style tutorial series (`../HowToFit`). +- **docs/** — Sphinx source; published to ReadTheDocs. -## Running Tests +## Quick commands ```bash -python -m pytest test_autofit/ -python -m pytest test_autofit/non_linear/ -python -m pytest test_autofit/mapper/ +pip install -e ".[dev]" # install with dev/test extras +python -m pytest test_autofit/ # full test suite +python -m pytest test_autofit/non_linear/ # one focused subtree (add -s for output) +black autofit/ # formatter (advisory — not gated) ``` -### Sandboxed / Codex runs +In a sandboxed / restricted environment, point numba and matplotlib at +writable caches: ```bash NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autofit/ ``` -## Key Architecture +## CI / definition of green -- **Non-linear searches** (`non_linear/search/`): MCMC (emcee), nested sampling (dynesty, nautilus), MLE (LBFGS, BFGS, drawer) -- **Model composition** (`mapper/`): `af.Model`, `af.Collection`, prior distributions -- **Analysis** (`non_linear/analysis/`): base `af.Analysis` class with `log_likelihood_function` -- **Aggregator** (`aggregator/`): results aggregation across runs -- **Database** (`database/`): SQLAlchemy backend for results storage -- **Graphical models** (`graphical/`): expectation propagation +PRs must pass `pytest --cov` on the CI matrix (Python 3.12 **and** 3.13). There +is no black/ruff/flake8 gate — formatting is advisory. (`requires-python` in +`pyproject.toml` is `>=3.9`.) -## Key Rules +## Configuration & defaults -- All files must use Unix line endings (LF) -- Format with `black autofit/` +autoconf supplies the packaged defaults under `autofit/config/`. Workspaces +override them via their own `config/` directory; the test suite pushes a local +config dir via `conf.instance.push(...)` in `test_autofit/conftest.py`. When a +change adds a new config key, mirror it into the packaged defaults so +downstream workspaces inherit it. + +## Public API + +The public surface is defined authoritatively in `autofit/__init__.py` — read +it rather than trusting a hand-maintained list. Canonical import: + +```python +import autofit as af +``` -## Working on Issues +Key subsystems: `non_linear/search/` (MCMC: emcee/zeus; nested: dynesty, +nautilus, NSS; MLE: LBFGS/BFGS/drawer), `mapper/` (model + priors), +`non_linear/analysis/` (`af.Analysis.log_likelihood_function`), `aggregator/`, +`database/` (SQLAlchemy), `graphical/` (expectation propagation), +`interpolator/`. + +## Key rules / footguns + +- Import direction: autoconf only — never `autoarray` / `autogalaxy` / + `autolens`. +- The `[nss]` extra (for `af.NSS`) needs a pinned **handley-lab/blackjax** fork + installed manually *after* the extras step; that fork conflicts with the + mainline `blackjax` pinned in `[optional]`. Do not naively combine or bump + them — see the install notes in `pyproject.toml`. +- All files use Unix line endings (LF, `\n`) — never `\r\n`. + +## Working on issues 1. Read the issue description and any linked plan. -2. Identify affected files and write your changes. -3. Run the full test suite: `python -m pytest test_autofit/` -4. Ensure all tests pass before opening a PR. -5. If changing public API, note the change in your PR description — downstream packages (PyAutoArray, PyAutoGalaxy, PyAutoLens) and workspaces may need updates. -## Never rewrite history - -NEVER perform these operations on any repo with a remote: - -- `git init` in a directory already tracked by git -- `rm -rf .git && git init` -- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset - for AI workflow", or any equivalent message on a branch with a remote -- `git push --force` to `main` (or any branch tracked as `origin/HEAD`) -- `git filter-repo` / `git filter-branch` on shared branches -- `git rebase -i` rewriting commits already pushed to a shared branch - -If the working tree needs a clean state, the **only** correct sequence is: - - git fetch origin - git reset --hard origin/main - git clean -fd - -This applies equally to humans, local Claude Code, cloud Claude agents, Codex, -and any other agent. The "Initial commit — fresh start for AI workflow" pattern -that appeared independently on origin and local for three workspace repos is -exactly what this rule prevents — it costs ~40 commits of redundant local work -every time it happens. +2. Identify affected files and make the change. +3. Run the full suite: `python -m pytest test_autofit/`. +4. If you changed public API, say so explicitly — downstream packages + (PyAutoGalaxy, PyAutoLens) and the workspaces may need updates. +5. Ensure all tests pass before opening a PR. + +## Clean state + +Never rewrite history on a repo with a remote (no `git init` over a tracked +tree, no force-push to `main`, no rebasing pushed shared branches). To reset a +dirty tree the only correct sequence is: + +```bash +git fetch origin +git reset --hard origin/main +git clean -fd +``` diff --git a/CLAUDE.md b/CLAUDE.md index a1429f785..a640b7694 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,95 +1,5 @@ -# PyAutoFit - -**PyAutoFit** is a Python probabilistic programming language for model fitting and Bayesian inference. - -- Authors: James Nightingale, Richard Hayes -- Requires Python >= 3.12 -- Package name: `autofit` - -## Dependency Graph - -PyAutoFit depends on **autoconf** (shared configuration and utilities). -PyAutoFit does **NOT** depend on PyAutoArray, PyAutoGalaxy, or PyAutoLens. -Never import from `autoarray`, `autogalaxy`, or `autolens` in this repo. -Shared utilities (e.g. `test_mode`, `jax_wrapper`) belong in autoconf. - -## Repository Structure - -- `autofit/` - Main package - - `non_linear/` - Non-linear search algorithms - - `search/mcmc/` - MCMC (emcee, zeus) - - `search/mle/` - Maximum likelihood (LBFGS, BFGS, drawer) - - `search/nest/` - Nested sampling (dynesty, nautilus) - - `samples/` - Posterior samples handling - - `paths/` - Output path management - - `analysis/` - Analysis base classes - - `mapper/` - Model and prior machinery - - `prior/` - Prior distributions - - `prior_model/` - Prior model composition - - `model.py` - Core model class - - `graphical/` - Graphical models and expectation propagation - - `aggregator/` - Results aggregation across runs - - `database/` - SQLAlchemy-based results database - - `interpolator/` - Model interpolation - - `config/` - Default config files packaged with library -- `test_autofit/` - Test suite (pytest) -- `docs/` - Sphinx documentation - -## Key Dependencies - -- `dynesty==2.1.5` - Nested sampling -- `emcee>=3.1.6` - MCMC -- `scipy<=1.14.0` - Optimisation -- `SQLAlchemy==2.0.32` - Database backend -- `anesthetic==2.8.14` - Posterior analysis/plotting -- Optional: `nautilus-sampler`, `zeus-mcmc`, `getdist` - -## Running Tests - -``` -pytest test_autofit -pytest test_autofit/non_linear -pytest test_autofit/mapper -``` - -## Codex / sandboxed runs - -When running Python from Codex or any restricted environment, set writable cache directories so `numba` and `matplotlib` do not fail on unwritable home or source-tree paths: - -```bash -NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib pytest test_autofit -``` - -This workspace is often imported from `/mnt/c/...` and Codex may not be able to write to module `__pycache__` directories or `/home/jammy/.cache`, which can cause import-time `numba` caching failures without this override. - -## Shell Commands - -- Prefer simple shell commands -- Avoid chaining with `&&` or pipes; run commands separately - -## Related Repos - -- **autofit_workspace** (tutorials/examples): `../autofit_workspace` -## Never rewrite history - -NEVER perform these operations on any repo with a remote: - -- `git init` in a directory already tracked by git -- `rm -rf .git && git init` -- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset - for AI workflow", or any equivalent message on a branch with a remote -- `git push --force` to `main` (or any branch tracked as `origin/HEAD`) -- `git filter-repo` / `git filter-branch` on shared branches -- `git rebase -i` rewriting commits already pushed to a shared branch - -If the working tree needs a clean state, the **only** correct sequence is: - - git fetch origin - git reset --hard origin/main - git clean -fd - -This applies equally to humans, local Claude Code, cloud Claude agents, Codex, -and any other agent. The "Initial commit — fresh start for AI workflow" pattern -that appeared independently on origin and local for three workspace repos is -exactly what this rule prevents — it costs ~40 commits of redundant local work -every time it happens. +# PyAutoFit — agent instructions +The canonical, agent-agnostic instructions live in `AGENTS.md`. Claude Code loads them +via the import below; if your tool does not process `@`-imports, open `AGENTS.md` in +this directory and read it directly. +@AGENTS.md