From 9b1d592f8a1bf6c456e1ff9e1aa724b1cd73ab4f Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Tue, 23 Jun 2026 08:49:40 +0100 Subject: [PATCH] docs: add canonical AGENTS.md, reduce CLAUDE.md to import stub MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Migrate the agent docs to one agent-agnostic AGENTS.md (uniform skeleton) with CLAUDE.md as a 4-line @AGENTS.md stub. Document run_smoke.py as the CI gate (Python 3.12 & 3.13, driven by smoke_tests.txt + config/build/env_vars.yaml), keep run_all_scripts.sh as the local full sweep, and reconcile the test-mode story: env_vars.yaml sets PYAUTO_TEST_MODE=2 by default with per-script overrides — not 'searches run for real'. Fix the stale Python-3.11 note and drop the /mnt/c narrative. Co-Authored-By: Claude Opus 4.8 (1M context) --- AGENTS.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 89 +++------------------------------------------------- 2 files changed, 98 insertions(+), 84 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4c9e58d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,93 @@ +# PyAutoFit Workspace Test — Agent Instructions + +This is the integration-test suite for **PyAutoFit**, run on the build server to verify the core +library works end-to-end. It is **not** a user-facing workspace — see `../autofit_workspace` for +examples and tutorials. These are the canonical, agent-agnostic instructions for this repo. + +Dependencies: `autofit` (and `autoconf`). + +## Repository Structure + +``` +scripts/ Integration-test scripts run on the build server + searches/ Non-linear search tests (Dynesty, Emcee, Nautilus, LBFGS, …) + features/ Feature tests (assertions, latent variables, minimal output, …) + database/ Database tests (directory, scrape, session) + graphical/ Graphical-model tests (EP, hierarchical, simultaneous) + model_composition/ Model-composition tests + prior_correctness/ Prior-behaviour correctness tests + jax_assertions/ JAX assertion tests + simulators/ Simulator utilities used by the other scripts +failed/ One .txt log per failing script (written by run_all_scripts.sh) +dataset/ config/ output/ Input data, YAML config, runtime fit results +``` + +## Running Scripts + +Run a single script directly from the repo root — with no env applied, the non-linear search runs +for real (sampler limits like `n_like_max` keep it short): + +```bash +python scripts/searches/DynestyStatic.py +``` + +## Testing + +On CI, `smoke_tests.yml` gates every PR on Python **3.12 and 3.13**. The gate runs the smoke runner +(the definition of green): + +```bash +python .github/scripts/run_smoke.py +``` + +It executes the curated entries in `smoke_tests.txt`, applying per-entry environment from +`config/build/env_vars.yaml`. That file sets `PYAUTO_TEST_MODE=2` (skip the sampler) as the default, +but **search and feature tests that must validate real inference `unset` it** (or set +`PYAUTO_TEST_MODE=1`, reduced iterations with a real sampler) — those are the cases where bypassing +the sampler would defeat the test. So the test-mode story is per-script, not a blanket "runs for +real." A failure under these flags signals a real problem. + +For a local **full sweep** of every script under `scripts/`, use the stateless runner (logs each +failure to `failed/.txt`): + +```bash +bash run_all_scripts.sh +``` + +## Sandboxed / restricted runs + +If `numba` or `matplotlib` cannot write to the default cache locations, point them at writable dirs: + +```bash +NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/searches/DynestyStatic.py +``` + +## Bulk-edit safety + +When editing the same region across many scripts in one pass, only rewrite the targeted region. +**Never produce a whole-file write unless you have read the entire current file** — a whole-file +write from a header skim silently deletes every section below the header. + +## Related Repos + +- Source libs: `../PyAutoFit`, `../PyAutoConf`. +- `../autofit_workspace` — the user-facing workspace; `../HowToFit` — the tutorial series. +- `../PyAutoBuild` — CI / build tooling. + +## Task Workflows + +When a library change lands, run the smoke suite, read any `[FAIL]` entries, and update the affected +test scripts to the new API (preserving intent). **Never edit a script to mask a real regression** — +if a library bug surfaces, flag it for PyAutoFit rather than papering over it. Note in your PR any +change that affects sibling repos (`autofit_workspace`, the source libraries). + +## 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 7e6a2b0..dcced43 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,84 +1,5 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## What This Repo Is - -**autofit_workspace_test** is the integration test suite for PyAutoFit. It contains Python scripts that are run on the build server to verify that the core PyAutoFit functionality works end-to-end. It is not a user-facing workspace — see `../autofit_workspace` for example scripts and tutorials. - -Dependencies: `autofit`. Python version: 3.11. - -## Workspace Structure - -``` -scripts/ Integration test scripts run on the build server - searches/ Non-linear search tests (Dynesty, Emcee, LBFGS, etc.) - features/ Feature tests (assertions, grid search, latent variables, etc.) - database/ Database tests (directory, scrape, session) - graphical/ Graphical model tests (EP, hierarchical, simultaneous) - simulators/ Simulator utilities used by other scripts -failed/ Failure logs written here when a script errors (one .txt per failure) -dataset/ Input data files and example datasets -config/ YAML configuration files -output/ Model-fit results written here at runtime -``` - -## Running Tests - -Scripts are run from the repository root **without** `PYAUTO_TEST_MODE=1` — the non-linear searches run for real (using sampler limits like `n_like_max` to keep runtimes short): - -```bash -python scripts/imaging/model_fit.py -``` - -**Codex / sandboxed runs**: when running 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 python scripts/imaging/model_fit.py -``` - -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. - -To run all tests and log failures to `failed/`: - -```bash -bash run_all_scripts.sh -``` - -Each failed script produces a `.txt` file in `failed/` named after the script path (with `/` replaced by `__`), containing the exit code and full output. - -Unlike `../autolens_workspace`, there is no resume/skip logic — every run executes all scripts in `scripts/` from scratch. - -## Integration Test Runner - -`run_all_scripts.sh` at the repo root: -- Finds all `*.py` files under `scripts/` and runs them in order (no test mode flag) -- On failure: writes a log to `failed/.txt` -- Does not skip previously-run scripts (stateless, always runs all) - -## Line Endings — Always Unix (LF) - -All files **must use Unix line endings (LF, `\n`)**. Never write `\r\n` line endings. -## 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. +# autofit_workspace_test — 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