Skip to content

AGENTS.md

Latest commit

 

History

History
119 lines (91 loc) · 4.92 KB

AGENTS.md

File metadata and controls

119 lines (91 loc) · 4.92 KB
Raw

PyAutoFit — Agent Instructions

Canonical, agent-agnostic instructions for this repo. CLAUDE.md imports this file; any tool that does not process @-imports should read this directly.

What this repo is

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.

Quick commands

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)

In a sandboxed / restricted environment, point numba and matplotlib at writable caches:

NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autofit/

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.)

Configuration & defaults

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:

import autofit as af

Key subsystems: non_linear/search/ (MCMC: emcee/zeus; nested: dynesty, nautilus; 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 EP seam rule: autofit/graphical is two layers — the inner factor-graph/message engine and the declarative/ user layer. A new statistical capability in the inner layer must land in the same PR with its declarative expression or an explicit "not exposed" row in the lowering-contract table (autofit/graphical/README.md §8), plus a seam test where behaviour crosses the boundary (test_autofit/graphical/test_declarative_deterministic.py is the pattern). Capabilities that exist below but are silently absent above are the seam's known failure mode (see PyAutoFit#1336/#1337).
  • 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 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.

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.