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

# 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:

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

3.0 KiB Raw Blame History