diff --git a/AGENTS.md b/AGENTS.md index 41b15c4..ebac0aa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,66 +1,86 @@ # PyAutoConf — Agent Instructions -**PyAutoConf** is the configuration management library for the PyAuto ecosystem. It handles object serialization/deserialization, JSON-based priors, and configuration generation. +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]" -``` +**PyAutoConf** (package `autoconf`) is the configuration, serialization, and +I/O foundation of the PyAuto ecosystem: layered config with overrides, +dict/JSON/CSV serialization, FITS I/O, JSON-based priors, and the shared +`jax_wrapper` / `test_mode` utilities. + +Dependency direction: autoconf is the **base layer**. It does **not** import +`autofit`, `autoarray`, `autogalaxy`, or `autolens`. All four of those depend +on autoconf, so any public-API change here ripples downstream. + +## Related repos -## Running Tests +- **Source siblings (downstream):** PyAutoFit, PyAutoArray, PyAutoGalaxy, + PyAutoLens — all depend on autoconf. +- No `_workspace`, `_workspace_test`, or HowTo companion repo. +- No `docs/` / RTD site — the package source and `test_autoconf/` are the + authoritative reference. + +## Quick commands ```bash -python -m pytest test_autoconf/ +pip install -e ".[dev]" # install with dev/test extras +python -m pytest test_autoconf/ # full test suite +python -m pytest test_autoconf/tools/test_decorators.py # one focused test +black autoconf/ # 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_autoconf/ ``` -## Key Architecture +## CI / definition of green + +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`.) -- `autoconf/conf.py` — Core configuration system -- `autoconf/dictable.py` — Dictionary/serialization support for YAML -- `autoconf/fitsable.py` — FITS file handling -- `autoconf/json_prior/` — JSON-based configuration priors -- `autoconf/tools/` — Utility decorators and helpers -- `autoconf/mock/` — Mock objects for testing +## Public API -## Key Rules +The public surface is defined authoritatively in `autoconf/__init__.py` — read +it rather than trusting a hand-maintained list. Canonical import: + +```python +from autoconf import conf +``` -- All files must use Unix line endings (LF) -- If changing public API, note it in your PR description — all downstream PyAuto packages depend on this +Key surfaces: `Config` / `conf.instance`, `output_to_json` / `from_json` +(`dictable.py`), `output_to_fits` / `ndarray_via_fits_from` (`fitsable.py`). -## Working on Issues +## Key rules / footguns + +- All files use Unix line endings (LF, `\n`) — never `\r\n`. +- This is the base config/IO layer: a public-API change here can break + PyAutoFit, PyAutoArray, PyAutoGalaxy, and PyAutoLens. Flag it loudly. +- YAML dict keys are lowercased on load (`muJy` → `mujy`); keep config keys and + any matching Python registries snake_case-lowercase. + +## 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_autoconf/` -4. Ensure all tests pass before opening a PR. -5. If changing public API, clearly document what changed — PyAutoFit, PyAutoArray, PyAutoGalaxy, and PyAutoLens all depend on this package. -## 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_autoconf/`. +4. If you changed public API, say so explicitly — PyAutoFit, PyAutoArray, + PyAutoGalaxy, and PyAutoLens all depend on this package and 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 3083eeb..eb8aadc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,65 +1,5 @@ -# PyAutoConf - -**PyAutoConf** is the configuration management library for the PyAuto ecosystem. It handles object serialization/deserialization via YAML, JSON-based priors and configuration generation, and provides utility tools for scientific Python applications. - -- Package name: `autoconf` -- Requires Python >= 3.12 - -## Repository Structure - -- `autoconf/` — Main package - - `conf.py` — Core configuration system - - `dictable.py` — Dictionary/serialization support - - `fitsable.py` — FITS file handling - - `json_prior/` — JSON-based configuration priors - - `tools/` — Utility decorators and helpers - - `mock/` — Mock objects for testing -- `test_autoconf/` — Test suite (pytest) - -## Commands - -### Install -```bash -pip install -e ".[dev]" -``` - -### Run Tests -```bash -python -m pytest test_autoconf/ -python -m pytest test_autoconf/ -s -``` - -### Codex / sandboxed runs - -When running Python from Codex or any restricted environment, set writable cache directories: - -```bash -NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autoconf/ -``` - -## 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. +# PyAutoConf — 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 diff --git a/README.md b/README.md index c7cec97..6e0c360 100644 --- a/README.md +++ b/README.md @@ -1 +1,56 @@ # PyAutoConf + +**PyAutoConf** (package `autoconf`) is the configuration, serialization, and +I/O foundation of the [PyAuto](https://github.com/PyAutoLabs) ecosystem. It +provides a layered configuration system with workspace overrides, dict / JSON / +CSV serialization of arbitrary objects, and FITS I/O. + +`PyAutoFit`, `PyAutoArray`, `PyAutoGalaxy`, and `PyAutoLens` all depend on +autoconf: it supplies their packaged default config, the object-serialization +used to persist models and results, and shared utilities (`test_mode`, +`jax_wrapper`). Centralising these here keeps a single, consistent config and +I/O layer beneath every library. + +## Install + +```bash +pip install autoconf +``` + +## Examples + +Layered config — read a directory of YAML into a queryable `Config`: + +```python +from autoconf.conf import Config + +config = Config("path/to/config") # directory of YAML files +value = config["general"]["model"]["section"]["value"] +``` + +JSON serialization — round-trip arbitrary Python objects: + +```python +from autoconf.dictable import output_to_json, from_json + +data = {"sersic_index": 4.0, "centre": [0.0, 0.0]} +output_to_json(data, "model.json") +restored = from_json("model.json") # == data +``` + +FITS I/O — write and read a NumPy array: + +```python +import numpy as np +from autoconf.fitsable import output_to_fits, ndarray_via_fits_from + +arr = np.arange(12.0).reshape(3, 4) +output_to_fits(values=arr, file_path="demo.fits", overwrite=True) +loaded = ndarray_via_fits_from(file_path="demo.fits", hdu=0) # np.allclose(arr, loaded) +``` + +## Links + +- Source & tests: [`autoconf/`](autoconf), [`test_autoconf/`](test_autoconf) +- Agent/contributor instructions: [`AGENTS.md`](AGENTS.md) +- Ecosystem: [PyAutoLabs on GitHub](https://github.com/PyAutoLabs)