---

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

pip install vigilcv

Or install with development dependencies:

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:

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:

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:

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:

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:

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:

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

vigilcv drift

Audit target dataset and quantify covariate drift against fitted baseline:

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:

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

Run static type analysis and linting:

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

Run CPU latency benchmarks:

python benchmarks/bench_pipeline.py

---

📄 License

VigilCV is released under the Apache-2.0 License. See LICENSE for details.