python-microscopy · David-Baddeley · Aug 20, 2026 · Jul 31, 2026 · Jul 31, 2026 · Jul 31, 2026
diff --git a/.gitignore b/.gitignore
@@ -58,6 +58,7 @@ pyme-bootstrap/package-lock.json
 PYME/experimental/_octree.html
 PYME/experimental/_treap.html
 PYME/experimental/_triangle_mesh.html
+AGENTS.local.md
 PYME/experimental/func_octree.c
 *.egg
 *.whl

diff --git a/.hgignore b/.hgignore
diff --git a/AGENTS.local.md.example b/AGENTS.local.md.example
@@ -0,0 +1,7 @@
+# Local, developer-specific agent instructions (not committed)
+#
+# Copy this file to AGENTS.local.md and fill in your own environment details.
+# AGENTS.local.md is gitignored so it stays specific to your checkout.
+
+## Conda environment
+- Use the conda environment at `/path/to/your/conda/envs/pyme` for this checkout.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,40 @@
+# Brief, incomplete, instructions for AI agents working in the codebase
+
+## General guidance
+- Use pep8 conventions for *new* python code
+- use numpy style docstrings
+- avoid extensive re-writes of exisiting code unless explicitly requested.
+- keep code backwards compatible to python 3.9 
+- there is a lot of legacy code, and docs are pretty out of date. Infer patterns with caution, and ask for clarification if needed.
+- new code should have a clear UI/algorithm split.
+- I like small files. Not a hard constraint, but start to think about refactoring at 500 lines, and get serious at 2k. 
+
+## Internals
+### Data model
+We use specific abstractions which sit slightly higher than e.g. numpy arrays or pandas dataframes and encapsulate
+meta along with data. See [docs/DataModel.rst]
+
+### Algorithms and recipe modules
+When implementing a new algorithm for PYME, there are 2 things to implement:
+- The core algorithm. This is fairly flexible as to how it's implemented and how it's inputs and outputs are structured.
+- A recipe module. This traits based class defines the interface (contract) between the algorithm and the rest of PYME. It defines parameters, takes input in one of the our data abstractions, returns output in one of our data abstractions, and propagates metadata. 
+- Recipe modules must be idempotent (with specific exceptions for IO modules). 
+- Recipe modules can be chained to form a data-flow language, and a recipe (a connected graph of recipe modules) can be serialised to .yaml. 
+- Recipe naming and parameterisation needs consideration (and human review) as it effectively becomes public API (module names are visible to users, and form the basis of user workflow serialisation). There is a high barrier to renaming or removing parameters on extant recipe modules.
+- In most cases the UI / view is autogenerated from the recipe module (TraitsUI), but they can contain hints as to how the view should be arranged if the autogenerated view is insufficient. 
+
+
+## Testing
+- New algorithmic and utility code should have unit tests
+- We use pytest
+- UI code has anexemption
+- Testing environment is headless
+- Unit tests live in the top levet /tests folder. Within the tests folder, structure mirrors the main PYME tree.
+- tests are run using the following `pytest -v tests/ --cov=PYME` in the top level
+- some algorithms are statistical, so will not always return the same result. Care is needed when choosing tests in these circumstances.
+
+## Building and running
+- Doing a full build and venv creation is time consuming (lots of dependencies, a fair bit of compiled code)
+- Typical dev pattern is to work from a conda environment using an inplace editable install, ie `pip install --no-deps --no-build-isolation --editable .`, which will usually already exist, and to do no additional install steps for python code. Changes to c and cython code will require re-running this in the dev conda environment. 
+- If a file `AGENTS.local.md` exists at the repo root, read it first — it records which conda environment to use for this checkout.
+- If `AGENTS.local.md` does not exist, ask the developer which conda environment to use, and offer to create `AGENTS.local.md` with that environment name.
diff --git a/BUILD.md b/BUILD.md
@@ -38,7 +38,7 @@ Obviously substituting the path to the un-packed wheel. It's a bit of a judgemen
 
 ## Editable install (replaces `python setup.py develop`)
 
-Ensure `build`,  `meson` and `meson-python` are installed alongside standard install dependencies
+Ensure `build`,  `meson`, `meson-python`, and `ninja` are installed alongside standard build-time dependencies (`numpy`, `cython`)
 
 ```bash
 pip install --no-build-isolation --editable .  

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md