fdavrs 0.1.2

Federated Drift-Aware Vision Reliability System SDK

FDAVRS Federated Drift-Aware Vision Reliability System

FDAVRS is a PyTorch-compatible SDK that acts as a self-healing wrapper for Computer Vision models.

When edge devices (such as drones or autonomous vehicles) encounter environmental drift (fog, snow, blur, lighting shifts), traditional models fail silently.

FDAVRS:

Detects drift in real time

Applies Unsupervised Test-Time Adaptation (TTA)

Heals the model mathematically

Securely packages adaptation weights for Federated Learning

Preserves the original model architecture

nstallation

Install the latest version from PyPI:

pip install fdavrs

Quick Start Guide:

Using FDAVRS is seamless. If you know how to use PyTorch, you already know how to use FDAVRS.

1️⃣ Import the SDK import torch import torchvision from fdavrs import FDAVRS 2️⃣ Wrap Your Model

Load your base vision model (e.g., ResNet or YOLO) and wrap it.

1. Load your standard pre-trained model

base_model = torchvision.models.resnet18(pretrained=True)

2. Wrap it with FDAVRS

robust_model = FDAVRS( client_model=base_model, feature_layer='avgpool', # Layer to monitor for drift threshold=0.3 # Drift score boundary ) 3️⃣ Calibrate the Baseline

Before deployment, the SDK analyzes clean images to establish a baseline embedding.

Pass a standard PyTorch DataLoader containing clean images

robust_model.fit(clean_data_loader) 4️⃣ Live Inference & Self-Healing

During live inference, FDAVRS operates automatically.

for images, labels in live_camera_feed:

# The SDK:
# - Calculates drift
# - Applies local adaptation if needed
# - Returns corrected predictions

predictions = robust_model.predict(images)

# Inspect SDK behavior
current_status = robust_model.status()
print(f"Action Taken: {current_status['action']}")

📖 API Reference Class: FDAVRS

The main wrapper class that orchestrates the Monitor, Brain, and Adapter layers.

🔧 Parameters client_model (torch.nn.Module)

The PyTorch vision model to make robust. The SDK freezes the feature extractor to prevent catastrophic forgetting.

feature_layer (str)

Name of the internal layer to attach a forward hook.

Examples:

'avgpool' → ResNet

'model.model.9' → YOLO

threshold (float, default = 0.3)

Drift score boundary:

Score < threshold → IDLE (Highly Reliable)

threshold < Score < 0.8 → LOCAL_ADAPTATION

Score > 0.8 → REQUEST_SERVER_CURE

core Methods fit(dataloader) Description

Calibrates the Monitor layer by computing a baseline reference embedding.

Parameters

dataloader (torch.utils.data.DataLoader) Clean, in-distribution images.

Returns

None

predict(images) / forward(images) Description

Main inference execution.

The SDK calculates a Composite Drift Score using:

Entropy

Cosine Shift

Confidence

If drift is detected:

BatchNorm layers switch to .train() mode

Running statistics (μ and σ²) are recalculated

5 adaptation iterations are performed

Corrected logits are returned

Parameters

images (torch.Tensor) Shape: (B, C, H, W)

Returns

logits (torch.Tensor)

status() Description

Returns the most recent decision taken by the Policy Engine.

Returns { "action": "IDLE | LOCAL_ADAPTATION | PASSIVE_DISCOVERY | REQUEST_SERVER_CURE", "metrics": { "score": float, "entropy": float, "shift": float, "confidence": float } } Architecture Overview

When predict() is called, FDAVRS executes a Teacher–Student Federated Learning protocol:

1️⃣ Monitor Layer

PyTorch forward hooks intercept internal activations

Calculates distribution shift

2️⃣ Decision Layer

Triage logic determines:

Whether the model is reliable enough to teach others

Or if it is blind and needs external correction

3️⃣ Local Adaptation Layer

If drift is recoverable:

Test-Time Adaptation (TTA) is triggered

BatchNorm statistics (μ, σ²) are recalculated

No permanent architecture changes occur

4️⃣ Knowledge Vault

Successful fixes are:

Stripped down to normalization weights (.pt)

Paired with a drift signature (.json)

Uploaded to Federated Server

Aggregated using FedAvg