Metadata-Version: 2.5
Name: vigilcv
Version: 0.1.0
Summary: Ultra-fast, CPU-first data quality auditor, corruption gatekeeper, and statistical distribution drift sentinel for production Computer Vision pipelines.
Project-URL: Homepage, https://github.com/vigilcv/vigilcv
Project-URL: Documentation, https://github.com/vigilcv/vigilcv#readme
Project-URL: Repository, https://github.com/vigilcv/vigilcv
Project-URL: Issues, https://github.com/vigilcv/vigilcv/issues
Author-email: VigilCV Maintainers <maintainers@vigilcv.org>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: computer-vision,data-quality,dataset-audit,distribution-drift,image-processing,machine-learning,mlops,quality-assurance,sentinel
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1.0
Requires-Dist: numpy>=1.23.0
Requires-Dist: pillow>=9.5.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# 🛡️ VigilCV

**Ultra-Fast, CPU-First Data Quality Auditor & Statistical Distribution Drift Sentinel for Production Computer Vision Pipelines.**

[![PyPI Version](https://img.shields.io/pypi/v/vigilcv?color=0ea5e9&style=flat-square)](https://pypi.org/project/vigilcv/)
[![Python Versions](https://img.shields.io/pypi/pyversions/vigilcv?style=flat-square)](https://pypi.org/project/vigilcv/)
[![CI Pipeline](https://img.shields.io/github/actions/workflow/status/vigilcv/vigilcv/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/vigilcv/vigilcv/actions)
[![Coverage](https://img.shields.io/badge/coverage-95%25-10b981?style=flat-square)](https://github.com/vigilcv/vigilcv)
[![Type Checked with mypy](https://img.shields.io/badge/mypy-strict-blueviolet?style=flat-square)](https://mypy.readthedocs.io/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](LICENSE)

</div>

---

## 📌 Overview

**`vigilcv`** is a high-performance, deterministic Python package engineered to sit directly in front of Computer Vision models (PyTorch, TensorRT, ONNX, TorchServe, Triton, FastAPI) and real-time video streams (OpenCV, GStreamer, RTSP).

It intercepts image datasets, batch directories, video frames, and inference payloads to detect **optical degradation**, **severe blur**, **signal clipping (underexposure / overexposure)**, **compression noise**, and **covariate distribution drift** *before* expensive downstream neural networks or multimodal models are triggered.

### Why VigilCV?

- ⚡ **Pure CPU Speed:** Sub-millisecond execution per frame ($< 250\,\mu\text{s}$ on standard x86/ARM CPUs) via vectorized NumPy / SciPy C-extensions. Zero GPU overhead.
- 🛡️ **Zero Silent Failures:** Corrupted headers, truncated bytes, $1\times 1$ edge inputs, RGBA alpha channels, single-channel infrared, or non-standard color spaces are defensively sanitized.
- 📊 **Multivariate Drift Detection:** Quantifies dataset-scale distribution shifts using **Wasserstein-1 (Earth Mover's Distance)**, **Maximum Mean Discrepancy (MMD with Gaussian RBF Kernel)**, and **Population Stability Index (PSI)** across 54-dimensional multiscale spatial color-moment features.
- 📈 **Standalone HTML Dashboard:** Self-contained, offline-ready HTML report with dark-mode glassmorphic styling, interactive charts, and flagged anomaly tables.
- 📦 **Zero-Config CLI:** Rich command-line interface with interactive progress bars, colored telemetry tables, and automation exit codes for CI/CD dataset gating.

---

## 🚀 Microsecond CPU Latency Benchmarks

Benchmarks executed on standard x86-64 CPU without GPU acceleration (pure NumPy vectorization):

| Benchmark Target | Input Resolution | Mean Latency | p50 Latency | p99 Latency |
| :--- | :--- | :--- | :--- | :--- |
| **Laplacian Focus Variance** | $224 \times 224$ (ResNet) | **$223.6\,\mu\text{s}$** | $211.2\,\mu\text{s}$ | $365.6\,\mu\text{s}$ |
| **Shannon Entropy** | $224 \times 224$ (ResNet) | **$104.1\,\mu\text{s}$** | $97.2\,\mu\text{s}$ | $202.4\,\mu\text{s}$ |
| **Exposure Clipping Metrics** | $224 \times 224$ (ResNet) | **$246.8\,\mu\text{s}$** | $229.0\,\mu\text{s}$ | $477.6\,\mu\text{s}$ |
| **Spatial Color Moments (54D)** | $224 \times 224$ (ResNet) | **$1.33\,\text{ms}$** | $1.23\,\text{ms}$ | $2.31\,\text{ms}$ |
| **`VisionSentinel.guard()`** | $224 \times 224$ (ResNet) | **$1.79\,\text{ms}$** | $1.65\,\text{ms}$ | $3.28\,\text{ms}$ |
| **Wasserstein EMD (54D)** | $200\text{ samples} \times 54\text{D}$ | **$4.68\,\text{ms}$** | $4.40\,\text{ms}$ | $9.44\,\text{ms}$ |
| **MMD (RBF Kernel)** | $200\text{ samples} \times 54\text{D}$ | **$11.80\,\text{ms}$** | $10.75\,\text{ms}$ | $25.27\,\text{ms}$ |

---

## 📦 Installation

Install the production package directly via `pip`:

```bash
pip install vigilcv
```

Or install with development dependencies:

```bash
pip install "vigilcv[dev]"
```

---

## 💡 Quickstart & Code Examples

### 1. Pre-Flight Inference Guard (Single Image)

Protect your model inference endpoints from corrupted or out-of-focus inputs:

```python
from vigilcv import VisionSentinel, QualityThresholdExceeded, CorruptImageError

sentinel = VisionSentinel(
    blur_threshold=100.0,  # Flag if Laplacian variance < 100
    min_entropy=3.0,  # Flag if Shannon entropy < 3.0 bits
    max_underexposure_ratio=0.20,  # Max 20% dark clipped pixels
    max_overexposure_ratio=0.20,  # Max 20% saturated white pixels
    raise_on_fail=False,
)

# Returns boolean decision in < 2ms
if sentinel.guard("input_frame.jpg"):
    prediction = model.predict("input_frame.jpg")
else:
    print("Rejected degraded input frame!")
```

### 2. Video Stream & Camera Ingestion Loop

Filter camera video frames in real time with generator streaming:

```python
import cv2
from vigilcv import VisionSentinel

sentinel = VisionSentinel(blur_threshold=80.0)
cap = cv2.VideoCapture(0)


def frame_generator():
    while cap.isOpened():
        ret, frame = cap.read()
        if not ret:
            break
        yield frame


# Stream generator yielding (frame, QualityMetrics)
for frame, metrics in sentinel.audit_stream(frame_generator()):
    if metrics.is_valid:
        cv2.imshow("Audited Stream", frame)
    else:
        print(f"Frame dropped! Blur score: {metrics.blur_score:.1f}")
```

### 3. Multi-Threaded Batch Dataset Audit & Drift Sentinel

Audit an entire directory of images in parallel and quantify covariate shift:

```python
from vigilcv import BatchAuditor

auditor = BatchAuditor(num_workers=8)

# 1. Fit reference baseline on training dataset
ref_features = auditor.fit_reference("/data/golden_training_set")
auditor.save_reference("baseline_distribution.npz")

# 2. Audit incoming production batch against baseline
summary = auditor.audit_batch(
    target="/data/production_inflow_batch",
    drift_threshold=0.05,
    compute_drift=True,
)

print(f"Total Images: {summary.total_images}")
print(
    f"Valid: {summary.valid_images} | Corrupted: {summary.corrupted_count} | Blurred: {summary.blurred_count}"
)
print(f"Throughput: {summary.throughput_fps:.1f} FPS")

if summary.drift_report and summary.drift_report.is_drifted:
    print(f"⚠️ DRIFT ALERT! MMD: {summary.drift_report.mmd_score:.4f} > 0.05")
```

---

## 🛠️ Command-Line Interface (CLI)

VigilCV ships with an enterprise-ready CLI powered by `typer` and `rich`.

### `vigilcv inspect`

Inspect a single image and print colorized diagnostic telemetry:

```bash
vigilcv inspect path/to/image.jpg --blur-threshold 100.0 --min-entropy 3.0
```

### `vigilcv audit`

Audit an entire dataset in parallel and generate an HTML report or JSON summary:

```bash
vigilcv audit /data/coco_val \
  --blur-threshold 100.0 \
  --report audit_report.html \
  --json audit_summary.json \
  --fail-on-flagged
```

### `vigilcv baseline`

Extract 54D spatial color-moment features on a reference dataset and save baseline:

```bash
vigilcv baseline /data/training_set baseline_reference.npz --workers 8
```

### `vigilcv drift`

Audit target dataset and quantify covariate drift against fitted baseline:

```bash
vigilcv drift /data/production_batch \
  --baseline baseline_reference.npz \
  --threshold 0.05 \
  --report drift_report.html \
  --fail-on-drift
```

---

## 🏗️ Architecture & Mathematical Foundation

```
                           +---------------------------+
                           |    Raw Image Payload      |
                           |  (Path / NumPy / PIL / B) |
                           +-------------+-------------+
                                         |
                                         v
                         +---------------+---------------+
                         |   Defensive Sanitization      |
                         |  (Grayscale/RGB Composite)    |
                         +---------------+---------------+
                                         |
                +------------------------+------------------------+
                |                                                 |
                v                                                 v
    +-----------------------+                         +-----------------------+
    | Optical Heuristics    |                         | Statistical Drift     |
    | - Laplacian Focus     |                         | - 54D Spatial Moments |
    | - Shannon Entropy     |                         | - 2D Spectral Energy  |
    | - Exposure Clipping   |                         | - Wasserstein-1 (EMD) |
    | - Dynamic Range       |                         | - Multivariate MMD    |
    +-----------+-----------+                         | - Population Stab PSI |
                |                                     +-----------+-----------+
                v                                                 v
    +-----------------------+                         +-----------------------+
    |    QualityMetrics     |                         |      DriftReport      |
    | (Slots / Frozen / DC) |                         | (Slots / Frozen / DC) |
    +-----------+-----------+                         +-----------+-----------+
                |                                                 |
                +------------------------+------------------------+
                                         |
                                         v
                         +---------------+---------------+
                         |   BatchAuditSummary & Report  |
                         |   - Standalone HTML Dashboard |
                         |   - Rich Console Telemetry    |
                         |   - JSON Export / Alert Gate  |
                         +-------------------------------+
```

### Mathematical Formulations

1. **Focus Blur Metric (Discrete 2D Laplacian Variance):**
   $$\nabla^2 I(x, y) = I(x+1, y) + I(x-1, y) + I(x, y+1) + I(x, y-1) - 4 I(x, y)$$
   $$\text{Focus Score} = \text{Var}\left(\nabla^2 I\right)$$

2. **Shannon Intensity Entropy ($H(I)$):**
   $$H(I) = -\sum_{k=0}^{255} p_k \log_2(p_k + \varepsilon)$$

3. **Multivariate Maximum Mean Discrepancy ($\text{MMD}^2$):**
   $$\text{MMD}^2(P, Q) = \frac{1}{m(m-1)} \sum_{i \neq j} k(x_i, x_j) + \frac{1}{n(n-1)} \sum_{i \neq j} k(y_i, y_j) - \frac{2}{mn} \sum_{i, j} k(x_i, y_j)$$
   where $k(x, y) = \exp\left(-\gamma \|x - y\|^2\right)$ with median-distance heuristic bandwidth selection.

4. **Population Stability Index ($\text{PSI}$):**
   $$\text{PSI} = \sum_{b=1}^{B} (q_b - p_b) \ln\left(\frac{q_b + \varepsilon}{p_b + \varepsilon}\right)$$

---

## 🧪 Testing & Verification

Run the full pytest suite with coverage validation:

```bash
pytest --cov=vigilcv --cov-report=term-missing --cov-fail-under=90
```

Run static type analysis and linting:

```bash
ruff check .
ruff format --check .
mypy src/ tests/
```

Run CPU latency benchmarks:

```bash
python benchmarks/bench_pipeline.py
```

---

## 📄 License

VigilCV is released under the **Apache-2.0 License**. See [LICENSE](LICENSE) for details.
