feat(api): implement Python FastAPI service for behavioral risk scoring with Docker support

Author: hanakassahun

python-service/Dockerfile

@@ -0,0 +1,12 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY requirements.txt ./
+RUN python -m pip install --no-cache-dir -r requirements.txt
+
+COPY . /app
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]

python-service/README.md

@@ -0,0 +1,54 @@
+# SentinelOS Python Risk Service Prototype
+
+This folder contains a minimal FastAPI prototype for a Python-based behavioral risk scoring service.
+
+## What it provides
+
+- `app.py`: FastAPI application exposing `/predict-risk` and `/health`
+- `schemas.py`: Pydantic models for behavioral events and risk requests
+- `ml_model.py`: Prototype ML model using `pandas` and `scikit-learn`
+- `requirements.txt`: Python dependency list
+- `Dockerfile`: Container image definition for the service
+
+## Run locally
+
+```powershell
+cd python-service
+python -m venv .venv
+.\.venv\Scripts\activate
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+uvicorn app:app --reload --host 0.0.0.0 --port 8000
+```
+
+## Example request
+
+```powershell
+curl -X POST "http://127.0.0.1:8000/predict-risk" -H "Content-Type: application/json" -d "{
+  \"user_id\": \"user-123\",
+  \"session_id\": \"session-abc\",
+  \"events\": [
+    {
+      \"event_type\": \"login_failure\",
+      \"timestamp\": \"2026-06-24T14:00:00Z\",
+      \"metadata\": { \"duration\": 30, \"high_risk_action\": true, \"confidence\": 0.8 }
+    },
+    {
+      \"event_type\": \"privilege_change\",
+      \"timestamp\": \"2026-06-24T14:05:00Z\",
+      \"metadata\": { \"duration\": 120, \"high_risk_action\": true, \"confidence\": 0.95 }
+    }
+  ]
+}"
+```
+
+## Notes
+
+This is a prototype to demonstrate how a Python FastAPI service can handle event payloads, validate them with Pydantic, and apply a simple ML-style risk model.
+
+For production, you can expand the service by:
+
+- loading a serialized model (`joblib` / `pickle` / `onnx`)
+- adding authentication and request validation middleware
+- using a real training dataset and feature engineering pipeline
+- versioning the API and ML model separately

python-service/app.py

@@ -0,0 +1,23 @@
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+
+from ml_model import RiskModel
+from schemas import RiskRequest, RiskResponse
+
+app = FastAPI(
+    title="SentinelOS Python Risk Service",
+    description="Prototype FastAPI service for behavioral risk scoring",
+    version="0.1.0",
+)
+
+model = RiskModel()
+
+@app.post("/predict-risk", response_model=RiskResponse)
+async def predict_risk(request: RiskRequest):
+    df = request.to_dataframe()
+    prediction = model.predict(df)
+    return RiskResponse(**prediction)
+
+@app.get("/health")
+async def health():
+    return JSONResponse({"status": "ok", "model_version": model.version})

python-service/ml_model.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+import numpy as np
+import pandas as pd
+from sklearn.linear_model import LogisticRegression
+from sklearn.pipeline import Pipeline
+from sklearn.preprocessing import StandardScaler
+
+FEATURE_COLUMNS = [
+    "event_count",
+    "unique_event_types",
+    "total_duration",
+    "avg_confidence",
+    "high_risk_actions",
+]
+
+
+class RiskModel:
+    version = "0.1.0"
+
+    def __init__(self) -> None:
+        self.pipeline = Pipeline(
+            [
+                ("scaler", StandardScaler()),
+                ("clf", LogisticRegression(random_state=42, max_iter=500)),
+            ]
+        )
+        X_train, y_train = self._generate_training_data()
+        self.pipeline.fit(X_train, y_train)
+
+    def predict(self, df: pd.DataFrame) -> Dict[str, Any]:
+        vector = self._extract_feature_vector(df)
+        score = float(self.pipeline.predict_proba([vector])[0, 1])
+        return {
+            "user_id": df.attrs.get("user_id", "unknown"),
+            "session_id": df.attrs.get("session_id"),
+            "risk_score": score,
+            "risk_level": self._to_risk_level(score),
+            "model_version": self.version,
+            "explanation": self._explain(vector, score),
+        }
+
+    def _generate_training_data(self) -> tuple[np.ndarray, np.ndarray]:
+        rng = np.random.default_rng(42)
+        rows: List[List[float]] = []
+        labels: List[int] = []
+
+        for _ in range(500):
+            event_count = float(rng.integers(1, 24))
+            unique_event_types = float(rng.integers(1, min(5, int(event_count))))
+            total_duration = float(rng.integers(0, 1200))
+            avg_confidence = float(rng.uniform(0.2, 0.98))
+            high_risk_actions = float(rng.integers(0, 5))
+
+            risk = 1 if (event_count > 10 and high_risk_actions >= 2) or total_duration > 600 else 0
+            rows.append([event_count, unique_event_types, total_duration, avg_confidence, high_risk_actions])
+            labels.append(risk)
+
+        return np.array(rows), np.array(labels)
+
+    def _extract_feature_vector(self, df: pd.DataFrame) -> List[float]:
+        event_count = float(len(df))
+        unique_event_types = float(df["event_type"].nunique()) if not df.empty else 0.0
+
+        total_duration = 0.0
+        confidences: List[float] = []
+        high_risk_actions = 0.0
+
+        for metadata in df["metadata"]:
+            if isinstance(metadata, dict):
+                total_duration += float(metadata.get("duration", 0.0) or 0.0)
+                confidence = metadata.get("confidence")
+                if isinstance(confidence, (int, float)):
+                    confidences.append(float(confidence))
+                if metadata.get("high_risk_action"):
+                    high_risk_actions += 1.0
+
+        avg_confidence = float(np.mean(confidences)) if confidences else 0.0
+        return [event_count, unique_event_types, total_duration, avg_confidence, high_risk_actions]
+
+    def _to_risk_level(self, score: float) -> str:
+        if score >= 0.65:
+            return "high"
+        if score >= 0.35:
+            return "medium"
+        return "low"
+
+    def _explain(self, vector: List[float], score: float) -> Dict[str, Any]:
+        return {
+            "features": dict(zip(FEATURE_COLUMNS, vector)),
+            "thresholds": {"low": 0.35, "high": 0.65},
+            "prediction_probability": score,
+        }

python-service/requirements.txt

@@ -0,0 +1,7 @@
+fastapi==0.109.0
+uvicorn[standard]==0.23.2
+pydantic==2.9.0
+pandas==2.2.2
+scikit-learn==1.4.0
+numpy==1.27.0
+python-dateutil==2.8.2

python-service/schemas.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+import pandas as pd
+from pydantic import BaseModel, Field
+
+
+class BehavioralEvent(BaseModel):
+    event_type: str = Field(..., description="Type of behavioral event")
+    timestamp: datetime
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+
+class RiskRequest(BaseModel):
+    user_id: str
+    session_id: Optional[str] = None
+    events: List[BehavioralEvent]
+    context: Dict[str, Any] = Field(default_factory=dict)
+
+    def to_dataframe(self) -> pd.DataFrame:
+        rows = []
+        for event in self.events:
+            rows.append(
+                {
+                    "event_type": event.event_type,
+                    "timestamp": event.timestamp.timestamp(),
+                    "metadata": event.metadata,
+                }
+            )
+
+        df = pd.DataFrame(rows)
+        df.attrs["user_id"] = self.user_id
+        df.attrs["session_id"] = self.session_id
+        return df
+
+
+class RiskResponse(BaseModel):
+    user_id: str
+    session_id: Optional[str]
+    risk_score: float
+    risk_level: str
+    model_version: str
+    explanation: Dict[str, Any]

server/api/controllers/insightsController.ts

@@ -4,6 +4,10 @@ import { analyzeEnergy } from '../../../intelligence/energyAnalyzer';
 import { generateEnergyInsights } from '../../../intelligence/insightGenerator';
 import { getLogs } from '../../services/insightsService';
 import { generateInsightsFromLogs } from '../../../internal/intelligence/insightGenerator';
+import {
+  buildInsightsFromAnalytics,
+  getBehaviorAnalytics,
+} from '../../services/analyticsService';
 
 // Simple in-memory cache for analysis/insights (per-process). Cached for 24h by default.
 let cached: { ts: number; insights: any[]; analysis: any } | null = null;
@@ -17,7 +21,6 @@ export async function getInsights(_req: Request, res: Response) {
     const force = _req.query && String(_req.query.force) === 'true';
     if (!force) {
       const persisted = await prisma.insight.findFirst({
-        where: { behaviorType: 'ENERGY' },
         orderBy: { generatedAt: 'desc' },
       });
       if (persisted) {
@@ -40,9 +43,8 @@ export async function getInsights(_req: Request, res: Response) {
       // persist empty result briefly to avoid repeated cheap requests
       await prisma.insight.create({
         data: {
-          behaviorType: 'ENERGY',
-          insights: [],
-          analysis: { totalLogs: logs ? logs.length : 0 },
+          insights: [] as any,
+          analysis: { totalLogs: logs ? logs.length : 0 } as any,
         },
       });
       cached = { ts: Date.now(), insights: [], analysis: { totalLogs: logs ? logs.length : 0 } };
@@ -56,9 +58,8 @@ export async function getInsights(_req: Request, res: Response) {
     // Persist generated insights (cache)
     await prisma.insight.create({
       data: {
-        behaviorType: 'ENERGY',
-        insights,
-        analysis,
+        insights: insights as any,
+        analysis: analysis as any,
       },
     });
 
@@ -83,7 +84,7 @@ export async function listPersistedInsights(_req: Request, res: Response) {
 
 export async function deleteInsight(req: Request, res: Response) {
   try {
-    const { id } = req.params;
+    const id = String(req.params.id);
     await prisma.insight.delete({ where: { id } });
     res.json({ ok: true });
   } catch (err) {
@@ -108,8 +109,24 @@ export async function refreshInsights(_req: Request, res: Response) {
 
 export async function getInsightsSimple(_req: Request, res: Response) {
   try {
-    const logs = await getLogs();
-    const report = generateInsightsFromLogs(logs);
+    const sinceAnalytics = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+    const analytics = await getBehaviorAnalytics({ behaviorType: 'ENERGY', since: sinceAnalytics });
+    const insights = buildInsightsFromAnalytics(analytics);
+
+    const recentSince = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+    const recentLogs = await prisma.log.findMany({
+      where: { behaviorType: 'ENERGY', timestamp: { gte: recentSince } },
+      orderBy: { timestamp: 'asc' },
+    });
+
+    const report = {
+      analysis: analytics,
+      insights,
+      explainableGuidance: insights.map((item) => ({ message: item.message })),
+      weeklyRecommendations: [],
+      logs: recentLogs,
+    };
+
     res.json(report);
   } catch (err) {
     console.error(err);