From cff3c7c9ac53fb66274b9c0149fb0d3408e87fcc Mon Sep 17 00:00:00 2001 From: jeremy-wayland Date: Tue, 6 Oct 2026 10:49:20 +0200 Subject: [PATCH 1/2] Simplify AGENTS.md for agent-facing docs. Keep policy and non-obvious dev commands; drop redundant tool-boundary detail and doc links. Co-authored-by: Cursor --- AGENTS.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index efe3e4b..e0dada5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,25 +1,17 @@ # Agent Guide -Pasteur is a Rust workspace for local clinical-AI simulation and evaluation. - ## Safety - Never commit patient data, PHI, real clinical datasets, or proprietary models. -- `pasteur-cli` performs local compute only; keep it network-free. +- `pasteur-cli` is local compute only; keep it network-free. Hub I/O goes through the official `hf` CLI; download inputs first, then pass local paths. - Create Hugging Face model and dataset repositories as **private** by default. -## Tool boundary - -- Use `pasteur-cli` for simulation, evaluation, comparison, dataset cards, and its local cache. -- Use the official `hf` CLI for Hub downloads, uploads, repositories, and the Hub cache. -- Download remote inputs before passing local paths to `pasteur-cli`. - ## Development +Git worktrees must not share a `CARGO_TARGET_DIR`: Cargo hashes workspace crates the same way in each checkout, so a shared target dir silently mixes artifacts from different checkouts. + ```bash cargo fmt --all --check cargo clippy --workspace -- -D warnings cargo test --workspace --exclude pypasteur-bindings ``` - -See [README.md](README.md), [CONTRIBUTING.md](CONTRIBUTING.md), and the [CLI reference](cli/README.md). From bb344ebaf2fe3eb49cfa1c36b564d23d83a79019 Mon Sep 17 00:00:00 2001 From: jeremy-wayland Date: Fri, 9 Oct 2026 12:17:02 +0000 Subject: [PATCH 2/2] Bring agent docs up to date with #2 and #3. - AGENTS.md: state the patient-data upload rule that README.md and cli/README.md point to; add --locked to match CI and CONTRIBUTING.md. - pasteur-rs skill: cover --task (multiclass, multilabel, regression), --targets and the regression cutoff; drop the link to AGENTS.md workflows that never existed there. - cli/README.md: describe multi-output predictions columns and what all_agree compares per task. - README.md: point to AGENTS.md for rules, skills for the workflow. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/pasteur-rs/SKILL.md | 51 ++++++++++++++++++------------ AGENTS.md | 5 +-- README.md | 2 +- cli/README.md | 2 +- 4 files changed, 35 insertions(+), 25 deletions(-) diff --git a/.agents/skills/pasteur-rs/SKILL.md b/.agents/skills/pasteur-rs/SKILL.md index 9d329a5..5311f14 100644 --- a/.agents/skills/pasteur-rs/SKILL.md +++ b/.agents/skills/pasteur-rs/SKILL.md @@ -1,44 +1,53 @@ --- name: pasteur-rs -description: Local Pasteur simulation and evaluation CLI. Use with the hf CLI skill for Hub download/upload. Complements hf skills — does not replace them. +description: Local Pasteur simulation and evaluation CLI (pasteur-cli) for binary, multiclass, multilabel, and regression ONNX models. Use with the hf-cli skill for Hub download/upload; pasteur-cli never touches the network. --- # Pasteur Rust (pasteur-cli) -Use this skill together with `hf skills add`. **All Hugging Face Hub I/O goes through `hf`.** `pasteur-cli` only reads/writes local files. +`pasteur-cli` only reads and writes local files. **All Hugging Face Hub I/O goes through `hf`** ([hf-cli](../hf-cli/SKILL.md)): download inputs first, pass local paths, upload results afterwards. -## When to use which tool +## Commands | Goal | Command | |------|---------| -| Download dataset/model | `hf download ...` | -| Upload simulation bundle | `hf repos create ... --private` + `hf upload` | -| Run simulators (blackout/jitter/flipper) | `pasteur-cli simulate --input --labels ` | -| Generate README | `pasteur-cli card --input ./output --source-dataset ... --dest-repo ...` | -| Evaluate/compare models | `pasteur-cli evaluate/compare --sim-root ./sim --labels ... --model ...` | -| Flipper stability | `pasteur-cli evaluate flipper --sim-root ./sim --labels ... --model ... --flip-threshold 0.5` | +| Download a dataset or model | `hf download ...` | +| Simulate blackout/jitter/flipper | `pasteur-cli simulate --input --labels --output ./sim` | +| Score one model | `pasteur-cli evaluate --sim-root ./sim --labels --model ` | +| Score several models | `pasteur-cli compare --sim-root ./sim --labels ... --model a.onnx --model b.onnx [--predictions-out preds.parquet]` | +| Write the dataset card | `pasteur-cli card --input ./sim --source-dataset --dest-repo ` | +| Publish a bundle | `hf repos create --type dataset --private`, then `hf upload` | -## Required layout before upload +`` is `blackout`, `jitter`, or `flipper`. Flags and defaults: [cli/README.md](../../../cli/README.md). -After `simulate --labels `, the bundle must look like: +## Task types + +Pass the same `--task` to `simulate`, `evaluate`, and `compare`; it must match the model's `metadata.json` `task_type`. + +| `--task` | Truth | `--positive-group-id` | `--flip-threshold` | +|----------|-------|-----------------------|--------------------| +| `binary` (default) | `--labels` | The positive cohort | Probability cutoff, default 0.5 | +| `multiclass` | `--labels` | One per class, in `output.classes` order; cohorts must partition the rows | Unused (argmax) | +| `multilabel` | `--labels` | One per label, in `output.classes` order | Default for labels without `output.thresholds`, 0.5 | +| `regression` | `--targets --target-col ` | Unused | Clinical cutoff in target units. No default; pass the same value to `simulate` and to `evaluate`/`compare` | + +For classifiers, `--flip-threshold` belongs to `evaluate`/`compare` only; `simulate` rejects it. Cohorts are matched to model outputs by position; Pasteur cannot check that they line up. + +## Bundle layout ``` -output/ +sim/ clean/clean.parquet blackout/blackout.parquet - jitter/jitter_*.parquet - flipper/flipper.parquet + jitter/jitter_.parquet + flipper/flipper.parquet # classifiers: needs --labels; regression: --targets and --flip-threshold ``` -Input schemas (clean parquet, `groups.parquet` labels) are documented in [Data Contracts](../../../docs/source/data-contracts.rst). - -`flipper/` is only written when `--labels` is passed to `simulate` (flipper needs labels to sample cross-label pairs; blackout/jitter don't). Its parquet also carries meta columns (`pair_id`, `step`, `t`, `source_a_row`, `source_b_row`, `label_a`, `label_b`) alongside the interpolated features — `evaluate`/`compare sim_type=flipper` strip these before scoring. - -Run `pasteur-cli card` to add `README.md`, then upload each folder with `hf upload`. +Schemas: inputs and `metadata.json` in [Data Contracts](../../../docs/source/data-contracts.rst), outputs in [Output Layout](../../../docs/source/outputs.rst), metrics in [Reading the results](../../../docs/source/metrics.rst). -## Full workflows +## Publishing -See [AGENTS.md](../../../AGENTS.md) in the pasteur-core repo root for copy-paste agent workflows (simulate → publish, evaluate, compare + predictions). +Only publish simulations of public or synthetic data. Run `pasteur-cli card` to add `README.md`, then upload the bundle with `hf upload` to a private repo. ## Build diff --git a/AGENTS.md b/AGENTS.md index e0dada5..a630f0c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ - Never commit patient data, PHI, real clinical datasets, or proprietary models. - `pasteur-cli` is local compute only; keep it network-free. Hub I/O goes through the official `hf` CLI; download inputs first, then pass local paths. - Create Hugging Face model and dataset repositories as **private** by default. +- Only publish simulations of public or synthetic data. Bundles keep each patient's row ID, so never upload one built from patient data, even to a private repo. ## Development @@ -12,6 +13,6 @@ Git worktrees must not share a `CARGO_TARGET_DIR`: Cargo hashes workspace crates ```bash cargo fmt --all --check -cargo clippy --workspace -- -D warnings -cargo test --workspace --exclude pypasteur-bindings +cargo clippy --workspace --locked -- -D warnings +cargo test --workspace --locked --exclude pypasteur-bindings ``` diff --git a/README.md b/README.md index e1f9f5a..2b7fe0d 100644 --- a/README.md +++ b/README.md @@ -98,4 +98,4 @@ cargo test --workspace --exclude pypasteur-bindings See [CONTRIBUTING.md](CONTRIBUTING.md). Pushing a `v*` tag runs `.github/workflows/release.yml`. -Automation: publishing simulations of public or synthetic datasets to Hugging Face is described in [AGENTS.md](AGENTS.md), with agent skills under [`.agents/skills/`](.agents/skills/). Never publish bundles made from patient data. +Automation: the rules for agents are in [AGENTS.md](AGENTS.md), and the publishing workflow is in the agent skills under [`.agents/skills/`](.agents/skills/). Never publish bundles made from patient data. diff --git a/cli/README.md b/cli/README.md index 1bda6fd..3635f1b 100644 --- a/cli/README.md +++ b/cli/README.md @@ -153,7 +153,7 @@ Same flags as `evaluate`, except: - `--predictions-out` writes a local per-patient predictions parquet - A single `--contract` applies to every model -**Predictions schema:** `source_row_id`, `variant_name`, `label`, one f64 column per model (stem of model path), `all_agree` (all models on the same side of 0.5). Regression writes `target` instead of `label`, and `all_agree` compares sides of `--flip-threshold` (null without one). +**Predictions schema:** `source_row_id`, `variant_name`, `label`, one f64 column per model (stem of model path), `all_agree` (every model makes the same decision). Binary decisions are the side of a fixed 0.5. Multiclass and multilabel write `label__` and `__` per class; their decisions are the argmax, or the set of labels at or over each threshold. Regression writes `target` instead of `label`, and `all_agree` compares sides of `--flip-threshold` (null without one). The `--output` directory must already exist.