Update hf_demo.py

hf_demo.py

@@ -1,62 +1,56 @@
 """
-ARF OSS v3.3.9 - Enterprise Lead Generation Engine (API Only)
-Compatible with Pydantic V2
+ARF OSS v3.3.9 - Enterprise Reliability Engine (Backend API only)
 """
 
 import os
-import sys
 import json
 import uuid
 import hashlib
 import logging
 import sqlite3
-import requests
-from datetime import datetime
-from typing import Dict, List, Optional, Any, Tuple
 from contextlib import contextmanager
+from datetime import datetime
 from enum import Enum
+from typing import Dict, List, Optional, Any, Tuple
 
-# FastAPI and Pydantic
+import requests
 from fastapi import FastAPI, HTTPException, Depends, status
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse
 from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
 from pydantic import BaseModel, Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 # ============== CONFIGURATION (Pydantic V2) ==============
 class Settings(BaseSettings):
-    """Centralized configuration using Pydantic Settings V2"""
-    
-    # Hugging Face settings (aliased to match expected env vars)
+    """Application settings loaded from environment variables."""
+    # Hugging Face settings
     hf_space_id: str = Field(default='local', alias='SPACE_ID')
     hf_token: str = Field(default='', alias='HF_TOKEN')
-    
-    # Persistence - HF persistent storage
+
+    # Data persistence directory
     data_dir: str = Field(
         default='/data' if os.path.exists('/data') else './data',
         alias='DATA_DIR'
     )
-    
-    # Lead generation
+
+    # Contact information (used in API responses)
     lead_email: str = "petter2025us@outlook.com"
     calendly_url: str = "https://calendly.com/petter2025us/arf-demo"
-    
-    # Webhook for lead alerts (set in HF secrets)
+
+    # External webhooks (set in secrets)
     slack_webhook: str = Field(default='', alias='SLACK_WEBHOOK')
     sendgrid_api_key: str = Field(default='', alias='SENDGRID_API_KEY')
-    
-    # Security
+
+    # API security
     api_key: str = Field(
         default_factory=lambda: str(uuid.uuid4()),
         alias='ARF_API_KEY'
     )
-    
+
     # ARF defaults
     default_confidence_threshold: float = 0.9
     default_max_risk: str = "MEDIUM"
-    
-    # Pydantic V2 configuration
+
     model_config = SettingsConfigDict(
         populate_by_name=True,
         extra='ignore',
@@ -81,7 +75,7 @@ logging.basicConfig(
 )
 logger = logging.getLogger('arf.oss')
 
-# ============== ENUMS & TYPES ==============
+# ============== ENUMS ==============
 class RiskLevel(str, Enum):
     LOW = "LOW"
     MEDIUM = "MEDIUM"
@@ -101,8 +95,9 @@ class LeadSignal(str, Enum):
     CONFIDENCE_LOW = "confidence_low"
     REPEATED_FAILURE = "repeated_failure"
 
-# ============== BAYESIAN ENGINE ==============
+# ============== BAYESIAN RISK ENGINE ==============
 class BayesianRiskEngine:
+    """True Bayesian inference with conjugate priors."""
     def __init__(self):
         self.prior_alpha = 2.0
         self.prior_beta = 5.0
@@ -115,7 +110,7 @@ class BayesianRiskEngine:
         }
         self.evidence_db = f"{settings.data_dir}/evidence.db"
         self._init_db()
-    
+
     def _init_db(self):
         try:
             with self._get_db() as conn:
@@ -134,7 +129,7 @@ class BayesianRiskEngine:
         except sqlite3.Error as e:
             logger.error(f"Failed to initialize evidence database: {e}")
             raise RuntimeError("Could not initialize evidence storage") from e
-    
+
     @contextmanager
     def _get_db(self):
         conn = None
@@ -147,7 +142,7 @@ class BayesianRiskEngine:
         finally:
             if conn:
                 conn.close()
-    
+
     def classify_action(self, action_text: str) -> str:
         action_lower = action_text.lower()
         if any(word in action_lower for word in ['database', 'db', 'sql', 'table', 'drop', 'delete']):
@@ -160,11 +155,11 @@ class BayesianRiskEngine:
             return 'security'
         else:
             return 'default'
-    
+
     def get_prior(self, action_type: str) -> Tuple[float, float]:
         prior = self.action_priors.get(action_type, self.action_priors['default'])
         return prior['alpha'], prior['beta']
-    
+
     def get_evidence(self, action_hash: str) -> Tuple[int, int]:
         try:
             with self._get_db() as conn:
@@ -177,7 +172,7 @@ class BayesianRiskEngine:
         except sqlite3.Error as e:
             logger.error(f"Failed to retrieve evidence: {e}")
             return (0, 0)
-    
+
     def calculate_posterior(self, action_text: str, context: Dict[str, Any]) -> Dict[str, Any]:
         action_type = self.classify_action(action_text)
         alpha0, beta0 = self.get_prior(action_type)
@@ -189,11 +184,12 @@ class BayesianRiskEngine:
         context_multiplier = self._context_likelihood(context)
         risk_score = posterior_mean * context_multiplier
         risk_score = min(0.99, max(0.01, risk_score))
+
         variance = (alpha_n * beta_n) / ((alpha_n + beta_n)**2 * (alpha_n + beta_n + 1))
         std_dev = variance ** 0.5
         ci_lower = max(0.01, posterior_mean - 1.96 * std_dev)
         ci_upper = min(0.99, posterior_mean + 1.96 * std_dev)
-        
+
         if risk_score > 0.8:
             risk_level = RiskLevel.CRITICAL
         elif risk_score > 0.6:
@@ -202,7 +198,7 @@ class BayesianRiskEngine:
             risk_level = RiskLevel.MEDIUM
         else:
             risk_level = RiskLevel.LOW
-        
+
         return {
             "score": risk_score,
             "level": risk_level,
@@ -217,7 +213,7 @@ class BayesianRiskEngine:
                 × Context multiplier {context_multiplier:.2f} = {risk_score:.3f}
             """
         }
-    
+
     def _context_likelihood(self, context: Dict) -> float:
         multiplier = 1.0
         if context.get('environment') == 'production':
@@ -234,7 +230,7 @@ class BayesianRiskEngine:
         if not context.get('backup_available', True):
             multiplier *= 1.6
         return multiplier
-    
+
     def record_outcome(self, action_text: str, success: bool):
         action_hash = hashlib.sha256(action_text.encode()).hexdigest()
         action_type = self.classify_action(action_text)
@@ -258,6 +254,7 @@ class BayesianRiskEngine:
 
 # ============== POLICY ENGINE ==============
 class PolicyEngine:
+    """Deterministic OSS policies – advisory only."""
     def __init__(self):
         self.config = {
             "confidence_threshold": settings.default_confidence_threshold,
@@ -281,11 +278,11 @@ class PolicyEngine:
             "require_human": [RiskLevel.CRITICAL, RiskLevel.HIGH],
             "require_rollback": True
         }
-    
+
     def evaluate(self, action: str, risk: Dict[str, Any], confidence: float) -> Dict[str, Any]:
         import re
         gates = []
-        
+
         # Gate 1: Confidence threshold
         confidence_passed = confidence >= self.config["confidence_threshold"]
         gates.append({
@@ -296,7 +293,7 @@ class PolicyEngine:
             "reason": f"Confidence {confidence:.2f} {'≥' if confidence_passed else '<'} threshold {self.config['confidence_threshold']}",
             "type": "numerical"
         })
-        
+
         # Gate 2: Risk level
         risk_levels = list(RiskLevel)
         max_idx = risk_levels.index(RiskLevel(self.config["max_autonomous_risk"]))
@@ -311,7 +308,7 @@ class PolicyEngine:
             "type": "categorical",
             "metadata": {"risk_score": risk["score"], "credible_interval": risk["credible_interval"]}
         })
-        
+
         # Gate 3: Destructive check
         is_destructive = any(re.search(pattern, action.lower()) for pattern in self.config["destructive_patterns"])
         gates.append({
@@ -322,7 +319,7 @@ class PolicyEngine:
             "type": "boolean",
             "metadata": {"requires_rollback": is_destructive}
         })
-        
+
         # Gate 4: Human review requirement
         requires_human = risk["level"] in self.config["require_human"]
         gates.append({
@@ -332,7 +329,7 @@ class PolicyEngine:
             "reason": "Human review not required" if not requires_human else f"Human review required for {risk['level'].value} risk",
             "type": "boolean"
         })
-        
+
         # Gate 5: OSS license (always passes)
         gates.append({
             "gate": "license_check",
@@ -341,9 +338,9 @@ class PolicyEngine:
             "reason": "OSS edition - advisory only",
             "type": "license"
         })
-        
+
         all_passed = all(g["passed"] for g in gates)
-        
+
         if not all_passed:
             required_level = ExecutionLevel.OPERATOR_REVIEW
         elif risk["level"] == RiskLevel.LOW:
@@ -352,7 +349,7 @@ class PolicyEngine:
             required_level = ExecutionLevel.AUTONOMOUS_HIGH
         else:
             required_level = ExecutionLevel.SUPERVISED
-        
+
         return {
             "allowed": all_passed,
             "required_level": required_level.value,
@@ -360,7 +357,7 @@ class PolicyEngine:
             "advisory_only": True,
             "oss_disclaimer": "OSS edition provides advisory only. Enterprise adds execution."
         }
-    
+
     def update_config(self, key: str, value: Any):
         if key in self.config:
             self.config[key] = value
@@ -370,11 +367,12 @@ class PolicyEngine:
 
 # ============== RAG MEMORY ==============
 class RAGMemory:
+    """Persistent RAG memory with SQLite and simple embeddings."""
     def __init__(self):
         self.db_path = f"{settings.data_dir}/memory.db"
         self._init_db()
         self.embedding_cache = {}
-    
+
     def _init_db(self):
         try:
             with self._get_db() as conn:
@@ -409,7 +407,7 @@ class RAGMemory:
         except sqlite3.Error as e:
             logger.error(f"Failed to initialize memory database: {e}")
             raise RuntimeError("Could not initialize memory storage") from e
-    
+
     @contextmanager
     def _get_db(self):
         conn = None
@@ -423,7 +421,7 @@ class RAGMemory:
         finally:
             if conn:
                 conn.close()
-    
+
     def _simple_embedding(self, text: str) -> List[float]:
         if text in self.embedding_cache:
             return self.embedding_cache[text]
@@ -438,7 +436,7 @@ class RAGMemory:
         vector = vector[:100]
         self.embedding_cache[text] = vector
         return vector
-    
+
     def store_incident(self, action: str, risk_score: float, risk_level: RiskLevel,
                        confidence: float, allowed: bool, gates: List[Dict]):
         action_hash = hashlib.sha256(action.encode()).hexdigest()[:50]
@@ -464,7 +462,7 @@ class RAGMemory:
                 conn.commit()
         except sqlite3.Error as e:
             logger.error(f"Failed to store incident: {e}")
-    
+
     def find_similar(self, action: str, limit: int = 5) -> List[Dict]:
         query_embedding = self._simple_embedding(action)
         try:
@@ -492,7 +490,7 @@ class RAGMemory:
         except sqlite3.Error as e:
             logger.error(f"Failed to find similar incidents: {e}")
             return []
-    
+
     def track_enterprise_signal(self, signal_type: LeadSignal, action: str,
                                 risk_score: float, metadata: Dict = None):
         signal = {
@@ -523,12 +521,12 @@ class RAGMemory:
         except sqlite3.Error as e:
             logger.error(f"Failed to track signal: {e}")
             return None
-        
+
         logger.info(f"🔔 Enterprise signal: {signal_type.value} - {action[:50]}...")
         if signal_type in [LeadSignal.HIGH_RISK_BLOCKED, LeadSignal.NOVEL_ACTION]:
             self._notify_sales_team(signal)
         return signal
-    
+
     def _notify_sales_team(self, signal: Dict):
         if settings.slack_webhook:
             try:
@@ -542,7 +540,7 @@ class RAGMemory:
                 }, timeout=5)
             except requests.RequestException as e:
                 logger.error(f"Slack notification failed: {e}")
-    
+
     def get_uncontacted_signals(self) -> List[Dict]:
         try:
             with self._get_db() as conn:
@@ -561,7 +559,7 @@ class RAGMemory:
         except sqlite3.Error as e:
             logger.error(f"Failed to get uncontacted signals: {e}")
             return []
-    
+
     def mark_contacted(self, signal_id: str):
         try:
             with self._get_db() as conn:
@@ -581,7 +579,7 @@ async def verify_api_key(credentials: HTTPAuthorizationCredentials = Depends(sec
         )
     return credentials.credentials
 
-# ============== PYDANTIC MODELS ==============
+# ============== PYDANTIC SCHEMAS ==============
 class ActionRequest(BaseModel):
     proposedAction: str = Field(..., min_length=1, max_length=1000)
     confidenceScore: float = Field(..., ge=0.0, le=1.0)
@@ -591,7 +589,7 @@ class ActionRequest(BaseModel):
     rollbackFeasible: bool = True
     user_role: str = "devops"
     session_id: Optional[str] = None
-    
+
     @field_validator('proposedAction')
     @classmethod
     def validate_action(cls, v: str) -> str:
@@ -629,11 +627,11 @@ class LeadSignalResponse(BaseModel):
     timestamp: str
     metadata: Dict
 
-# ============== FASTAPI SETUP ==============
+# ============== FASTAPI APP ==============
 app = FastAPI(
     title="ARF OSS Real Engine (API Only)",
     version="3.3.9",
-    description="Real ARF OSS components for enterprise lead generation - API only",
+    description="Real ARF OSS components for enterprise lead generation – backend API only.",
     contact={
         "name": "ARF Sales",
         "email": settings.lead_email,
@@ -653,10 +651,11 @@ risk_engine = BayesianRiskEngine()
 policy_engine = PolicyEngine()
 memory = RAGMemory()
 
-# ============== ROOT ENDPOINT (for health checks) ==============
+# ============== API ENDPOINTS ==============
+
 @app.get("/")
 async def root():
-    """Root endpoint for platform health checks"""
+    """Root endpoint for platform health checks."""
     return {
         "service": "ARF OSS API",
         "version": "3.3.9",
@@ -664,11 +663,9 @@ async def root():
         "docs": "/docs"
     }
 
-# ============== API ENDPOINTS ==============
-
 @app.get("/health")
 async def health_check():
-    """Public health check endpoint"""
+    """Public health check endpoint."""
     return {
         "status": "healthy",
         "version": "3.3.9",
@@ -679,7 +676,7 @@ async def health_check():
 
 @app.get("/api/v1/config", dependencies=[Depends(verify_api_key)])
 async def get_config():
-    """Get current ARF configuration"""
+    """Get current ARF configuration."""
     return {
         "confidenceThreshold": policy_engine.config["confidence_threshold"],
         "maxAutonomousRisk": policy_engine.config["max_autonomous_risk"],
@@ -690,7 +687,7 @@ async def get_config():
 
 @app.post("/api/v1/config", dependencies=[Depends(verify_api_key)])
 async def update_config(config: ConfigUpdateRequest):
-    """Update ARF configuration"""
+    """Update ARF configuration (protected)."""
     if config.confidenceThreshold:
         policy_engine.update_config("confidence_threshold", config.confidenceThreshold)
     if config.maxAutonomousRisk:
@@ -700,7 +697,7 @@ async def update_config(config: ConfigUpdateRequest):
 @app.post("/api/v1/evaluate", dependencies=[Depends(verify_api_key)], response_model=EvaluationResponse)
 async def evaluate_action(request: ActionRequest):
     """
-    Real ARF OSS evaluation pipeline
+    Real ARF OSS evaluation pipeline – protected.
     """
     try:
         context = {
@@ -709,20 +706,20 @@ async def evaluate_action(request: ActionRequest):
             "backup_available": request.rollbackFeasible,
             "requires_human": request.requiresHuman
         }
-        
+
         risk = risk_engine.calculate_posterior(
             action_text=request.proposedAction,
             context=context
         )
-        
+
         policy = policy_engine.evaluate(
             action=request.proposedAction,
             risk=risk,
             confidence=request.confidenceScore
         )
-        
+
         similar = memory.find_similar(request.proposedAction, limit=3)
-        
+
         if not policy["allowed"] and risk["score"] > 0.7:
             memory.track_enterprise_signal(
                 signal_type=LeadSignal.HIGH_RISK_BLOCKED,
@@ -734,7 +731,7 @@ async def evaluate_action(request: ActionRequest):
                     "failed_gates": [g["gate"] for g in policy["gates"] if not g["passed"]]
                 }
             )
-        
+
         if len(similar) < 2 and risk["score"] > 0.6:
             memory.track_enterprise_signal(
                 signal_type=LeadSignal.NOVEL_ACTION,
@@ -742,7 +739,7 @@ async def evaluate_action(request: ActionRequest):
                 risk_score=risk["score"],
                 metadata={"similar_count": len(similar)}
             )
-        
+
         memory.store_incident(
             action=request.proposedAction,
             risk_score=risk["score"],
@@ -751,7 +748,7 @@ async def evaluate_action(request: ActionRequest):
             allowed=policy["allowed"],
             gates=policy["gates"]
         )
-        
+
         gates = []
         for g in policy["gates"]:
             gates.append(GateResult(
@@ -763,7 +760,7 @@ async def evaluate_action(request: ActionRequest):
                 type=g.get("type", "boolean"),
                 metadata=g.get("metadata")
             ))
-        
+
         execution_ladder = {
             "levels": [
                 {"name": "AUTONOMOUS_LOW", "required": gates[0].passed and gates[1].passed},
@@ -773,7 +770,7 @@ async def evaluate_action(request: ActionRequest):
             ],
             "current": policy["required_level"]
         }
-        
+
         return EvaluationResponse(
             allowed=policy["allowed"],
             requiredLevel=policy["required_level"],
@@ -782,7 +779,7 @@ async def evaluate_action(request: ActionRequest):
             escalationReason=None if policy["allowed"] else "Failed mechanical gates",
             executionLadder=execution_ladder
         )
-        
+
     except Exception as e:
         logger.error(f"Evaluation failed: {e}", exc_info=True)
         raise HTTPException(
@@ -793,7 +790,7 @@ async def evaluate_action(request: ActionRequest):
 @app.get("/api/v1/enterprise/signals", dependencies=[Depends(verify_api_key)])
 async def get_enterprise_signals(contacted: bool = False):
     """
-    Get enterprise lead signals
+    Get enterprise lead signals (protected).
     """
     try:
         if contacted:
@@ -823,25 +820,28 @@ async def get_enterprise_signals(contacted: bool = False):
 
 @app.post("/api/v1/enterprise/signals/{signal_id}/contact", dependencies=[Depends(verify_api_key)])
 async def mark_signal_contacted(signal_id: str):
+    """Mark a lead signal as contacted (protected)."""
     memory.mark_contacted(signal_id)
     return {"status": "success", "message": "Signal marked as contacted"}
 
 @app.get("/api/v1/memory/similar", dependencies=[Depends(verify_api_key)])
 async def get_similar_actions(action: str, limit: int = 5):
+    """Find similar historical actions (protected)."""
     similar = memory.find_similar(action, limit=limit)
     return {"similar": similar, "count": len(similar)}
 
 @app.post("/api/v1/feedback", dependencies=[Depends(verify_api_key)])
 async def record_outcome(action: str, success: bool):
+    """Record actual outcome for Bayesian updating (protected)."""
     risk_engine.record_outcome(action, success)
     return {"status": "success", "message": "Outcome recorded"}
 
 # ============== MAIN ENTRY POINT ==============
 if __name__ == "__main__":
     import uvicorn
-    
+
     port = int(os.environ.get('PORT', 7860))
-    
+
     logger.info("="*60)
     logger.info("🚀 ARF OSS v3.3.9 (API Only) Starting")
     logger.info(f"📊 Data directory: {settings.data_dir}")
@@ -849,10 +849,10 @@ if __name__ == "__main__":
     logger.info(f"🔑 API Key: {settings.api_key[:8]}... (set in HF secrets)")
     logger.info(f"🌐 Serving API at: http://0.0.0.0:{port}")
     logger.info("="*60)
-    
+
     uvicorn.run(
         "hf_demo:app",
-        host="0.0.0.0", 
+        host="0.0.0.0",
         port=port,
         log_level="info",
         reload=False