forgedev 1.2.0 → 1.4.0

package/templates/ai/guardrails-py/backend/app/ai/health.py.template

@@ -0,0 +1,157 @@
+"""AI Health Check — Observability endpoint for AI system metrics.
+
+Compliance: NIST AI RMF Manage 3.2 (monitoring),
+            EU AI Act Art. 9 (risk management)
+
+Mount as: router.include_router(ai_health_router, prefix="/api/ai")
+"""
+
+import time
+from collections import deque
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import APIRouter
+
+ai_health_router = APIRouter(tags=["ai-health"])
+
+
+@dataclass
+class CallMetric:
+    timestamp: float
+    model: str
+    latency_ms: float
+    confidence: float
+    success: bool
+    token_usage: dict[str, int] | None = None
+
+
+class AIHealthMetrics:
+    def __init__(self, max_metrics: int = 5000):
+        self._metrics: deque[CallMetric] = deque(maxlen=max_metrics)
+
+    def record_call(
+        self,
+        model: str,
+        latency_ms: float,
+        confidence: float,
+        success: bool,
+        token_usage: dict[str, int] | None = None,
+    ) -> None:
+        self._metrics.append(CallMetric(
+            timestamp=time.time(),
+            model=model,
+            latency_ms=latency_ms,
+            confidence=confidence,
+            success=success,
+            token_usage=token_usage,
+        ))
+
+    def get_health_status(self, window_seconds: int = 3600) -> dict[str, Any]:
+        cutoff = time.time() - window_seconds
+        recent = [m for m in self._metrics if m.timestamp >= cutoff]
+
+        if not recent:
+            return {
+                "status": "ok",
+                "ai_available": True,
+                "message": "No AI calls in the monitoring window",
+                "window": f"{window_seconds // 60}m",
+                "metrics": self._empty_metrics(),
+                "models": {},
+            }
+
+        successes = [m for m in recent if m.success]
+        error_rate = 1 - (len(successes) / len(recent))
+        avg_confidence = (
+            sum(m.confidence for m in successes) / len(successes) if successes else 0
+        )
+        avg_latency = sum(m.latency_ms for m in recent) / len(recent)
+        low_confidence = [m for m in successes if m.confidence < 0.7]
+        low_confidence_rate = len(low_confidence) / max(len(successes), 1)
+
+        # Determine status
+        status = "ok"
+        warnings: list[str] = []
+
+        if error_rate > 0.5:
+            status = "unhealthy"
+            warnings.append(f"High error rate: {error_rate * 100:.1f}%")
+        elif error_rate > 0.1:
+            status = "degraded"
+            warnings.append(f"Elevated error rate: {error_rate * 100:.1f}%")
+
+        if avg_confidence < 0.5:
+            status = "degraded" if status == "ok" else status
+            warnings.append(f"Low average confidence: {avg_confidence * 100:.1f}%")
+
+        if avg_latency > 10_000:
+            status = "degraded" if status == "ok" else status
+            warnings.append(f"High average latency: {avg_latency:.0f}ms")
+
+        # Per-model breakdown
+        models: dict[str, dict] = {}
+        model_names = set(m.model for m in recent)
+        for model_name in model_names:
+            model_calls = [m for m in recent if m.model == model_name]
+            model_successes = [m for m in model_calls if m.success]
+            total_tokens = sum(
+                (m.token_usage.get("input_tokens", 0) + m.token_usage.get("output_tokens", 0))
+                for m in model_calls if m.token_usage
+            )
+            models[model_name] = {
+                "calls": len(model_calls),
+                "success_rate": len(model_successes) / len(model_calls),
+                "avg_latency_ms": sum(m.latency_ms for m in model_calls) / len(model_calls),
+                "avg_confidence": (
+                    sum(m.confidence for m in model_successes) / len(model_successes)
+                    if model_successes else 0
+                ),
+                "total_tokens": total_tokens,
+            }
+
+        return {
+            "status": status,
+            "ai_available": error_rate < 1,
+            "message": "; ".join(warnings) if warnings else "All AI systems operating normally",
+            "window": f"{window_seconds // 60}m",
+            "metrics": {
+                "total_calls": len(recent),
+                "success_rate": 1 - error_rate,
+                "avg_confidence": avg_confidence,
+                "avg_latency_ms": avg_latency,
+                "low_confidence_rate": low_confidence_rate,
+                "error_rate": error_rate,
+            },
+            "models": models,
+        }
+
+    def _empty_metrics(self) -> dict:
+        return {
+            "total_calls": 0,
+            "success_rate": 1.0,
+            "avg_confidence": 0.0,
+            "avg_latency_ms": 0.0,
+            "low_confidence_rate": 0.0,
+            "error_rate": 0.0,
+        }
+
+
+# --- Singleton ---
+
+ai_health_metrics = AIHealthMetrics()
+
+
+# --- FastAPI Health Endpoint ---
+
+@ai_health_router.get("/health")
+async def ai_health():
+    """AI system health check.
+
+    Returns model availability, confidence distribution,
+    error rates, and per-model metrics.
+    """
+    return ai_health_metrics.get_health_status()
+
+
+AIHealthStatus = dict  # Type alias for documentation

package/templates/ai/guardrails-py/backend/app/ai/input_guard.py

@@ -0,0 +1,98 @@
+"""AI Input Guard — Prompt injection detection and input sanitization.
+
+Compliance: EU AI Act Art. 15 (robustness), NIST AI RMF Manage 2.2
+"""
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class InputValidationResult:
+    blocked: bool
+    reason: str | None = None
+    detected_patterns: list[str] = field(default_factory=list)
+
+
+# --- Injection Detection Patterns ---
+
+INJECTION_PATTERNS: list[tuple[re.Pattern, str]] = [
+    # Direct instruction override
+    (re.compile(r"ignore\s+(all\s+)?(previous|prior|above)\s+(instructions|prompts|rules)", re.I), "instruction-override"),
+    (re.compile(r"disregard\s+(all\s+)?(previous|prior|above|your)\s+(instructions|prompts|rules|training)", re.I), "instruction-override"),
+    (re.compile(r"forget\s+(all\s+)?(previous|prior|your)\s+(instructions|context|rules)", re.I), "instruction-override"),
+
+    # Role manipulation
+    (re.compile(r"you\s+are\s+now\s+(a|an|the)\s+", re.I), "role-manipulation"),
+    (re.compile(r"act\s+as\s+(if\s+you\s+are|a|an)\s+", re.I), "role-manipulation"),
+    (re.compile(r"pretend\s+(to\s+be|you\s+are)\s+", re.I), "role-manipulation"),
+    (re.compile(r"from\s+now\s+on\s+(you|your)\s+", re.I), "role-manipulation"),
+
+    # System prompt extraction
+    (re.compile(r"what\s+(is|are)\s+your\s+(system\s+)?(prompt|instructions|rules)", re.I), "prompt-extraction"),
+    (re.compile(r"show\s+me\s+your\s+(system\s+)?(prompt|instructions)", re.I), "prompt-extraction"),
+    (re.compile(r"repeat\s+(your|the)\s+(system\s+)?(prompt|instructions)", re.I), "prompt-extraction"),
+    (re.compile(r"print\s+(your|the)\s+(system\s+)?(prompt|instructions)", re.I), "prompt-extraction"),
+
+    # Delimiter injection
+    (re.compile(r"</?system>", re.I), "delimiter-injection"),
+    (re.compile(r"\[INST\]", re.I), "delimiter-injection"),
+    (re.compile(r"<\|im_start\|", re.I), "delimiter-injection"),
+    (re.compile(r"###\s*(system|instruction|human|assistant)", re.I), "delimiter-injection"),
+
+    # Data exfiltration
+    (re.compile(r"send\s+(this|the|all)\s+(data|info|conversation)\s+to", re.I), "data-exfiltration"),
+    (re.compile(r"forward\s+(this|everything)\s+to", re.I), "data-exfiltration"),
+]
+
+SUSPICIOUS_PATTERNS: list[tuple[re.Pattern, str]] = [
+    (re.compile(r"eval\s*\(", re.I), "code-execution"),
+    (re.compile(r"exec\s*\(", re.I), "code-execution"),
+    (re.compile(r"import\s+(?:os|subprocess)|subprocess\.", re.I), "code-execution"),
+    (re.compile(r"[A-Za-z0-9+/]{100,}={0,2}", re.I), "encoded-payload"),
+]
+
+
+def validate_input(text: str) -> InputValidationResult:
+    """Validate input for prompt injection and safety concerns."""
+    import unicodedata
+    # Normalize Unicode to defeat homoglyph attacks (e.g., Cyrillic "а" for Latin "a")
+    normalized = unicodedata.normalize("NFKC", text)
+    detected: list[str] = []
+
+    for pattern, name in INJECTION_PATTERNS:
+        if pattern.search(normalized):
+            detected.append(name)
+
+    if detected:
+        unique = list(set(detected))
+        return InputValidationResult(
+            blocked=True,
+            reason=f"Potential prompt injection detected: {', '.join(unique)}",
+            detected_patterns=unique,
+        )
+
+    suspicious: list[str] = []
+    for pattern, name in SUSPICIOUS_PATTERNS:
+        if pattern.search(normalized):
+            suspicious.append(name)
+
+    if suspicious:
+        return InputValidationResult(
+            blocked=False,
+            reason=f"Suspicious patterns detected (not blocked): {', '.join(suspicious)}",
+            detected_patterns=suspicious,
+        )
+
+    return InputValidationResult(blocked=False)
+
+
+def sanitize_input(text: str) -> str:
+    """Remove known dangerous patterns from input."""
+    sanitized = re.sub(r"</?system>", "", text, flags=re.I)
+    sanitized = re.sub(r"\[INST\]", "", sanitized, flags=re.I)
+    sanitized = re.sub(r"<\|im_start\|[^>]*>?", "", sanitized, flags=re.I)
+    sanitized = re.sub(r"<\|im_end\|>?", "", sanitized, flags=re.I)
+    sanitized = re.sub(r"###\s*(system|instruction|human|assistant)", "", sanitized, flags=re.I)
+    sanitized = sanitized.replace("\x00", "")
+    return sanitized

package/templates/ai/guardrails-ts/src/lib/ai/audit-log.ts.template

@@ -0,0 +1,164 @@
+/**
+ * AI Audit Logger — Structured logging of all AI interactions.
+ *
+ * Compliance: EU AI Act Art. 12 (logging and traceability),
+ *             NIST AI RMF Manage 1.3 (monitoring)
+ *
+ * Every AI call is logged with:
+ * - Input preview (truncated, no PII in logs)
+ * - Output confidence score
+ * - Model version and parameters
+ * - Human review decisions
+ * - Latency and token usage
+ * - Error details
+ *
+ * Logs are structured JSON for easy ingestion into observability platforms
+ * (Datadog, Grafana, ELK, etc.)
+ */
+
+export interface AuditEntry {
+  /** Unique interaction ID (matches AIResponse.auditId) */
+  id: string;
+  /** ISO 8601 timestamp */
+  timestamp: string;
+  /** Model identifier */
+  model: string;
+  /** Business purpose of this AI call */
+  purpose: string;
+  /** Truncated input for traceability (never log full PII) */
+  inputPreview: string;
+  /** Confidence score (0-1) */
+  confidence: number;
+  /** Whether human review was triggered */
+  needsHumanReview: boolean;
+  /** Total latency in milliseconds */
+  latencyMs: number;
+  /** Token usage for cost tracking */
+  tokenUsage?: { inputTokens: number; outputTokens: number };
+  /** Whether the call succeeded */
+  success: boolean;
+  /** Error message if failed */
+  error?: string;
+  /** Human reviewer action (if reviewed) */
+  humanAction?: 'approved' | 'rejected' | 'modified';
+  /** Human reviewer ID (if reviewed) */
+  humanReviewerId?: string;
+}
+
+export interface AuditLogConfig {
+  /** Where to send logs: 'console' or custom handler */
+  destination: 'console' | 'custom';
+  /** Custom log handler */
+  handler?: (entry: AuditEntry) => void;
+  /** Log level filter: only log entries with confidence below this */
+  confidenceAlertThreshold?: number;
+}
+
+class AIAuditLog {
+  private config: AuditLogConfig;
+  private entries: AuditEntry[] = [];
+  private maxInMemory = 1000;
+
+  constructor(config?: Partial<AuditLogConfig>) {
+    this.config = {
+      destination: config?.destination || 'console',
+      handler: config?.handler,
+      confidenceAlertThreshold: config?.confidenceAlertThreshold ?? 0.5,
+    };
+  }
+
+  log(entry: AuditEntry): void {
+    // In-memory buffer for health metrics
+    this.entries.push(entry);
+    if (this.entries.length > this.maxInMemory) {
+      this.entries = this.entries.slice(-this.maxInMemory);
+    }
+
+    // Structured log output (exclude inputPreview to avoid PII in logs)
+    const { inputPreview: _preview, ...safeEntry } = entry;
+    const logEntry = {
+      level: entry.success ? 'info' : 'error',
+      type: 'ai_interaction',
+      ...safeEntry,
+    };
+
+    switch (this.config.destination) {
+      case 'console':
+        if (!entry.success || (entry.confidence < (this.config.confidenceAlertThreshold ?? 0.5))) {
+          console.warn('[AI_AUDIT]', JSON.stringify(logEntry));
+        } else {
+          console.log('[AI_AUDIT]', JSON.stringify(logEntry));
+        }
+        break;
+      case 'custom':
+        this.config.handler?.(entry);
+        break;
+    }
+  }
+
+  /**
+   * Record a human review decision against an existing audit entry.
+   */
+  recordHumanReview(auditId: string, action: 'approved' | 'rejected' | 'modified', reviewerId?: string): void {
+    const entry = this.entries.find(e => e.id === auditId);
+    if (!entry) {
+      console.warn(`[AI_AUDIT] Cannot record human review: audit entry ${auditId} not found`);
+      return;
+    }
+    entry.humanAction = action;
+    entry.humanReviewerId = reviewerId;
+    // Re-emit to log destination without adding duplicate to buffer
+    const logEntry = {
+      level: 'info',
+      type: 'ai_interaction_review',
+      ...entry,
+    };
+    if (this.config.destination === 'console') {
+      console.log('[AI_AUDIT]', JSON.stringify(logEntry));
+    } else if (this.config.destination === 'custom') {
+      this.config.handler?.(entry);
+    }
+  }
+
+  /**
+   * Get recent entries for monitoring dashboard.
+   */
+  getRecentEntries(count = 50): AuditEntry[] {
+    return this.entries.slice(-count);
+  }
+
+  /**
+   * Get aggregate stats for AI health reporting.
+   */
+  getStats(windowMs = 3600_000): {
+    totalCalls: number;
+    successRate: number;
+    avgConfidence: number;
+    avgLatencyMs: number;
+    humanReviewRate: number;
+    errorRate: number;
+  } {
+    const cutoff = new Date(Date.now() - windowMs).toISOString();
+    const recent = this.entries.filter(e => e.timestamp >= cutoff);
+
+    if (recent.length === 0) {
+      return { totalCalls: 0, successRate: 1, avgConfidence: 0, avgLatencyMs: 0, humanReviewRate: 0, errorRate: 0 };
+    }
+
+    const successes = recent.filter(e => e.success).length;
+    const reviews = recent.filter(e => e.needsHumanReview).length;
+
+    return {
+      totalCalls: recent.length,
+      successRate: successes / recent.length,
+      avgConfidence: recent.reduce((sum, e) => sum + e.confidence, 0) / recent.length,
+      avgLatencyMs: recent.reduce((sum, e) => sum + e.latencyMs, 0) / recent.length,
+      humanReviewRate: reviews / recent.length,
+      errorRate: 1 - (successes / recent.length),
+    };
+  }
+}
+
+// --- Singleton ---
+
+export const aiAuditLog = new AIAuditLog();