# 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 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}`.

**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

- `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 + baseline implementation notes
docs/handoff/      session handoff (start here for a new session)
configs/           datasets, experiments, model
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

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`.

## Quickstart

```bash
# 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 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]])  # equal mean over the contributor set S_j
```