Skip to content

docs: consolidate agent instructions into canonical AGENTS.md #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jammy2211 merged 1 commit into from
Jun 23, 2026
Merged

docs: consolidate agent instructions into canonical AGENTS.md #66

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 104 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```
86 changes: 5 additions & 81 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading