agent-learning-kit 0.1.0__py3-none-any.whl

fi/evals/guardrails/config.py

@@ -0,0 +1,221 @@
+"""
+Guardrails Configuration Module.
+
+Defines configuration classes for the guardrails system including:
+- GuardrailModel: Enum of supported models
+- RailType: Types of rails (input, output, retrieval)
+- AggregationStrategy: How to combine results from multiple models
+- SafetyCategory: Per-category configuration
+- GuardrailsConfig: Main configuration class
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Literal, Set
+from enum import Enum
+
+
+class GuardrailModel(Enum):
+    """Supported guardrail models."""
+
+    # Turing Models (FutureAGI API)
+    TURING_FLASH = "turing_flash"
+    TURING_SAFETY = "turing_safety"
+
+    # Local Models
+    QWEN3GUARD_8B = "qwen3guard-8b"
+    QWEN3GUARD_4B = "qwen3guard-4b"
+    QWEN3GUARD_0_6B = "qwen3guard-0.6b"
+    GRANITE_GUARDIAN_8B = "granite-guardian-3.3-8b"
+    GRANITE_GUARDIAN_5B = "granite-guardian-3.2-5b"
+    WILDGUARD_7B = "wildguard-7b"
+    LLAMAGUARD_3_8B = "llamaguard-3-8b"
+    LLAMAGUARD_3_1B = "llamaguard-3-1b"
+    SHIELDGEMMA_2B = "shieldgemma-2b"
+
+    # Generic LLM as guard (any chat model prompted for safety)
+    LLAMA_3_2_3B = "llama3.2-3b"
+
+    # Third-party API Models
+    OPENAI_MODERATION = "openai-moderation"
+    AZURE_CONTENT_SAFETY = "azure-content-safety"
+
+
+class RailType(Enum):
+    """Types of rails for screening content."""
+    INPUT = "input"       # Screen user input before LLM
+    OUTPUT = "output"     # Screen LLM response before user
+    RETRIEVAL = "retrieval"  # Screen RAG chunks
+
+
+class AggregationStrategy(Enum):
+    """Strategy for combining results from multiple models."""
+    ANY = "any"           # Fail if ANY model flags
+    ALL = "all"           # Fail if ALL models flag
+    MAJORITY = "majority" # Fail if majority flags
+    WEIGHTED = "weighted" # Weighted voting (uses model_weights)
+
+
+@dataclass
+class SafetyCategory:
+    """Configuration for a specific safety category."""
+    name: str
+    enabled: bool = True
+    threshold: float = 0.7
+    action: Literal["block", "flag", "redact", "warn"] = "block"
+    models: List[GuardrailModel] = field(default_factory=list)
+
+    def __post_init__(self):
+        """Validate configuration."""
+        if not 0.0 <= self.threshold <= 1.0:
+            raise ValueError(f"threshold must be between 0.0 and 1.0, got {self.threshold}")
+        if self.action not in ("block", "flag", "redact", "warn"):
+            raise ValueError(f"action must be one of block, flag, redact, warn, got {self.action}")
+
+
+@dataclass
+class TopicConfig:
+    """Configuration for topic restriction scanner."""
+    allowed: List[str] = field(default_factory=list)
+    denied: List[str] = field(default_factory=list)
+    custom_topics: Dict[str, Set[str]] = field(default_factory=dict)
+    min_keyword_matches: int = 2
+
+
+@dataclass
+class LanguageConfig:
+    """Configuration for language detection scanner."""
+    allowed: List[str] = field(default_factory=list)  # e.g., ["en", "es", "fr"]
+    blocked: List[str] = field(default_factory=list)
+    allowed_scripts: List[str] = field(default_factory=lambda: ["Latin", "Common"])
+
+
+@dataclass
+class RegexPatternConfig:
+    """Configuration for a custom regex pattern."""
+    name: str
+    pattern: str
+    confidence: float = 0.8
+    action: Literal["block", "flag", "redact", "warn"] = "block"
+    description: str = ""
+
+
+@dataclass
+class ScannerConfig:
+    """
+    Configuration for content scanners.
+
+    Scanners are lightweight, fast detectors that run before model-based backends.
+    They provide quick detection of specific threats like jailbreaks, code injection, etc.
+
+    Attributes:
+        enabled: Master switch for all scanners
+        jailbreak: Enable jailbreak detection
+        code_injection: Enable SQL/shell injection detection
+        secrets: Enable secrets/credential detection
+        urls: Enable malicious URL detection
+        invisible_chars: Enable invisible character detection
+        language: Language restriction config
+        topics: Topic restriction config
+        regex_patterns: Custom regex patterns
+        parallel: Run scanners in parallel
+        fail_fast: Stop on first failure
+    """
+    enabled: bool = True
+
+    # Individual scanner toggles
+    jailbreak: bool = True
+    code_injection: bool = True
+    secrets: bool = True
+    urls: bool = False  # Disabled by default (can be noisy)
+    invisible_chars: bool = False  # Disabled by default
+    language: Optional[LanguageConfig] = None
+    topics: Optional[TopicConfig] = None
+
+    # Custom regex patterns
+    regex_patterns: List[RegexPatternConfig] = field(default_factory=list)
+    predefined_patterns: List[str] = field(default_factory=list)  # e.g., ["credit_card", "ssn"]
+
+    # Performance settings
+    parallel: bool = True
+    fail_fast: bool = True
+
+    # Thresholds
+    jailbreak_threshold: float = 0.7
+    code_injection_threshold: float = 0.7
+    secrets_threshold: float = 0.7
+    urls_threshold: float = 0.7
+
+
+@dataclass
+class GuardrailsConfig:
+    """
+    Main configuration for the guardrails system.
+
+    Attributes:
+        models: List of models to use for screening
+        rails: Types of rails to enable
+        aggregation: How to combine results from multiple models
+        categories: Per-category configuration
+        timeout_ms: Timeout for each model in milliseconds
+        parallel: Whether to run models in parallel
+        max_workers: Maximum parallel workers
+        fail_open: If True, allow content when guardrails fail
+        fallback_model: Model to use if primary fails
+    """
+
+    # Model selection
+    models: List[GuardrailModel] = field(default_factory=lambda: [
+        GuardrailModel.TURING_FLASH,
+    ])
+
+    # Rail types to enable
+    rails: List[RailType] = field(default_factory=lambda: [
+        RailType.INPUT,
+        RailType.OUTPUT,
+    ])
+
+    # Aggregation strategy for ensemble
+    aggregation: AggregationStrategy = AggregationStrategy.ANY
+
+    # Category-specific configurations
+    categories: Dict[str, SafetyCategory] = field(default_factory=lambda: {
+        "toxicity": SafetyCategory(name="toxicity", threshold=0.7),
+        "hate_speech": SafetyCategory(name="hate_speech", threshold=0.7),
+        "violence": SafetyCategory(name="violence", threshold=0.8),
+        "sexual_content": SafetyCategory(name="sexual_content", threshold=0.8),
+        "self_harm": SafetyCategory(name="self_harm", threshold=0.6, action="block"),
+        "prompt_injection": SafetyCategory(name="prompt_injection", threshold=0.8),
+        "jailbreak": SafetyCategory(name="jailbreak", threshold=0.7),
+        "pii": SafetyCategory(name="pii", action="redact"),
+        "harmful_content": SafetyCategory(name="harmful_content", threshold=0.7),
+        "harassment": SafetyCategory(name="harassment", threshold=0.7),
+        "fraud": SafetyCategory(name="fraud", threshold=0.8),
+        "illegal_activity": SafetyCategory(name="illegal_activity", threshold=0.8),
+    })
+
+    # Performance settings
+    timeout_ms: int = 1000
+    parallel: bool = True
+    max_workers: int = 5
+
+    # Weighted aggregation — maps model value to weight (default 1.0 for unlisted)
+    # Example: {"turing_flash": 2.0, "openai-moderation": 1.0}
+    # weighted_threshold: fraction of total weight needed to block (0.5 = majority)
+    model_weights: Dict[str, float] = field(default_factory=dict)
+    weighted_threshold: float = 0.5
+
+    # Fallback behavior
+    fail_open: bool = False
+    fallback_model: Optional[GuardrailModel] = None
+
+    # Scanner configuration
+    scanners: Optional[ScannerConfig] = None
+
+    def __post_init__(self):
+        """Validate configuration."""
+        if not self.models:
+            raise ValueError("At least one model must be specified")
+        if self.timeout_ms <= 0:
+            raise ValueError(f"timeout_ms must be positive, got {self.timeout_ms}")
+        if self.max_workers <= 0:
+            raise ValueError(f"max_workers must be positive, got {self.max_workers}")

fi/evals/guardrails/discovery.py

@@ -0,0 +1,243 @@
+"""
+Backend Discovery for Guardrails.
+
+Auto-detects available backends based on environment variables,
+API keys, and hardware capabilities.
+"""
+
+import os
+from typing import Dict, List, Optional, Tuple
+
+from fi.evals.guardrails.config import GuardrailModel
+from fi.evals.guardrails.registry import MODEL_REGISTRY
+
+
+class BackendDiscovery:
+    """
+    Auto-discover available guardrail backends.
+
+    Checks for:
+    - API keys (OpenAI, Azure, FutureAGI)
+    - VLLM servers (via environment variables)
+    - GPU availability for local models
+
+    Usage:
+        discovery = BackendDiscovery()
+        available = discovery.discover()
+        print(f"Available backends: {[m.value for m in available]}")
+
+        # Get details
+        details = discovery.get_availability_details()
+        for model, info in details.items():
+            print(f"{model}: {info['status']} - {info['reason']}")
+    """
+
+    def __init__(self):
+        """Initialize discovery."""
+        self._cache: Optional[List[GuardrailModel]] = None
+        self._details_cache: Optional[Dict[str, Dict]] = None
+
+    def discover(self, force_refresh: bool = False) -> List[GuardrailModel]:
+        """
+        Discover available backends.
+
+        Args:
+            force_refresh: Bypass cache and re-check
+
+        Returns:
+            List of available GuardrailModel values
+        """
+        if self._cache is not None and not force_refresh:
+            return self._cache
+
+        available = []
+
+        # Check API backends
+        if self._check_fi_credentials():
+            available.append(GuardrailModel.TURING_FLASH)
+            available.append(GuardrailModel.TURING_SAFETY)
+
+        if self._check_openai_key():
+            available.append(GuardrailModel.OPENAI_MODERATION)
+
+        if self._check_azure_credentials():
+            available.append(GuardrailModel.AZURE_CONTENT_SAFETY)
+
+        # Check local models via VLLM servers
+        for model_value, info in MODEL_REGISTRY.items():
+            if info.model_type == "local":
+                vllm_url = self._get_vllm_url(model_value)
+                if vllm_url and self._check_vllm_health(vllm_url):
+                    available.append(info.model)
+
+        self._cache = available
+        return available
+
+    def get_availability_details(self) -> Dict[str, Dict]:
+        """
+        Get detailed availability information for all models.
+
+        Returns:
+            Dict mapping model names to availability details
+        """
+        if self._details_cache is not None:
+            return self._details_cache
+
+        details = {}
+
+        for model_value, info in MODEL_REGISTRY.items():
+            status = "unavailable"
+            reason = ""
+
+            if info.model_type == "api":
+                if model_value.startswith("turing"):
+                    if self._check_fi_credentials():
+                        status = "available"
+                        reason = "FutureAGI credentials found"
+                    else:
+                        reason = "Missing FI_API_KEY or FI_SECRET_KEY"
+                elif model_value == "openai-moderation":
+                    if self._check_openai_key():
+                        status = "available"
+                        reason = "OPENAI_API_KEY found"
+                    else:
+                        reason = "Missing OPENAI_API_KEY"
+                elif model_value == "azure-content-safety":
+                    if self._check_azure_credentials():
+                        status = "available"
+                        reason = "Azure credentials found"
+                    else:
+                        reason = "Missing AZURE_CONTENT_SAFETY_ENDPOINT or AZURE_CONTENT_SAFETY_KEY"
+
+            elif info.model_type == "local":
+                vllm_url = self._get_vllm_url(model_value)
+                if vllm_url:
+                    if self._check_vllm_health(vllm_url):
+                        status = "available"
+                        reason = f"VLLM server at {vllm_url}"
+                    else:
+                        status = "unavailable"
+                        reason = f"VLLM server at {vllm_url} not responding"
+                else:
+                    gpu_status = self._check_gpu_available()
+                    if gpu_status[0]:
+                        vram = gpu_status[1]
+                        if info.vram_required_gb and vram and vram >= info.vram_required_gb:
+                            status = "available"
+                            reason = f"GPU available ({vram:.1f}GB VRAM)"
+                        elif info.vram_required_gb:
+                            status = "unavailable"
+                            reason = f"Insufficient VRAM ({vram:.1f}GB < {info.vram_required_gb}GB required)"
+                        else:
+                            status = "available"
+                            reason = "GPU available"
+                    else:
+                        status = "unavailable"
+                        reason = "No GPU available and no VLLM server configured"
+
+            details[model_value] = {
+                "status": status,
+                "reason": reason,
+                "model_type": info.model_type,
+                "description": info.description,
+                "hf_model": info.hf_model_name,
+                "vram_required": info.vram_required_gb,
+                "is_gated": info.is_gated,
+            }
+
+        self._details_cache = details
+        return details
+
+    def _check_fi_credentials(self) -> bool:
+        """Check if FutureAGI credentials are available."""
+        return bool(
+            os.environ.get("FI_API_KEY") and
+            os.environ.get("FI_SECRET_KEY")
+        )
+
+    def _check_openai_key(self) -> bool:
+        """Check if OpenAI API key is available."""
+        return bool(os.environ.get("OPENAI_API_KEY"))
+
+    def _check_azure_credentials(self) -> bool:
+        """Check if Azure credentials are available."""
+        return bool(
+            os.environ.get("AZURE_CONTENT_SAFETY_ENDPOINT") and
+            os.environ.get("AZURE_CONTENT_SAFETY_KEY")
+        )
+
+    def _get_vllm_url(self, model_value: str) -> Optional[str]:
+        """Get VLLM server URL for a model."""
+        # Try model-specific env var
+        env_var = f"VLLM_{model_value.upper().replace('-', '_')}_URL"
+        url = os.environ.get(env_var)
+        if url:
+            return url
+
+        # Fall back to generic VLLM_SERVER_URL
+        return os.environ.get("VLLM_SERVER_URL")
+
+    def _check_vllm_health(self, url: str) -> bool:
+        """Check if VLLM server is healthy."""
+        try:
+            import httpx
+            base = url.rstrip('/')
+            with httpx.Client(timeout=5.0) as client:
+                # Try /health (VLLM), fall back to / (ollama)
+                response = client.get(f"{base}/health")
+                if response.status_code == 200:
+                    return True
+                response = client.get(base)
+                return response.status_code == 200
+        except Exception:
+            return False
+
+    def _check_gpu_available(self) -> Tuple[bool, Optional[float]]:
+        """
+        Check if GPU is available and get VRAM.
+
+        Returns:
+            Tuple of (is_available, vram_gb)
+        """
+        try:
+            import torch
+
+            if torch.cuda.is_available():
+                vram = torch.cuda.get_device_properties(0).total_memory / (1024**3)
+                return (True, vram)
+
+            if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+                # MPS doesn't report VRAM, estimate based on typical Apple Silicon
+                return (True, 16.0)  # Conservative estimate
+
+        except ImportError:
+            pass
+
+        return (False, None)
+
+    def _check_hf_token(self) -> bool:
+        """Check if HuggingFace token is available."""
+        return bool(
+            os.environ.get("HF_TOKEN") or
+            os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        )
+
+
+def discover_backends() -> List[GuardrailModel]:
+    """
+    Convenience function to discover available backends.
+
+    Returns:
+        List of available GuardrailModel values
+    """
+    return BackendDiscovery().discover()
+
+
+def get_backend_details() -> Dict[str, Dict]:
+    """
+    Convenience function to get detailed availability info.
+
+    Returns:
+        Dict mapping model names to availability details
+    """
+    return BackendDiscovery().get_availability_details()