Metadata-Version: 2.4
Name: fdavrs
Version: 0.2.0
Summary: A self-healing SDK that detects and fixes data drift in deployed computer vision models using federated learning
Author: Srivandhi S
License: MIT
Project-URL: Homepage, https://pypi.org/project/fdavrs
Keywords: drift-detection,federated-learning,computer-vision,pytorch,test-time-adaptation,resnet,yolo
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch>=1.9.0
Requires-Dist: numpy>=1.19.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: requests>=2.25.0

# FDAVRS — Federated Drift-Aware Vision Reliability System

**FDAVRS** is a PyTorch SDK that makes computer vision models self-healing.
When deployed models encounter real-world distribution shift — fog, lighting 
changes, sensor noise, blur — they fail silently. FDAVRS detects this 
automatically and fixes the model at runtime, without labels and without 
retraining.

## Install

pip install fdavrs

## The Problem It Solves

A ResNet trained on clean images loses 30–40% accuracy when deployed in fog.
No error is raised. The model just starts predicting wrong — silently.
FDAVRS wraps the model and fixes this automatically.

## Quick Start

```python
import torch
import torchvision
from fdavrs import FDAVRS

# 1. Load your existing model — nothing changes here
base_model = torchvision.models.resnet18(pretrained=True)

# 2. Wrap it with FDAVRS — one line
model = FDAVRS(
    client_model=base_model,
    feature_layer='avgpool',
    threshold=0.3
)

# 3. Calibrate once on clean data before deployment
model.fit(clean_data_loader)

# 4. Use exactly like a normal model during inference
for images in live_feed:
    predictions = model.predict(images)

    status = model.status()
    print(status['action'])
    # IDLE                  → model is healthy
    # LOCAL_ADAPTATION      → drift detected, fixing locally
    # GLOBAL_CURE_APPLIED   → fix retrieved from federated server
```

## How It Works

When `predict()` is called, FDAVRS runs a 4-layer pipeline automatically:

**1. Monitor Layer** — A forward hook intercepts internal activations from 
the specified feature layer. It computes a Composite Drift Score:
Score = (0.5 × Entropy) + (0.3 × Cosine Shift) + (0.2 × (1 - Confidence))

**2. Decision Layer** — Triage based on score:
- Score ≤ 0.3 → `IDLE` (model is reliable)
- 0.3 < Score ≤ 0.8 → `LOCAL_ADAPTATION` (fix locally via TTA)
- Score > 0.8 → `REQUEST_SERVER_CURE` (ask federated server)

**3. Adaptation Layer** — BatchNorm running statistics (μ and σ²) are 
recalculated on the current batch using Test-Time Adaptation. No labels 
required. No architecture changes. No retraining.

**4. Knowledge Vault** — Successful fixes are packaged as weight deltas 
and drift signatures, then uploaded to a federated server so other 
devices with the same drift pattern benefit instantly.

## API Reference

### `FDAVRS(client_model, feature_layer, threshold=0.3)`

Wraps your model with drift monitoring and self-healing.

| Parameter | Type | Description |
|---|---|---|
| `client_model` | `torch.nn.Module` | Your pretrained PyTorch model |
| `feature_layer` | `str` | Layer name to monitor e.g. `'avgpool'` for ResNet |
| `threshold` | `float` | Drift sensitivity. Default `0.3` |

### `fit(dataloader)` / `fit_baseline(dataloader)`

Calibrates the baseline using clean data. Call once before deployment.

### `predict(images)` / `forward(images)`

Drop-in replacement for `model(images)`. Drift detection and adaptation 
happen automatically inside.

### `status()`

Returns current SDK state:

```python
{
    "action": "IDLE | LOCAL_ADAPTATION | GLOBAL_CURE_APPLIED | ...",
    "metrics": {
        "score": 0.42,
        "entropy": 0.81,
        "shift": 0.23,
        "confidence": 0.61
    }
}
```

## Compatible Models

Tested with ResNet-18, YOLOv11, DeepLabV3, and custom CNNs.
Any PyTorch model with BatchNorm layers is supported.

## Requirements

- Python ≥ 3.8
- PyTorch ≥ 1.9.0
- NumPy ≥ 1.19.0
- SciPy ≥ 1.7.0
