WildlifeFL

Privacy-preserving federated learning for wildlife poaching detection

        ┌────────────────────┐
        │   Server (Flower)  │
        │  global aggregation│
        └─────────┬──────────┘
                  │ round config
        ┌─────────┴──────────┐
        ▼                    ▼
  ┌──────────┐         ┌──────────┐
  │ Client 1 │   ...   │ Client N │
  │ (YOLOv8) │         │  (CRNN)  │
  │ + DP     │         │ + DP     │
  └──────────┘         └──────────┘
       │                    │
       └────────┬───────────┘
                ▼
         W&B tracking
       (server-side eval)

Overview

A multi-modal federated learning pipeline for wildlife poaching detection. Combines YOLOv8 visual object detection (72 wildlife/poaching classes) and a CRNN audio event classifier (5 classes — gun shot, engine idling, car horn, siren, dog bark), trained across simulated non-IID clients with client-side differential privacy (fixed clipping + Gaussian noise).

Designed for conservation scenarios where raw camera-trap images and audio recordings cannot leave the field station due to data sovereignty or connectivity constraints.

Modalities

Visual — YOLOv8 (72 classes)

• Backbone: YOLOv8n with custom 72-class head
• Dataset: WPPMuFL/wildlife-poaching-prevention
• Output: bounding boxes + class + confidence

Audio — CRNN on UrbanSound8K (5 classes)

• Architecture: CNN + GRU + FC
• Dataset: UrbanSound8K (filtered to 5 poaching-relevant classes)
• Output: per-clip class probabilities

Federated Setup

• Framework: Flower v1.20 (ServerApp / ClientApp API)
• Partitioning: Dirichlet (non-IID, configurable α)
• Privacy: Client-side DP (fixed clipping 1.0 + Gaussian noise σ=0.1)
• Tracking: Weights & Biases (optional — server-side metrics only)
• Aggregation: FedAvg with differential privacy

Results

Metric	Value
YOLO mAP@0.5	0.71
Audio balanced accuracy	91.6%
Audio macro F1	0.89

Research

A research paper describing this system has been submitted to the BEEI journal (under review). The codebase is structured for reproducibility — all training configs, hyperparameters, and partition seeds are version-controlled.

Quick Start

Prerequisites

• Python 3.11+
• HuggingFace account + token (for YOLO dataset access)
• W&B account (optional, for experiment tracking)
• UrbanSound8K dataset (manual download from UrbanSound8K)

Setup

git clone https://github.com/MeGaurav4/WildlifeFL.git
cd WildlifeFL
pip install -e .

cp .env.example .env
# Edit .env:
#   WANDB_API_KEY=your_key (optional)
#   HF_HUB_TOKEN=your_hf_token
#   AUDIO_LOCAL_DIR=/path/to/UrbanSound8K

Run YOLO modality (simulation, 5 clients)

flwr run . yolo --federation-config num-supernodes=5

Run Audio modality (simulation, 5 clients)

flwr run . audio --federation-config num-supernodes=5

Results are logged to W&B (if configured) and checkpoints saved to artifacts/.

Project Structure

app_server/      # Flower ServerApp, strategy, aggregation
app_client/      # Generic client entrypoint
app_yolo/        # YOLOv8 client, data partitioning, training utils
app_audio/       # CRNN client, audio data loaders, models
app_common/      # Shared constants (breaks circular imports)
utils/           # Seeding, W&B logger helpers
scripts/         # One-off utilities (model conversion, W&B dashboards)
yolov8n_72.yaml  # Custom YOLO config (72 classes)
pyproject.toml   # Flower run config + dependencies

Tech Stack

Testing

pip install -r requirements.txt
pytest tests/

License

MIT — see LICENSE.