From 0fa517dbe0d8aa6f2e24d1dae49b4c219caa8909 Mon Sep 17 00:00:00 2001 From: Ramdam17 Date: Sun, 4 Oct 2026 10:09:47 -0400 Subject: [PATCH 1/2] docs: add a minimal AGENTS.md and fix the Shiny link of the README AGENTS.md gives coding agents the facts that are stable today: how to install, how to run the tests and what a green run does not cover, the reference-test-first rule, and what not to touch. The README pointed to hypyp/app for the Shiny dashboards, which live in hypyp/shiny. Co-Authored-By: Claude Fable 5.1 --- AGENTS.md | 39 +++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 2 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..81d2ac7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,39 @@ +# AGENTS.md + +This file tells coding agents how to work in the HyPyP repository. It is deliberately short and contains only facts that are stable today. HyPyP is a Python library for hyperscanning analysis: it computes inter-brain connectivity and related statistics on EEG and fNIRS recordings of two or more participants. Its results end up in scientific publications, so a silent change in a computed value is the most serious defect a contribution can introduce. + +## Install + +The project uses `uv` with a committed lock file and requires Python 3.11 or later. Install the development environment from the repository root: + +```bash +uv sync --group dev +``` + +The accelerated backends are optional extras and are not installed by default. Add them only when the task needs them: `--extra numba`, `--extra torch`, `--extra metal` (Apple Silicon only) and `--extra cupy` (NVIDIA CUDA 12 only). + +## Run the tests + +```bash +uv run python -m pytest tests/ +``` + +Tests for a backend that is not installed are skipped, not failed. A green run without the extras therefore says nothing about the Numba, torch, Metal or CUDA code paths; say so when you report a result, and report the number of skipped tests along with the number that passed. + +## Rules for changing code + +When a change may alter a computed value, write an independent reference test first and see it fail, then make the fix. An independent reference is a value obtained without the code under test: a closed-form result on a synthetic signal, or a different trusted implementation. A test that only checks the shape of an output, or that compares one HyPyP backend with another, is not a reference test. + +Do not change a formula, a default parameter, a normalisation or a sign convention on your own judgement. These are choices of scientific method. Describe the problem, cite the literature, and leave the decision to a maintainer. + +Keep a pull request to one subject, and state in its description whether it changes any numerical result. + +## What not to touch + +Do not edit `uv.lock` by hand; change `pyproject.toml` and let `uv lock` regenerate it. Do not edit `docs/requirements.txt` by hand either: it is generated by `update_docs_requirements.sh`. Do not add a dependency without asking. + +Do not modify the sample data in `hypyp/data/` and `tests/data/`, and do not add recordings of real participants to the repository. + +The fNIRS code under `hypyp/fnirs/` and the Shiny dashboards under `hypyp/shiny/` have their own maintainer and an open draft pull request. Ask before changing them. + +Releases, tags and publication to PyPI are done by a maintainer with a dedicated procedure. Do not bump the version, create a tag or publish. diff --git a/README.md b/README.md index a9e0f4a..f5c8af5 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ For getting started with HyPyP, we have designed a little walkthrough: [getting_ 🌊 [wavelet/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/wavelet) — Continuous Wavelet Transform and Wavelet Transform Coherence (Patrice) -📊 [shiny/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/app) — Shiny dashboards, install using `uv sync --extra shiny` (Patrice) +📊 [shiny/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/shiny) — Shiny dashboards, install using `uv sync --extra shiny` (Patrice) ## Developer Installation (uv) From 9429fb221f354417d091c94eddeb025bc73ecbbd Mon Sep 17 00:00:00 2001 From: Ramdam17 Date: Sun, 4 Oct 2026 10:12:42 -0400 Subject: [PATCH 2/2] docs(agents): say that HyPyP works on pairs of participants Co-Authored-By: Claude Fable 5.1 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 81d2ac7..df9eec9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -This file tells coding agents how to work in the HyPyP repository. It is deliberately short and contains only facts that are stable today. HyPyP is a Python library for hyperscanning analysis: it computes inter-brain connectivity and related statistics on EEG and fNIRS recordings of two or more participants. Its results end up in scientific publications, so a silent change in a computed value is the most serious defect a contribution can introduce. +This file tells coding agents how to work in the HyPyP repository. It is deliberately short and contains only facts that are stable today. HyPyP is a Python library for hyperscanning analysis: it computes inter-brain connectivity and related statistics on EEG and fNIRS recordings of pairs of participants. Its results end up in scientific publications, so a silent change in a computed value is the most serious defect a contribution can introduce. ## Install