---
language:
  - en
tags:
  - regtech
  - banking
  - risk-scoring
  - eu-compliance
  - basel-iii
  - fastapi
  - prometheus
license: apache-2.0
pipeline_tag: tabular-regression
---

# GENESIS Risk Engine — v10.1 (Enterprise)

[![CI](https://github.com/Alvoradozerouno/GENESIS-v10.1/actions/workflows/ci.yml/badge.svg)](https://github.com/Alvoradozerouno/GENESIS-v10.1/actions/workflows/ci.yml)
[![Tests](https://img.shields.io/badge/tests-87%20passing-brightgreen)]()
[![Python](https://img.shields.io/badge/python-3.12%20|%203.13-blue)]()
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)]()

Part of the **GENESIS v10.1 Sovereign AI OS** — the world's first open-source EU Banking Compliance platform.

## Model Description

Pure NumPy gradient-like risk scoring engine calibrated against Basel III benchmarks.  
**R² = 0.8955** on 15 Basel III operational anchors.

### 9 EU Framework Profiles
Each profile uses framework-specific feature weights derived from EBA supervisory convergence data:

| Framework | Primary Risk Drivers |
|-----------|---------------------|
| Basel III/IV | CPU stress + Memory (LCR) + Error Rate (op-loss) |
| DORA | Network latency + ICT error rate + CPU recovery |
| GDPR | Disk saturation (data at rest) + Error rate (breach risk) |
| EU AI Act | CPU (inference load) + Memory (model) + Errors (model failures) |
| MiFID II | Network I/O (trade latency) + CPU + Error rate (failed txn) |
| AML6 | CPU (ML screening) + Network (data feeds) + Error rate |
| PSD2 | Network (SCA/API) + Error rate (failed payments) |
| Solvency II | Memory (actuarial models) + Disk (policy data) |
| EBA Guidelines | CPU + Memory + Disk (loan data) + Error rate |

## Production API (v10.1 Enterprise Features)

| Feature | Status |
|---------|:------:|
| API Key auth (`X-API-Key` / `Bearer`) | ✅ |
| Rate limiting: 30 writes/60s/IP (sliding window) | ✅ |
| Input bounds: all numeric fields `ge/le` validated | ✅ |
| SQLite audit persistence | ✅ |
| Multi-tenant API keys (SHA-256 CRUD admin routes) | ✅ |
| Prometheus `/metrics` (7 metrics) | ✅ |
| Grafana dashboard (8 panels, import-ready) | ✅ |
| Structured JSON logging | ✅ |
| 94 pytest tests (CI Python 3.12 + 3.13) | ✅ |
| Docker + nginx HTTPS | ✅ |

## Usage

### Start the API

```bash
git clone https://github.com/Alvoradozerouno/GENESIS-v10.1.git
cd GENESIS-v10.1
pip install -r requirements.txt
uvicorn genesis_api:app --port 8080
# Default dev key: genesis-dev-key
# Production: export GENESIS_API_KEY=<your-secure-key>
```

### Score Risk (authenticated)

```bash
curl -X POST http://localhost:8080/api/risk/score \
  -H "X-API-Key: genesis-dev-key" \
  -H "Content-Type: application/json" \
  -d '{
    "cpu": 85,
    "memory": 70,
    "disk_usage": 60,
    "network_io": 50,
    "error_rate": 15,
    "framework": "dora"
  }'
```

### Prometheus scrape (public)

```bash
curl http://localhost:8080/metrics
# genesis_model_r2 0.8955
# genesis_audit_entries_total 42
# genesis_up 1
```

## Input Schema

| Field | Type | Range | Description |
|-------|------|-------|-------------|
| `cpu` | float | 0–100 | CPU utilisation % |
| `memory` | float | 0–100 | Memory utilisation % |
| `disk_usage` | float | 0–100 | Disk utilisation % |
| `network_io` | float | 0–100000 | Network I/O Mbps |
| `error_rate` | float | 0–100 | Application error rate % |
| `framework` | string | — | One of 9 EU frameworks |

## Output

```json
{
  "risk_score": 62.3,
  "risk_level": "HIGH",
  "framework": "dora",
  "model_confidence_r2": 0.8955,
  "feature_importance": {"cpu": 0.2, "memory": 0.12, "network_io": 0.25, "disk_usage": 0.08, "error_rate": 0.35},
  "regulatory_action": "Board notification + corrective action within 24h",
  "audit_ref": "2026-01-14T10:00:00+00:00"
}
```

## Links

- 🏛️ **GitHub**: https://github.com/Alvoradozerouno/GENESIS-v10.1
- 📋 **Compliance / Fraud Engine**: https://huggingface.co/Alvoradozerouno/genesis-quantum-fraud
- 📖 **API Docs**: http://localhost:8080/docs (after starting server)