# 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])
```