From 00553adb3af35f62e49112e764c6d53ea700cde3 Mon Sep 17 00:00:00 2001 From: Guillaume GAUTREAU Date: Fri, 31 Jul 2026 09:37:58 +0200 Subject: [PATCH 1/3] Add AGENTS.md pointing agents at the PanGBank skill Points to the canonical skill in PanGBank-api and records what the notebooks do not spell out: ppanggolin metadata rewrites the HDF5 in place, and re-running a --download into a directory holding an annotated pangenome deletes it. --- AGENTS.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2c3ba43 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,33 @@ + +# AGENTS.md + +Guidance for AI agents working in this repository or with the PanGBank resource. + +## Read the agent skill first + +**** documents the REST API and its filters, the query traps that silently return wrong results, how to download and analyse a pangenome with PPanGGOLiN, how to project a user's own genome, and the citation requirements. Several of its traps produce plausible but incorrect answers with no visible symptom, so read it before writing any PanGBank query. + +Short web entry point: + +## Always true + +- **Never scrape .** Single-page app; the HTML carries no data, and dynamic routes return HTTP 404 server-side while rendering fine in a browser. Use . +- **Pin the release** with `only_latest_release=true`, or filter client-side on `collection_release.version`. Without it results are summed across every release. +- **`taxon_name` needs the GTDB rank prefix** and is an exact match: `g__Escherichia` works, `Escherichia` returns nothing. + +## Citation + +Results derived from PanGBank must cite PanGBank and PPanGGOLiN, plus panRGP when RGPs or insertion spots are used, and panModule when conserved modules are used. Full references in the skill. Data are CC BY-SA 4.0 (attribution *and* share-alike); source is CeCILL v2.1. + +## Specific to this repository + +The notebooks ship **precomputed outputs** (git-lfs): the shell commands shown are for transparency and reproducibility, and you are not expected to run the expensive ones to follow the tutorial. + +Before reproducing the annotation workflow, know two things the notebooks do not spell out: + +- **`ppanggolin metadata` rewrites the HDF5 in place**, so the file no longer matches the API's `file_md5sum`. Work on a copy (`cp pangenome.h5 pangenome_annotated.h5`), and keep the pristine download read-only (`chmod 444`) — a mutating command then fails cleanly with `PermissionError` instead of silently rewriting it. +- **Do not re-run a `--download` command into an outdir containing an annotated pangenome.** The CLI treats the md5 mismatch as corruption and deletes the file before re-downloading; if the network or the API is unavailable at that moment, the annotated file is gone with nothing in its place. + +When adapting a notebook to another species, pin the release explicitly (`--release-version`) rather than relying on `--latest-only`: pangenome ids are not stable across releases, and "latest" changes under you. + +Analytical points worth preserving when editing the notebooks: join RGP → spot with a **left** join (not every RGP is assigned to a spot, so an inner join silently drops part of the plasticity), and state whether a projection used `--fasta` or `--anno`, since completeness and genome-specific family counts differ materially between the two. From 01f9d79149850f48342dd0bec893500b55eacd06 Mon Sep 17 00:00:00 2001 From: Guillaume GAUTREAU Date: Fri, 31 Jul 2026 11:29:59 +0200 Subject: [PATCH 2/3] State the 1-request-per-30-seconds limit in AGENTS.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The rate limit was stated in the skill and in llms.txt but not here, so an agent working in this repository — the population AGENTS.md actually serves — never saw it. PanGBank runs on a shared Genoscope machine with no dedicated resources and no monitoring, so an overload is invisible until the service goes down for everyone. --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 2c3ba43..ea72b24 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,7 @@ Short web entry point: - **Never scrape .** Single-page app; the HTML carries no data, and dynamic routes return HTTP 404 server-side while rendering fine in a browser. Use . - **Pin the release** with `only_latest_release=true`, or filter client-side on `collection_release.version`. Without it results are summed across every release. - **`taxon_name` needs the GTDB rank prefix** and is an exact match: `g__Escherichia` works, `Escherichia` returns nothing. +- **At most 1 HTTP request every 30 seconds**, across all routes, never parallelised across agents or threads. PanGBank runs on a shared Genoscope machine with no dedicated resources and no monitoring: an overload is invisible until the service goes down for everyone. Call `/pangenomes/count/` before any listing, filter server-side, use `limit=100`, and download a pangenome once rather than re-fetching it. ## Citation From bac95603027c72e292e6d3d9cd58876ed5892cff Mon Sep 17 00:00:00 2001 From: Guillaume GAUTREAU Date: Fri, 31 Jul 2026 11:53:22 +0200 Subject: [PATCH 3/3] Soften how the rate limit describes the infrastructure The rule read "shared Genoscope machine with no dedicated resources and no monitoring". Stating in a public, agent-facing file that nothing is watched tells a bad actor exactly what goes unnoticed, and it undersells the resource to legitimate users. The constraint keeps all of its force from the part that matters: the infrastructure is shared, so an overload degrades the service for everyone else. --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ea72b24..e95caa8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ Short web entry point: - **Never scrape .** Single-page app; the HTML carries no data, and dynamic routes return HTTP 404 server-side while rendering fine in a browser. Use . - **Pin the release** with `only_latest_release=true`, or filter client-side on `collection_release.version`. Without it results are summed across every release. - **`taxon_name` needs the GTDB rank prefix** and is an exact match: `g__Escherichia` works, `Escherichia` returns nothing. -- **At most 1 HTTP request every 30 seconds**, across all routes, never parallelised across agents or threads. PanGBank runs on a shared Genoscope machine with no dedicated resources and no monitoring: an overload is invisible until the service goes down for everyone. Call `/pangenomes/count/` before any listing, filter server-side, use `limit=100`, and download a pangenome once rather than re-fetching it. +- **At most 1 HTTP request every 30 seconds**, across all routes, never parallelised across agents or threads. PanGBank runs on shared academic infrastructure: an overload degrades the service for every other user. Call `/pangenomes/count/` before any listing, filter server-side, use `limit=100`, and download a pangenome once rather than re-fetching it. ## Citation