feat: implement reproducible PROTEAN baseline pipeline

README.md

@@ -3,15 +3,20 @@
 Research code for **server-side prototype aggregation in PROTEAN** using class-specific
 sample support, for rare attack detection under non-IID federated intrusion detection.
 
-The study modifies only how the server combines local class prototypes:
+The planned study modifies only how the server combines local class prototypes. The
+proposed support-weighted aggregation is:
 
 ```
 Cbar_j(beta) = ( sum_{i in S_j} N_ij^beta C_ij ) / ( sum_{i in S_j} N_ij^beta )
 ```
 
 with `S_j = { i | N_ij > 0 and C_ij exists }` and candidate
-`beta in {0.0, 0.25, 0.5, 0.75, 1.0}`. Architecture, model aggregation, loss terms, and
-inference follow the PROTEAN baseline (Chennoufi et al., 2025).
+`beta in {0.0, 0.25, 0.5, 0.75, 1.0}`.
+
+**Current checkpoint: baseline only.** The proposed beta-weighted aggregation and the
+`equal_available` control are **not implemented** in this checkpoint; they are deferred to
+the later beta/controls phase, which must not begin until the baseline is verified. See
+`docs/handoff/SESSION_HANDOFF.md`.
 
 ## Immutable source
 
@@ -30,19 +35,21 @@ never hardcoded in source. Generated artifacts go under `artifacts/`.
 
 ```
 docs/research/     spec interpretation, dataset inspection, implementation plan, protocol
-docs/baseline/     PROTEAN baseline investigation
+docs/baseline/     PROTEAN baseline investigation + baseline implementation notes
 docs/handoff/      session handoff (start here for a new session)
 configs/           datasets, experiments, model
-src/protean_research/  aggregation (implemented), data/federated/models/evaluation (planned)
-tests/             unit tests
+src/protean_research/  data, models, aggregation, federated, evaluation, utils (baseline)
+scripts/           run_baseline.py, generate_partitions.py
+tests/             focused unit + integration tests
 artifacts/ results/ generated outputs (not source)
 ```
 
 ## Status
 
-This is a planning/bootstrap state. No full training has been run and no experimental sweep
-has been launched. The original PROTEAN baseline has **no public official code**, so it must
-be reproduced from the paper.
+The minimum reproducible **baseline** is implemented and smoke-tested. No full-scale
+training and no beta sweep have been run. The original PROTEAN baseline has **no public
+official code**, so it is reproduced from the paper/thesis with explicitly documented
+reproduction assumptions (`docs/baseline/BASELINE_IMPLEMENTATION.md`).
 
 Read `docs/handoff/SESSION_HANDOFF.md` first, then
 `planningawal/PROTEAN_Revisi_Lurus.md`.
@@ -50,13 +57,20 @@ Read `docs/handoff/SESSION_HANDOFF.md` first, then
 ## Quickstart
 
 ```bash
-# inside the repo, with a virtualenv that has pyyaml + pytest
-python -m pytest -q
+# inside the repo, with the project virtualenv (numpy, pandas, torch, pyyaml, pytest)
+.venv/bin/python -m pytest -q
+
+# baseline smoke test (writes only to ignored directories)
+.venv/bin/python scripts/run_baseline.py --dataset xiiotid --alpha 0.5 --seed 0 \
+    --max-rows 3000 --sample-from 60000 --clients 4 --rounds 2 --local-epochs 1
+
+# generate + verify all deterministic partition manifests (full data)
+.venv/bin/python scripts/generate_partitions.py
 ```
 
-The aggregation module is dependency-free and testable without pandas/torch:
+The baseline aggregation is dependency-free and testable without pandas/torch:
 
 ```python
 from protean_research.aggregation import aggregate_prototypes
-aggregate_prototypes([[0.0, 2.0], [2.0, 0.0]], "support_weighted", beta=0.5, supports=[1, 3])
+aggregate_prototypes([[0.0, 2.0], [2.0, 0.0]])  # equal mean over the contributor set S_j
 ```