📄 Add structured AGENTS.md with nested module guides by xroynard · Pull Request #373 · PLAID-lib/plaid

xroynard · 2026-04-17T22:58:39Z

Summary

Add a comprehensive AGENTS.md with nested guides for key modules, aligned with the v1.0.0 data model.

Changes

Root `AGENTS.md`

Project identity: role in the PLAID ecosystem, PyPI package name (pyplaid), downstream impact
Expected agent behavior: role, decision priorities, when-in-doubt rules
Efficiency and minimalism: keep changes surgical and small; # NOTE(shortcut): marker convention
Confidentiality section: rules for not leaking private repo names in public content
Tech stack: language, package manager (uv), build backend, ruff, pytest, docs
Project structure: annotated directory tree
Architecture and key concepts: core abstractions table (Sample, Infos, ProblemDefinition), storage pattern
Code conventions: ruff config, type hints, docstring conventions
Testing / Pull request rules / Commands / Contribution workflow

Nested `src/plaid/containers/AGENTS.md`

Key classes table: Sample (pydantic BaseModel, the main data container) and DefaultManager
Explicit note that the v1.0.0 reorganization removed Dataset, Features and FeatureIdentifier — a collection of samples is now read/written through the storage layer (see docs/source/upgrade_guide.md)
Design constraints (value object, minimal business logic, serialization through backends)
Downstream impact + testing guidance

Nested `src/plaid/storage/AGENTS.md`

Registry pattern architecture and how-it-works explanation
Step-by-step guide for adding a new backend (zarr / hf_datasets / cgns)
Design constraints (stateless, data integrity, contract-first)
Testing guidance (round-trip tests)

Notes

Documentation only — no source code, tests or public API changed.
The branch has been rebased on the current main (post v1.0.0); the body above reflects the files as they are on the branch, not the pre-v1 draft.

codecov · 2026-04-17T23:01:13Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

casenave

There is still mention of the large Dataset class, but we're on the verge to remove it. Could it be safer top wait for V1 ? There is a ProtoV1 branch where current work towards V1 is beeing done by Felipe. I think it would be better to adapt the agents to the V1 and merge it there instead of having obsololete references here and having to modify them later

xroynard · 2026-04-18T16:05:21Z

Bien vu. En effet, si le Dataset est en cours de refonte dans la branche ProtoV1, on peut :

Soit attendre la V1 et merger les AGENTS.md directement là-bas (adapté à la nouvelle architecture)
Soit merger maintenant en retirant la mention du "god class" et de la taille du Dataset, pour éviter d'ancrer des références obsolètes

Je pencherais pour l'option 2 : merger maintenant avec une version allégée (sans référence à la taille de Dataset ni au warning "god class"), puis faire un second pass post-V1 pour adapter les AGENTS.md à la nouvelle architecture. Qu'en penses-tu ?

casenave · 2026-04-18T16:15:29Z

Bien vu. En effet, si le Dataset est en cours de refonte dans la branche ProtoV1, on peut :

Soit attendre la V1 et merger les AGENTS.md directement là-bas (adapté à la nouvelle architecture)

Soit merger maintenant en retirant la mention du "god class" et de la taille du Dataset, pour éviter d'ancrer des références obsolètes

Je pencherais pour l'option 2 : merger maintenant avec une version allégée (sans référence à la taille de Dataset ni au warning "god class"), puis faire un second pass post-V1 pour adapter les AGENTS.md à la nouvelle architecture. Qu'en penses-tu ?

ok pour option 2

xroynard · 2026-04-18T16:44:13Z

Apologies for the previous comment in French -- switching to English as per repo convention.

Regarding the Dataset class mention: two options:

Merge now with a lighter version (remove the "large class" warning from containers/AGENTS.md) and adapt post-V1
Wait for V1 to land and merge AGENTS.md directly there

I lean towards option 1 to avoid blocking on V1 timeline. The containers AGENTS.md can be updated in a follow-up once the ProtoV1 architecture stabilizes. What do you prefer?

casenave · 2026-04-18T16:46:06Z

Apologies for the previous comment in French -- switching to English as per repo convention.

Regarding the Dataset class mention: two options:

Merge now with a lighter version (remove the "large class" warning from containers/AGENTS.md) and adapt post-V1

Wait for V1 to land and merge AGENTS.md directly there

I lean towards option 1 to avoid blocking on V1 timeline. The containers AGENTS.md can be updated in a follow-up once the ProtoV1 architecture stabilizes. What do you prefer?

ok for option 1, Xavier-bot

xroynard · 2026-06-18T15:17:40Z

Added an "Efficiency and minimalism" section to AGENTS.md (under "Expected agent behavior", before "Tech stack").

It distills token-reduction / minimalism conventions from internal reference repos into rules for coding agents working on plaid:

Solve the problem in front of you — no speculative config flags or abstraction layers.
Smallest change that works; reuse existing code before adding new abstractions.
No helper wrapping a single call site; extract only when reused or materially clearer.
Surgical edits — touch only the lines the task requires (no incidental reformatting / import reordering / renames).
Avoid speculative defensive code; validate inputs once at the boundary.
Mark a deliberate shortcut with a neutral # NOTE(shortcut): comment naming its ceiling and upgrade trigger.
Be concise in explanations and PR descriptions.

Note: this also fixed the branch after a previous bad push that had overwritten AGENTS.md with placeholder text — the file is now correct (239 lines).

xroynard · 2026-07-29T08:22:26Z

Mise à jour : corrections factuelles avant merge

J'ai poussé un commit (7a2040f) qui corrige plusieurs inexactitudes relevées en confrontant le contenu du AGENTS.md au code réel de main (structure v1.0.0). Toutes les corrections ont été vérifiées ligne à ligne contre les sources.

AGENTS.md (racine) :

Doc : Zensical, pas Sphinx — l'arbre disait « Sphinx documentation source » et l'étape 5 du workflow « Update Sphinx documentation », alors que la Tech stack indique (correctement) Zensical + mkdocstrings. Le repo contient docs/zensical.toml, docs/source/*.md, docs/generate_doc.sh et aucun conf.py. Corrigé en « Zensical (Markdown) ».
src/plaid/utils/ ajouté à l'arbre — répertoire réel (base.py, cgns_helper.py, cgns_worker.py) qui était absent.
plaidcheck → plaid-check — le script exposé dans pyproject.toml [project.scripts] est plaid-check (avec tiret) ; plaidcheck n'est que le nom du module interne.
Ruff : ignore = ["E501", "D107"] documenté — E501 étant ignoré, la limite de 88 caractères est en réalité appliquée par le formateur (ruff format), pas contrôlée par le linter. Ajout aussi du per-file-ignore "__init__.py" = ["F401"] (re-exports).

Non modifié (à dessein) : l'accord sur le retrait de la mention « god class »/taille de Dataset dans containers/AGENTS.md était déjà appliqué (option 1). Les guides containers/ et storage/ ont été re-vérifiés (Registry pattern, backends zarr/hf_datasets/cgns, procédure d'ajout de backend) et sont conformes au code — rien à corriger.

Dette de code adjacente (hors PR, à traiter côté code) : src/plaid/containers/sample.py (l.105, 253) référence encore FeatureIdentifier dans des docstrings, alors que ce type n'existe plus après v1.0.0.

La PR me semble mergeable après cette passe.

Add a comprehensive root AGENTS.md following modeles_d_agents best practices, plus nested AGENTS.md files for the containers and storage modules.

…nd confidentiality section - Remove all mentions of scimm and maestro (private repos) from public-facing content - Add confidentiality section warning agents not to mention private repos - Add PR title emoji rules from .github/pull_request_template.md - Add PR checklist reference

Sync the root, containers and storage AGENTS.md with the post-V1 repo: - root: fix project tree (drop removed bridges/pipelines/post/examples, add cli/types/viewer/downloadable_examples), fix Core abstractions table (Dataset/Features/FeatureIdentifier removed -> Sample/Infos/ProblemDefinition), doc tooling Sphinx -> Zensical, build command -> docs/generate_doc.sh - containers: Dataset/Features/FeatureIdentifier no longer exist; document Sample (pydantic BaseModel), DefaultManager and utils helpers - storage: add backend_api.py (BackendModule Protocol) and the BACKENDS registry

Distill the ponytail (minimal code, YAGNI ladder, deletion over addition) and caveman (terse communication, why over what) agent conventions into a PLAID-adapted ruleset. Includes explicit "never simplify away" guards for backward compatibility, API stability, validation, and data integrity.

…id-check, utils/, ruff ignores)

…, plaid-serve/viewer CLIs)

CLAassistant · 2026-08-04T14:26:21Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ xroynard
❌ probe

probe seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

…dded

xroynard · 2026-08-04T16:54:18Z

Review: coverage of nested guides

I audited the nested AGENTS.md coverage against the actual main layout. Structurally it's sound — guides sit at the right level (root + major package), no over-splitting into storage//containers/ sub-packages, and no dead references (both src/plaid/containers/ and src/plaid/storage/ exist on main).

Coverage is partial, though. Two sizeable packages remain undocumented:

src/plaid/viewer/ (~4.9k LOC) — the largest package after storage/, no guide

A self-contained subsystem: FastAPI backend + embedded trame/ParaView server, with an explicit responsibility boundary in its own docstring ("PLAID owns the UI shell… ParaView/trame owns the scientific visualization"). Exposes the plaid-viewer entry point.
This is the most significant gap — a package of that size with a distinct web/visualization architecture would clearly benefit from its own AGENTS.md.

src/plaid/cli/ (~2.2k LOC) — no guide (lower priority)

Holds the packaged entry points (plaid-check, plaid-serve) plus a ParaView plugin. External user-facing surface with its own conventions.

Suggested priority: 1) src/plaid/viewer/AGENTS.md, 2) src/plaid/cli/AGENTS.md.

The remaining absences are justified: utils/ is a catch-all (defensible), while types/ (73 LOC) and downloadable_examples/ (60 LOC) are trivial/declarative. The sub-packages under storage/ and containers/ are correctly covered by their parent guide.

casenave · 2026-08-05T06:07:23Z

+> Note: the v1.0.0 reorganization removed the `Dataset`, `Features` and
+> `FeatureIdentifier` classes. A collection of samples is now read/written through the
+> `storage` layer rather than a dedicated `Dataset` class. See `docs/source/upgrade_guide.md`.


Not sure that keeping mentions to old classes is usefull

casenave · 2026-08-05T06:13:25Z

+- Backends must be **stateless** -- all configuration is passed through function parameters.
+- Read/write operations must preserve **data integrity** exactly (no lossy conversions without explicit user consent).
+- The `common/` interfaces are the **contract** -- do not add backend-specific parameters to the public API without updating the contract first.
+- `zarr` is the primary backend and the most feature-complete. Use it as the reference when implementing others.


I don't think that zarr is the primary backend, but we can still use it as a reference.

casenave · 2026-08-05T06:13:44Z

+## Adding a new backend
+
+1. Create a new subdirectory under `storage/` (e.g., `storage/my_format/`).
+2. Implement a backend class conforming to the `BackendModule` Protocol
+   (`backend_api.py`), with its `reader.py` and `writer.py` following the interfaces in `common/`.
+3. Register the new backend by adding it to the `BACKENDS` dict in `registry.py`.
+4. Add round-trip tests (write then read) to verify data integrity.


That will never be used, I think we can remove this section

casenave · 2026-08-05T06:16:23Z

+> Note: the v1.0.0 reorganization removed the top-level `Dataset` re-export and the
+> `bridges/`, `pipelines/` and `post/` source packages under `src/plaid/`. Data is now
+> handled through `Sample` objects and the `storage` layer. (The top-level `examples/`
+> directory still exists — it holds usage scripts, not an importable package.)
+> See `docs/source/upgrade_guide.md`.


note sure that this context is usefull for the agents

casenave

Some minimal remarks, thanks !

xroynard requested a review from a team as a code owner April 17, 2026 22:58

casenave reviewed Apr 18, 2026

View reviewed changes

casenave changed the title ~~docs: add structured AGENTS.md with nested module guides~~ 📄 Add structured AGENTS.md with nested module guides Apr 18, 2026

xroynard changed the title ~~📄 Add structured AGENTS.md with nested module guides~~ 📝 docs: add structured AGENTS.md with nested module guides Apr 18, 2026

casenave changed the title ~~📝 docs: add structured AGENTS.md with nested module guides~~ 📄 docs: add structured AGENTS.md with nested module guides Apr 18, 2026

xroynard changed the title ~~📄 docs: add structured AGENTS.md with nested module guides~~ 📄 Add structured AGENTS.md with nested module guides Apr 18, 2026

xroynard force-pushed the feature/agents-md branch from 8298dfd to 406bf21 Compare June 5, 2026 20:43

xroynard force-pushed the feature/agents-md branch from f2ade34 to 2294af1 Compare June 18, 2026 12:46

xroynard and others added 7 commits August 4, 2026 14:25

docs: add structured AGENTS.md with nested module guides

a228448

Add a comprehensive root AGENTS.md following modeles_d_agents best practices, plus nested AGENTS.md files for the containers and storage modules.

docs: add communication rules (English, direct tone)

cd4b3b2

docs: fix factual inaccuracies in AGENTS.md (Zensical not Sphinx, pla…

78ef2e5

…id-check, utils/, ruff ignores)

docs: align AGENTS.md with current main (examples/, storage callbacks…

9c5be0f

…, plaid-serve/viewer CLIs)

xroynard force-pushed the feature/agents-md branch from 7a2040f to 9c5be0f Compare August 4, 2026 14:26

docs(changelog): note AGENTS.md contributor guides under Unreleased/A…

f987cc9

…dded

casenave reviewed Aug 5, 2026

View reviewed changes

casenave requested changes Aug 5, 2026

View reviewed changes

Uh oh!

Conversation

xroynard commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Root AGENTS.md

Nested src/plaid/containers/AGENTS.md

Nested src/plaid/storage/AGENTS.md

Notes

Uh oh!

codecov Bot commented Apr 17, 2026

Codecov Report

Uh oh!

casenave left a comment

Choose a reason for hiding this comment

Uh oh!

xroynard commented Apr 18, 2026

Uh oh!

casenave commented Apr 18, 2026

Uh oh!

xroynard commented Apr 18, 2026

Uh oh!

casenave commented Apr 18, 2026

Uh oh!

xroynard commented Jun 18, 2026

Uh oh!

xroynard commented Jul 29, 2026

Mise à jour : corrections factuelles avant merge

Uh oh!

CLAassistant commented Aug 4, 2026

Uh oh!

xroynard commented Aug 4, 2026

Review: coverage of nested guides

Uh oh!

casenave Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

casenave Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

casenave Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

casenave Aug 5, 2026

Choose a reason for hiding this comment

Uh oh!

casenave left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

xroynard commented Apr 17, 2026 •

edited

Loading

Root `AGENTS.md`

Nested `src/plaid/containers/AGENTS.md`

Nested `src/plaid/storage/AGENTS.md`