forgedev 1.2.0 → 1.3.0

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

@@ -0,0 +1,133 @@
+"""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)
+"""
+
+import json
+import logging
+import threading
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+
+logger = logging.getLogger("ai.audit")
+
+
+@dataclass
+class AuditEntry:
+    """A single AI interaction audit record."""
+
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    model: str = ""
+    purpose: str = "unspecified"
+    input_preview: str = ""
+    confidence: float = 0.0
+    needs_human_review: bool = False
+    latency_ms: float = 0.0
+    token_usage: dict[str, int] | None = None
+    success: bool = True
+    error: str | None = None
+    human_action: str | None = None  # approved | rejected | modified
+    human_reviewer_id: str | None = None
+
+
+class AIAuditLog:
+    """In-memory audit log with structured logging output."""
+
+    def __init__(self, max_entries: int = 1000):
+        self._entries: deque[AuditEntry] = deque(maxlen=max_entries)
+        self._lock = threading.Lock()
+
+    def log(self, entry: AuditEntry) -> None:
+        with self._lock:
+            self._entries.append(entry)
+
+        log_data = {
+            "type": "ai_interaction",
+            "id": entry.id,
+            "timestamp": entry.timestamp,
+            "model": entry.model,
+            "purpose": entry.purpose,
+            "confidence": entry.confidence,
+            "needs_human_review": entry.needs_human_review,
+            "latency_ms": round(entry.latency_ms, 1),
+            "success": entry.success,
+        }
+
+        if entry.error:
+            log_data["error"] = entry.error
+            logger.warning("[AI_AUDIT] %s", json.dumps(log_data))
+        elif entry.confidence < 0.5:
+            logger.warning("[AI_AUDIT] %s", json.dumps(log_data))
+        else:
+            logger.info("[AI_AUDIT] %s", json.dumps(log_data))
+
+    VALID_ACTIONS = {"approved", "rejected", "modified"}
+
+    def record_human_review(
+        self, audit_id: str, action: str, reviewer_id: str | None = None
+    ) -> None:
+        if action not in self.VALID_ACTIONS:
+            raise ValueError(f"Invalid action: {action}. Must be one of {self.VALID_ACTIONS}")
+
+        with self._lock:
+            for entry in self._entries:
+                if entry.id == audit_id:
+                    entry.human_action = action
+                    entry.human_reviewer_id = reviewer_id
+                    break
+            else:
+                logger.warning("[AI_AUDIT] audit_id not found: %s", audit_id)
+                return
+
+        # Log the review event without adding a duplicate to the buffer
+        log_data = {
+            "type": "ai_interaction_review",
+            "id": entry.id,
+            "purpose": f"human-review:{entry.purpose}",
+            "action": action,
+            "reviewer_id": reviewer_id,
+        }
+        logger.info("[AI_AUDIT] %s", json.dumps(log_data))
+
+    def get_recent_entries(self, count: int = 50) -> list[AuditEntry]:
+        with self._lock:
+            return list(self._entries)[-count:]
+
+    def get_stats(self, window_seconds: int = 3600) -> dict:
+        cutoff = datetime.now(timezone.utc) - timedelta(seconds=window_seconds)
+        with self._lock:
+            recent = [
+                e for e in self._entries
+                if datetime.fromisoformat(e.timestamp) >= cutoff
+            ]
+
+        if not recent:
+            return {
+                "total_calls": 0,
+                "success_rate": 1.0,
+                "avg_confidence": 0.0,
+                "avg_latency_ms": 0.0,
+                "human_review_rate": 0.0,
+                "error_rate": 0.0,
+            }
+
+        successes = [e for e in recent if e.success]
+        reviews = [e for e in recent if e.needs_human_review]
+
+        return {
+            "total_calls": len(recent),
+            "success_rate": len(successes) / len(recent),
+            "avg_confidence": sum(e.confidence for e in recent) / len(recent),
+            "avg_latency_ms": sum(e.latency_ms for e in recent) / len(recent),
+            "human_review_rate": len(reviews) / len(recent),
+            "error_rate": 1 - (len(successes) / len(recent)),
+        }
+
+
+# --- Singleton ---
+
+ai_audit_log = AIAuditLog()

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

@@ -0,0 +1,323 @@
+"""AI Client — Central wrapper for all LLM interactions.
+
+Every AI call goes through this client, which provides:
+- Input validation and prompt injection detection
+- Output validation against Pydantic models
+- Confidence scoring with human review routing
+- Structured audit logging (EU AI Act Art. 12)
+- Health metrics collection (NIST AI RMF Manage 3.2)
+
+Compliance: EU AI Act (2024/1689), NIST AI RMF 1.0
+"""
+
+import os
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Callable, TypeVar
+
+import anthropic
+from pydantic import BaseModel, ValidationError
+
+from app.ai.audit_log import ai_audit_log, AuditEntry
+from app.ai.input_guard import validate_input, InputValidationResult
+from app.ai.health import ai_health_metrics
+
+T = TypeVar("T", bound=BaseModel)
+
+
+@dataclass
+class AIClientConfig:
+    """Configuration for the AI client."""
+
+    api_key: str = field(default_factory=lambda: os.environ.get("ANTHROPIC_API_KEY", ""))
+    model: str = "claude-sonnet-4-20250514"
+    confidence_threshold: float = 0.7
+    max_input_length: int = 100_000
+    detect_injection: bool = True
+    audit_log: bool = True
+    moderator: Callable[[str], bool] | None = None
+
+    def __post_init__(self):
+        if not self.api_key:
+            raise ValueError("ANTHROPIC_API_KEY environment variable is required")
+
+
+@dataclass
+class AIResponse:
+    """Response from an AI call with metadata."""
+
+    data: Any
+    confidence: float
+    needs_human_review: bool
+    model: str
+    latency_ms: float
+    token_usage: dict[str, int] | None = None
+    ai_generated: bool = True
+    audit_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    error: str | None = None
+    blocked: bool = False
+
+
+class AIClient:
+    """Central AI client with guardrails, validation, and audit logging."""
+
+    def __init__(self, config: AIClientConfig | None = None):
+        self.config = config or AIClientConfig()
+        self.client = anthropic.AsyncAnthropic(api_key=self.config.api_key)
+
+    async def generate(
+        self,
+        prompt: str,
+        schema: type[T],
+        system_prompt: str | None = None,
+        context: str | None = None,
+        model: str | None = None,
+        confidence_threshold: float | None = None,
+        max_retries: int = 2,
+        purpose: str = "unspecified",
+    ) -> AIResponse:
+        """Generate a structured response validated against a Pydantic model.
+
+        Args:
+            prompt: The user prompt.
+            schema: Pydantic model class to validate output against.
+            system_prompt: Optional system prompt override.
+            context: Additional context appended to the prompt.
+            model: Override model for this call.
+            confidence_threshold: Override threshold for human review.
+            max_retries: Max retries on validation failure.
+            purpose: Business purpose tag for audit log.
+
+        Returns:
+            AIResponse with validated data, confidence score, and audit trail.
+        """
+        start_time = time.monotonic()
+        model = model or self.config.model
+        threshold = confidence_threshold if confidence_threshold is not None else self.config.confidence_threshold
+
+        # Step 1: Input validation
+        input_validation = self._validate_inputs(prompt, context)
+        if input_validation.blocked:
+            return self._build_blocked_response(input_validation, start_time, model, purpose)
+
+        # Step 2: Call model with retries
+        last_error: Exception | None = None
+        for attempt in range(max_retries + 1):
+            try:
+                response = await self._call_model(prompt, system_prompt, context, model)
+
+                # Step 3: Parse and validate output
+                try:
+                    parsed = schema.model_validate_json(response["content"])
+                except (ValidationError, ValueError) as e:
+                    last_error = e
+                    if attempt < max_retries:
+                        continue
+                    break
+
+                # Step 4: Score confidence
+                confidence = self._score_confidence(response)
+                needs_review = confidence < threshold
+
+                # Step 5: Build response
+                result = AIResponse(
+                    data=parsed,
+                    confidence=confidence,
+                    needs_human_review=needs_review,
+                    model=model,
+                    latency_ms=(time.monotonic() - start_time) * 1000,
+                    token_usage=response.get("usage"),
+                    ai_generated=True,
+                )
+
+                # Step 6: Audit log
+                if self.config.audit_log:
+                    self._log_interaction(result, prompt, purpose)
+
+                # Step 7: Health metrics
+                ai_health_metrics.record_call(
+                    model=model,
+                    latency_ms=result.latency_ms,
+                    confidence=confidence,
+                    success=True,
+                    token_usage=response.get("usage"),
+                )
+
+                return result
+
+            except Exception as e:
+                last_error = e
+                if attempt < max_retries:
+                    continue
+
+        # All retries exhausted
+        latency = (time.monotonic() - start_time) * 1000
+        ai_health_metrics.record_call(model=model, latency_ms=latency, confidence=0, success=False)
+
+        return AIResponse(
+            data=None,
+            confidence=0,
+            needs_human_review=True,
+            model=model,
+            latency_ms=latency,
+            error=str(last_error) if last_error else "AI call failed after retries",
+        )
+
+    def _validate_inputs(self, prompt: str, context: str | None) -> InputValidationResult:
+        full_input = f"{prompt}\n{context}" if context else prompt
+
+        if len(full_input) > self.config.max_input_length:
+            return InputValidationResult(
+                blocked=True,
+                reason=f"Input exceeds maximum length ({self.config.max_input_length} chars)",
+            )
+
+        if self.config.detect_injection:
+            result = validate_input(full_input)
+            if result.blocked:
+                return result
+
+        if self.config.moderator and self.config.moderator(full_input):
+            return InputValidationResult(blocked=True, reason="Content blocked by moderation policy")
+
+        return InputValidationResult(blocked=False)
+
+    async def _call_model(
+        self,
+        prompt: str,
+        system_prompt: str | None,
+        context: str | None,
+        model: str,
+    ) -> dict:
+        user_content = f"{prompt}\n\nContext:\n{context}" if context else prompt
+
+        response = await self.client.messages.create(
+            model=model,
+            max_tokens=4096,
+            system=system_prompt or (
+                f"You are an AI assistant for {{PROJECT_NAME}}. "
+                "Respond with valid JSON matching the requested schema. Be precise and factual."
+            ),
+            messages=[{"role": "user", "content": user_content}],
+        )
+
+        text = ""
+        for block in response.content:
+            if block.type == "text":
+                text = block.text
+                break
+
+        # Extract JSON from response
+        content = self._extract_json(text)
+
+        return {
+            "content": content,
+            "usage": {
+                "input_tokens": response.usage.input_tokens,
+                "output_tokens": response.usage.output_tokens,
+            },
+            "stop_reason": response.stop_reason,
+        }
+
+    def _extract_json(self, text: str) -> str:
+        """Extract JSON from model response, handling markdown code blocks."""
+        import re
+
+        text = text.strip()
+
+        # Try direct parse
+        if text.startswith("{") or text.startswith("["):
+            return text
+
+        # Extract from code blocks
+        match = re.search(r"```(?:json)?\s*\n?([\s\S]*?)\n?```", text)
+        if match:
+            return match.group(1).strip()
+
+        return text
+
+    def _score_confidence(self, response: dict) -> float:
+        score = 0.85
+
+        if response.get("stop_reason") == "max_tokens":
+            score -= 0.3
+
+        usage = response.get("usage", {})
+        output_tokens = usage.get("output_tokens", 0)
+
+        if output_tokens < 10:
+            score -= 0.2
+        if output_tokens > 3000:
+            score -= 0.1
+
+        return max(0.0, min(1.0, score))
+
+    def _log_interaction(self, result: AIResponse, prompt: str, purpose: str) -> None:
+        entry = AuditEntry(
+            id=result.audit_id,
+            model=result.model,
+            purpose=purpose,
+            input_preview=prompt[:100] + ("..." if len(prompt) > 100 else ""),
+            confidence=result.confidence,
+            needs_human_review=result.needs_human_review,
+            latency_ms=result.latency_ms,
+            token_usage=result.token_usage,
+            success=result.error is None,
+            error=result.error,
+        )
+        ai_audit_log.log(entry)
+
+    def _build_blocked_response(
+        self,
+        validation: InputValidationResult,
+        start_time: float,
+        model: str,
+        purpose: str,
+    ) -> AIResponse:
+        result = AIResponse(
+            data=None,
+            confidence=0,
+            needs_human_review=False,
+            model=model,
+            latency_ms=(time.monotonic() - start_time) * 1000,
+            ai_generated=False,
+            error=f"Input blocked: {validation.reason}",
+            blocked=True,
+        )
+
+        if self.config.audit_log:
+            ai_audit_log.log(AuditEntry(
+                id=result.audit_id,
+                model=model,
+                purpose=purpose,
+                input_preview="[BLOCKED]",
+                confidence=0,
+                needs_human_review=False,
+                latency_ms=result.latency_ms,
+                success=False,
+                error=validation.reason,
+            ))
+
+        return result
+
+
+# --- Singleton ---
+
+_default_client: AIClient | None = None
+
+
+def get_ai_client(config: AIClientConfig | None = None) -> AIClient:
+    """Get the singleton AI client. Call with config on first use only."""
+    global _default_client
+    if _default_client is None:
+        _default_client = AIClient(config)
+    elif config is not None:
+        import warnings
+        warnings.warn(
+            "AIClient already initialized; ignoring provided config. "
+            "Call get_ai_client() without arguments or use AIClient(config) directly.",
+            UserWarning,
+            stacklevel=2,
+        )
+    return _default_client

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