Review fixes; README and CLAUDE.md finalised
- cancel reverts only the run's commits (base..HEAD), never the caller's edits - validator diffs base..HEAD, not the working tree - fix commits carry their Co-Authored-By line; no redundant end benchmark - score.py: clear error on a missing labels file; docstring says end is not passed - usage lines; README and CLAUDE.md for the generic workflow Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
0de006bcb2
commit
388619685a
10 files changed
+63
-30
No files matched your search
@@ -1,31 +1,57 @@
|
||||
# detectors
|
||||
|
||||
The AIMsight anomaly detectors, and their improvement. One detector per anomaly family of the displacements, classified into events by `scripts/categories.py`; `scripts/data.py` reads a station folder. Standard library only (Python 3).
|
||||
The AIMsight anomaly detectors, and the workflow that improves them. Python 3, standard library only.
|
||||
|
||||
## The detectors
|
||||
|
||||
One detector per anomaly family of the displacements, in `scripts/`:
|
||||
|
||||
| Family | Detector |
|
||||
|---|---|
|
||||
| Visibility | `visibility.py` |
|
||||
| Obstruction | `obstruction.py` |
|
||||
| Target issue | `target_issue.py` |
|
||||
| Thermal displacement | `thermal_displacement.py` |
|
||||
| No data | `no_data.py` |
|
||||
| Displacement | `displacement.py` |
|
||||
|
||||
`categories.py` runs them all and classifies their episodes into events, one line per event; `data.py` reads a station folder (`displacement/`, `metrics/`, `camera/`).
|
||||
|
||||
```bash
|
||||
python3 scripts/categories.py <station folder> --from YYYY-MM-DD --to YYYY-MM-DD
|
||||
python3 scripts/categories.py <station folder> --from YYYY-MM-DD --to YYYY-MM-DD # --chunk N, --history N
|
||||
python3 scripts/visibility.py <station folder> # one detector alone
|
||||
```
|
||||
|
||||
The station folder: `displacement/`, `metrics/`, `camera/` (the format of `data/<STATION>/` in Diagnostic-app).
|
||||
`thresholds.md` is the registry of the detectors' thresholds and what each was tuned on.
|
||||
|
||||
- `scripts/`: the detectors (`visibility.py`, `obstruction.py`, `target_issue.py`, `thermal_displacement.py`, `no_data.py`, `displacement.py`), `categories.py`, `data.py`.
|
||||
- `thresholds.md`: the registry of the detectors' thresholds.
|
||||
## Improving them: `/detectors:wf-improve`
|
||||
|
||||
## The wf-improve workflow: a Claude Code plugin
|
||||
The repository is also a Claude Code plugin (`.claude-plugin/plugin.json`). Its workflow improves the detectors on a range of data where they perform poorly, given labels as the truth on that range:
|
||||
|
||||
The repository is also a Claude Code plugin (`.claude-plugin/plugin.json`), to be mounted as `detectors/` in a working repository that has `labeling/` (the labels, `labeling/auto/<STATION>.jsonl`; the analyses, `labeling/auto/analyses/`), `data/` and `agent-tools/`: Diagnostic-app, where it is a submodule.
|
||||
1. measures before: the score on the range, and a benchmark on a reference truth (every labelled station);
|
||||
2. the `upgrader` agent compares the detectors' events with the labels and fixes the detectors with general rules, one commit per fix;
|
||||
3. the `validator` agent, an LLM-as-judge that does not read the upgrader's diagnosis, keeps the fixes, removes some, or cancels them: no station may go back, no overfitting;
|
||||
4. a summary.
|
||||
|
||||
- `skills/wf-improve/`: `/detectors:wf-improve <analysis>` (`SKILL.md`), the session that improves the detectors from an analysis of the Data page, without overfitting; its tools in `scripts/`, run from the working repository: `regression.py` (the benchmark, all labels of `labeling/auto/`), `score.py` (the score of a range), `sensors.py` (the sensors of each event).
|
||||
- `agents/`: `upgrader` (diagnoses and fixes the detectors) and `validator` (LLM-as-judge: keeps, removes or cancels the fixes), called `detectors:<name>`.
|
||||
- `wf-improve/`: the sessions, one folder `<session>_<analysis>/` each, written by the skill.
|
||||
The result: detectors a little better on the range without going back elsewhere, or unchanged. Nothing is pushed.
|
||||
|
||||
From the working repository:
|
||||
The caller gives the context of each run: the range, the labels, the reference truth, the families document, any context documents, the output folder, and its own rules (git branch, what else to commit). For example:
|
||||
|
||||
```bash
|
||||
claude --plugin-dir detectors # then /detectors:wf-improve <analysis>
|
||||
python3 detectors/skills/wf-improve/scripts/regression.py # the benchmark
|
||||
claude --plugin-dir detectors -p "/detectors:wf-improve DETECTORS: detectors/. STATION: data/NORDEND. \
|
||||
FROM: 2026-11-04. TO: 2026-11-08. LABELS: labeling/auto/NORDEND.jsonl. \
|
||||
REFERENCE: --labels labeling/auto --data data. FAMILIES: labeling/familles.md. \
|
||||
CONTEXT: labeling/auto/analyses/NORDEND_x/rapport.md. OUT: detectors/runs/NORDEND_x/."
|
||||
```
|
||||
|
||||
The session commits the detectors here, on `main`, without pushing: push `detectors` so that everyone has the updated detectors.
|
||||
Labels: JSONL, one per line, `{"id", "debut", "fin", "categorie", "description"}` (UTC ISO times, `categorie` = the family).
|
||||
|
||||
Copied from Support-Agent on 2026-11-13 (commit 48a3092); the detectors now evolve here.
|
||||
- `skills/wf-improve/SKILL.md`: the workflow; its tools in `skills/wf-improve/scripts/`: `score.py` (the score of a range), `regression.py` (the benchmark), `sensors.py` (the sensors of each event).
|
||||
- `agents/`: `upgrader`, `validator` (called `detectors:<name>`).
|
||||
|
||||
```bash
|
||||
python3 skills/wf-improve/scripts/score.py <station folder> --labels <labels.jsonl> --from YYYY-MM-DD --to YYYY-MM-DD
|
||||
python3 skills/wf-improve/scripts/regression.py --labels <folder of <STATION>.jsonl> --data <folder of <STATION>/>
|
||||
```
|
||||
|
||||
Copied from Support-Agent on 2026-11-13 (commit 48a3092); the detectors now evolve here. Used by Diagnostic-app, where it is the `detectors/` submodule.
|
||||
Reference in new issue
Block a user