chore: checkpoint PROTEAN research planning and architecture

README.md

@@ -0,0 +1,62 @@
+# perdalam-protean
+
+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:
+
+```
+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).
+
+## Immutable source
+
+- `planningawal/PROTEAN_Revisi_Lurus.md` is the authoritative research specification and is
+  **read-only**. Do not edit, add, rename, move, or delete anything under `planningawal/`.
+
+## External raw datasets (read-only, never copied into the repo)
+
+- `~/datasets/X-IIoTID/X-IIoTID-dataset.csv`
+- `~/datasets/5G-NIDD/5G-NIDD.csv`
+
+Paths are configured in `configs/datasets/datasets.yaml` (with environment overrides) and are
+never hardcoded in source. Generated artifacts go under `artifacts/`.
+
+## Layout
+
+```
+docs/research/     spec interpretation, dataset inspection, implementation plan, protocol
+docs/baseline/     PROTEAN baseline investigation
+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
+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.
+
+Read `docs/handoff/SESSION_HANDOFF.md` first, then
+`planningawal/PROTEAN_Revisi_Lurus.md`.
+
+## Quickstart
+
+```bash
+# inside the repo, with a virtualenv that has pyyaml + pytest
+python -m pytest -q
+```
+
+The aggregation module 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])
+```