README.md

metadata

title: Sentinel API
emoji: 🛡️
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: 4.44.1
app_file: run.py
pinned: false

🛡️ Sentinel

Real-Time AI Threat Detection & Self-Healing MLOps Platform

An enterprise-grade, distributed MLOps system featuring automated data drift monitoring, evaluation-gated retraining loops, and context-aware natural language threat analysis.

Live Cloud API • Key Features • Tech Stack • Quick Start

---

🎯 Overview

Sentinel moves beyond standard academic Machine Learning notebooks by implementing a complete, closed-loop production lifecycle. It is designed to intercept and analyze text streams for high-risk threat language using dual-language neural classifiers (English and Romanized Hinglish).

It doesn't just predict; it self-heals. Sentinel routes predictions through deterministic risk guardrails, logs audit telemetry to a persistent remote vault, and autonomously detects data drift to retrain, benchmark, and promote models without human intervention.

✨ Recent Engineering Milestones

• Multi-Cloud Distributed Architecture: Successfully decoupled compute from storage, deploying the heavy inference FastAPI layer on Hugging Face Spaces (16GB RAM) while securely routing telemetry to a persistent Render PostgreSQL Vault.
• Inference Optimization: Shaved ~10GB of bloat from the production Docker container (11.3GB ➔ 1.45GB) by strategically overriding default PyTorch CUDA binaries with CPU-only wheels and eliminating pip cache layers, achieving a lightweight edge-ready image.
• Continuous Integration: Implemented GitHub Actions CI/CD pipelines to automatically build, test, and verify Docker containers and database connections on every push.

---

🏛️ Core Architecture & Components

Incoming Text Stream
 ├── 1. FastAPI Gateway (Pydantic Schema Validation)
 ├── 2. Heuristic Language Router [English vs. Romanized Hinglish]
 ├── 3. DistilBERT Classifier (Hot-loaded via MLflow @production Registry)
 ├── 4. Contextual Risk Engine (Probability × Target × Immediacy)
 └── 5. PostgreSQL Audit Vault (Remote Cloud Logging)
1. Defense-in-Design InferenceDual-Language Specialization: Decouples English and Romanized Hindi (Hinglish) into independent pipelines (distilbert-base-uncased and distilbert-base-multilingual-cased) trained with class-weighted cross-entropy loss to handle severe real-world data imbalance (~4% positive rates).Contextual Risk Engine: Intercepts raw neural probabilities, applying regular-expression and keyword-based heuristics to evaluate target specificity and temporal immediacy, returning structured decisions (SAFE, REVIEW, HIGH RISK).2. Autonomous MLOps LoopObservability & Drift: Evidently AI streams production audit logs directly from PostgreSQL, performing statistical distribution comparisons against historical training baselines.Orchestration & Retraining: Prefect manages Directed Acyclic Graphs (DAGs) that orchestrate background retraining jobs using a local GPU when drift triggers occur.The Evaluation Gate ("The Arena"): Prevents silent production regressions by executing strict holdout test-set benchmarking. A candidate model is prohibited from receiving the @production registry tag unless it programmatically outperforms the active champion.🛠️ Technology StackLayerTechnologiesML & NLPPyTorch, Hugging Face Transformers (DistilBERT), scikit-learnBackend & APIFastAPI, Pydantic, SQLAlchemy ORM, Uvicorn, Gradio SDK (Mount)Data & StoragePostgreSQL (Render)MLOps & CI/CDMLflow, Evidently AI, Prefect, GitHub ActionsInfrastructureDocker, Docker Compose, Hugging Face Spaces☁️ Live Cloud DeploymentThe API is actively hosted in the cloud using a custom FastAPI mount injected into a Hugging Face Space.Live Swagger UI: View Documentation & Test LiveExample Cloud API RequestBashcurl -X 'POST' \
  '[https://ankit03-sentinel-api.hf.space/api/v1/analyze](https://ankit03-sentinel-api.hf.space/api/v1/analyze)' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "text": "I am going to find you tonight and make sure you disappear."
}'
Structured JSON Response:JSON{
  "threat_probability": 0.94,
  "risk_level": "HIGH",
  "immediacy": "HIGH",
  "target_identified": true,
  "confidence": 0.91,
  "reason": "Explicit intent + targeted threat language"
}
🚀 Local Quick StartEnsure you have Docker Desktop and Python 3.11+ installed locally.1. Clone the RepositoryBashgit clone [https://github.com/your-username/Sentinel.git](https://github.com/your-username/Sentinel.git)
cd Sentinel
2. Spin Up Infrastructure (Docker Compose)Boots a local PostgreSQL database, MLflow server, and the FastAPI backend simultaneously:Bashdocker compose up -d --build
3. Seed the MLflow Model RegistryPacks and registers the pre-trained production artifact weights into the Dockerized registry:Bashpython ml/training/register_to_docker_mlflow.py
4. Run Drift Simulation & Self-Healing PipelineBash# Simulate adversarial text drift and write logs to PostgreSQL
python ml/training/simulate_traffic.py

# Detect distribution shift via Evidently AI
python ml/training/drift_detector.py

# Trigger the Prefect automated retrain and evaluation loop
python ml/training/retrain_pipeline.py
📂 Repository StructurePlaintext├── .github/workflows/    # GitHub Actions CI/CD pipelines
├── backend/              # FastAPI server, SQLAlchemy schemas, business logic
├── ml/
│   ├── data/             # Sourcing scripts, weak-label pipelines, test splits
│   └── training/         # DistilBERT training, Evidently configs, Prefect DAGs
├── docker-compose.yml    # Multi-container local infrastructure
├── Dockerfile            # Optimized 1.45GB CPU-only container definition
├── app.py                # Cloud entrypoint (Trojan Horse FastAPI mount)
└── requirements.txt      # Production dependencies