From 3734dade75d0f67635cb66f28c5090548fc76d3e Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Tue, 23 Jun 2026 08:49:39 +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 | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 86 +++----------------------------------------- 2 files changed, 109 insertions(+), 81 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9fb6e02 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,104 @@ +# PyAutoGalaxy Workspace Test — Agent Instructions + +This is the integration-test suite for **PyAutoGalaxy**, run on the build server to verify the core +library works end-to-end. It is **not** a user-facing workspace — see `../autogalaxy_workspace` for +examples and tutorials. These are the canonical, agent-agnostic instructions for this repo. + +Dependencies: `autogalaxy`, `autofit`, `autoarray`, `numba`. + +## Repository Structure + +``` +scripts/ Integration-test scripts run on the build server + imaging/ interferometer/ CCD imaging / interferometer model-fit tests + ellipse/ quantity/ Ellipse-fitting and derived-quantity tests + aggregator/ Results database aggregator tests (pytest-based) + model_composition/ Model-composition tests + jax_likelihood_functions/ JAX batched-likelihood tests + jax_grad/ jax_assertions/ JAX gradient + assertion tests + latent/ Latent-variable tests +failed/ One log per failing script (written by run_all_scripts.sh) +config/ output/ YAML config and runtime fit results +``` + +## Running Scripts + +Run a single script directly from the repo root (with no env applied, searches run for real). The +aggregator tests are pytest-based and run from their directory: + +```bash +python scripts/imaging/model_fit.py +NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest scripts/aggregator -v +``` + +## 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 **fast-mode defaults for every entry** — +`PYAUTO_TEST_MODE=2` (skip the sampler), `PYAUTO_SMALL_DATASETS=1` (cap grids/masks), +`PYAUTO_FAST_PLOTS=1` — with **per-script `unset`/override** blocks where a test genuinely needs a +real sampler run or full-resolution data. So CI is *not* "searches run for real" by default; it is +fast-mode with targeted exceptions. 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/`): + +```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/imaging/model_fit.py +``` + +## Aggregator & JAX Testing + +- **Aggregator** (`scripts/aggregator/`) — `MockSearch` + `MockSamples` build mock model-fit + results, scrape them into an SQLite database, then exercise each aggregator class (`GalaxiesAgg`, + `FitImagingAgg`, `ImagingAgg`, `InterferometerAgg`, `EllipsesAgg`, `FitEllipseAgg`, + `MultipolesAgg`, …) via its generator methods. +- **JAX** (`jax_likelihood_functions/`, `jax_grad/`, `jax_assertions/`) — exercises the `xp=jnp` + path that library unit tests (NumPy-only) never touch, via `fitness._vmap`. See the PyAutoArray + deep dive `../PyAutoArray/docs/agents/jax_and_decorators.md` for the boundary patterns. + +## 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: `../PyAutoGalaxy`, `../PyAutoArray`, `../PyAutoFit`, `../PyAutoConf`. +- `../autogalaxy_workspace` — the user-facing workspace; `../HowToGalaxy` — the tutorial series. +- `../PyAutoBuild` — CI / build tooling. +- `../autolens_assistant` — science-assistant workspace (literature wiki). + +## 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 the source repo rather than papering over it. Note in your PR +any change that affects sibling repos (`autogalaxy_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 6517ad9..b884ef8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,81 +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 - -**autogalaxy_workspace_test** is the integration test suite for PyAutoGalaxy. It contains pytest test scripts that are run on the build server to verify that the core PyAutoGalaxy functionality works end-to-end. It is not a user-facing workspace — see `../autogalaxy_workspace` for example scripts and tutorials. - -Dependencies: `autogalaxy`, `autofit`, `numba`. Python version: 3.12. - -## Workspace Structure - -``` -scripts/ Integration test scripts run on the build server - aggregator/ Database aggregator tests (pytest-based) - conftest.py Shared fixtures: model, samples, aggregator_from helper - config/ Local config for aggregator tests - test_aggregator_*.py Test files for each aggregator module -failed/ Failure logs written here when a script errors -config/ Root-level YAML configuration files -output/ Model-fit results written here at runtime -``` - -## Running Tests - -Aggregator tests use pytest and run from their directory: - -```bash -cd scripts/aggregator -NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest . -v -``` - -To run all scripts via the runner: - -```bash -bash run_all_scripts.sh -``` - -## Aggregator Tests - -Seven test files covering all PyAutoGalaxy aggregator modules: - -| File | Aggregator Classes Tested | -|------|--------------------------| -| `test_aggregator_galaxies.py` | `GalaxiesAgg` | -| `test_aggregator_fit_imaging.py` | `FitImagingAgg` | -| `test_aggregator_imaging.py` | `ImagingAgg` | -| `test_aggregator_fit_interferometer.py` | `FitInterferometerAgg` | -| `test_aggregator_interferometer.py` | `InterferometerAgg` | -| `test_aggregator_ellipses.py` | `EllipsesAgg` | -| `test_aggregator_fit_ellipse.py` | `FitEllipseAgg` | -| `test_aggregator_multipoles.py` | `MultipolesAgg` | - -Tests use `MockSearch` + `MockSamples` to create mock model-fit results, scrape them into an SQLite database, then test the aggregator's generator methods. - -## 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. +# autogalaxy_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