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

fi/evals/guardrails/scanners/urls.py

@@ -0,0 +1,341 @@
+"""
+Malicious URL Scanner for Guardrails.
+
+Detects suspicious URLs, phishing attempts, and malicious links.
+"""
+
+import re
+import time
+from typing import List, Optional, Set, Tuple
+from urllib.parse import urlparse
+
+from fi.evals.guardrails.scanners.base import (
+    BaseScanner,
+    ScanResult,
+    ScanMatch,
+    ScannerAction,
+    register_scanner,
+)
+
+
+# URL extraction pattern
+URL_PATTERN = re.compile(
+    r'https?://[^\s<>"\']+|'
+    r'www\.[^\s<>"\']+|'
+    r'[a-zA-Z0-9][-a-zA-Z0-9]*\.[a-zA-Z]{2,}(?:/[^\s<>"\']*)?'
+)
+
+# Suspicious TLDs often used in phishing
+SUSPICIOUS_TLDS: Set[str] = {
+    "xyz", "top", "work", "click", "link", "gq", "ml", "cf", "ga", "tk",
+    "zip", "mov", "app", "dev",  # New TLDs that can be confusing
+    "ru", "cn", "su",  # Sometimes associated with malicious content
+}
+
+# Known URL shorteners
+URL_SHORTENERS: Set[str] = {
+    "bit.ly", "tinyurl.com", "t.co", "goo.gl", "ow.ly", "is.gd",
+    "buff.ly", "adf.ly", "bc.vc", "j.mp", "tr.im", "tiny.cc",
+    "lnkd.in", "db.tt", "qr.ae", "cur.lv", "ity.im", "q.gs",
+    "po.st", "su.pr", "rebrand.ly", "shorturl.at",
+}
+
+# Legitimate domains that are often spoofed
+SPOOFED_DOMAINS: List[Tuple[str, List[str]]] = [
+    ("google", ["g00gle", "googie", "gooogle", "google-", "-google"]),
+    ("facebook", ["faceb00k", "facebok", "faceboook", "facebook-", "-facebook"]),
+    ("microsoft", ["micros0ft", "mircosoft", "microsoft-", "-microsoft"]),
+    ("apple", ["app1e", "appie", "apple-", "-apple"]),
+    ("amazon", ["amaz0n", "amazonn", "amazon-", "-amazon"]),
+    ("paypal", ["paypa1", "paypai", "paypal-", "-paypal"]),
+    ("netflix", ["netf1ix", "netiflix", "netflix-", "-netflix"]),
+    ("linkedin", ["linkedln", "linkedin-", "-linkedin"]),
+    ("twitter", ["tw1tter", "twitter-", "-twitter"]),
+    ("instagram", ["lnstagram", "instagram-", "-instagram"]),
+    ("whatsapp", ["whatsap", "whatsapp-", "-whatsapp"]),
+    ("dropbox", ["dr0pbox", "dropbox-", "-dropbox"]),
+    ("github", ["g1thub", "github-", "-github"]),
+    ("openai", ["0penai", "openal", "openai-", "-openai"]),
+]
+
+
+def _extract_urls(text: str) -> List[Tuple[str, int, int]]:
+    """Extract URLs from text with positions."""
+    urls = []
+    for match in URL_PATTERN.finditer(text):
+        url = match.group()
+        # Add protocol if missing
+        if not url.startswith(('http://', 'https://')):
+            url = 'https://' + url
+        urls.append((url, match.start(), match.end()))
+    return urls
+
+
+def _get_domain(url: str) -> Optional[str]:
+    """Extract domain from URL."""
+    try:
+        parsed = urlparse(url)
+        return parsed.netloc.lower()
+    except Exception:
+        return None
+
+
+def _check_homoglyph(domain: str) -> Optional[str]:
+    """Check for homoglyph attacks (lookalike characters)."""
+    # Common homoglyphs
+    homoglyphs = {
+        '0': 'o', '1': 'i', '@': 'a',
+        '$': 's', '3': 'e', '4': 'a', '5': 's',
+        '6': 'b', '7': 't', '8': 'b', '9': 'g',
+    }
+
+    normalized = domain
+    for fake, real in homoglyphs.items():
+        normalized = normalized.replace(fake, real)
+
+    if normalized != domain:
+        return normalized
+    return None
+
+
+@register_scanner("urls")
+class MaliciousURLScanner(BaseScanner):
+    """
+    Scanner for detecting malicious and suspicious URLs.
+
+    Detects:
+    - Phishing URLs (lookalike domains)
+    - IP-based URLs
+    - Suspicious TLDs
+    - URL shorteners (optional)
+    - Data URLs with executable content
+    - Encoded URLs
+
+    Usage:
+        scanner = MaliciousURLScanner()
+        result = scanner.scan("Visit https://g00gle.com/login")
+        if not result.passed:
+            print(f"Suspicious URL: {result.matched_patterns}")
+    """
+
+    name = "urls"
+    category = "malicious_url"
+    description = "Detects phishing URLs and malicious links"
+    default_action = ScannerAction.FLAG  # Flag rather than block by default
+
+    def __init__(
+        self,
+        action: Optional[ScannerAction] = None,
+        enabled: bool = True,
+        threshold: float = 0.7,
+        block_ip_urls: bool = True,
+        block_suspicious_tlds: bool = True,
+        block_shorteners: bool = False,  # Disabled by default
+        block_data_urls: bool = True,
+        check_homoglyphs: bool = True,
+        allowed_domains: Optional[Set[str]] = None,
+        blocked_domains: Optional[Set[str]] = None,
+    ):
+        """
+        Initialize URL scanner.
+
+        Args:
+            action: Action on detection
+            enabled: Whether scanner is enabled
+            threshold: Minimum confidence to trigger
+            block_ip_urls: Block URLs with IP addresses
+            block_suspicious_tlds: Block URLs with suspicious TLDs
+            block_shorteners: Block URL shorteners
+            block_data_urls: Block data: URLs
+            check_homoglyphs: Check for lookalike domains
+            allowed_domains: Whitelist of allowed domains
+            blocked_domains: Blacklist of blocked domains
+        """
+        super().__init__(action, enabled)
+        self.threshold = threshold
+        self.block_ip_urls = block_ip_urls
+        self.block_suspicious_tlds = block_suspicious_tlds
+        self.block_shorteners = block_shorteners
+        self.block_data_urls = block_data_urls
+        self.check_homoglyphs = check_homoglyphs
+        self.allowed_domains = allowed_domains or set()
+        self.blocked_domains = blocked_domains or set()
+
+    def _is_ip_address(self, domain: str) -> bool:
+        """Check if domain is an IP address."""
+        # IPv4
+        ipv4_pattern = r'^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$'
+        if re.match(ipv4_pattern, domain):
+            return True
+        # IPv6
+        if ':' in domain and domain.replace(':', '').replace('.', '').isalnum():
+            return True
+        return False
+
+    def _check_phishing(self, domain: str) -> Optional[Tuple[str, str]]:
+        """Check if domain is a phishing attempt."""
+        domain_lower = domain.lower()
+
+        for legit, fakes in SPOOFED_DOMAINS:
+            for fake in fakes:
+                if fake in domain_lower:
+                    return (legit, fake)
+
+            # Also check for the legitimate name in suspicious context
+            if legit in domain_lower and not domain_lower.endswith(f".{legit}.com"):
+                # e.g., google.suspicious.com
+                parts = domain_lower.split('.')
+                if len(parts) > 2 and legit in parts[0]:
+                    return (legit, f"{legit} subdomain")
+
+        return None
+
+    def scan(self, content: str, context: Optional[str] = None) -> ScanResult:
+        """
+        Scan content for malicious URLs.
+
+        Args:
+            content: Content to scan
+            context: Optional context
+
+        Returns:
+            ScanResult with detection details
+        """
+        start = time.perf_counter()
+        matches = []
+        max_confidence = 0.0
+        issues = set()
+
+        # Check for data URLs
+        if self.block_data_urls:
+            data_url_pattern = re.compile(r'data:[^;]+;base64,[a-zA-Z0-9+/=]+', re.IGNORECASE)
+            for match in data_url_pattern.finditer(content):
+                # Check if it's potentially executable
+                url = match.group().lower()
+                if any(t in url for t in ['javascript', 'text/html', 'application/']):
+                    matches.append(ScanMatch(
+                        pattern_name="data_url_executable",
+                        matched_text=match.group()[:50] + "...",
+                        start=match.start(),
+                        end=match.end(),
+                        confidence=0.95,
+                    ))
+                    max_confidence = max(max_confidence, 0.95)
+                    issues.add("Executable data URL")
+
+        # Extract and check URLs
+        urls = _extract_urls(content)
+
+        for url, start_pos, end_pos in urls:
+            domain = _get_domain(url)
+            if not domain:
+                continue
+
+            # Skip allowed domains
+            if domain in self.allowed_domains:
+                continue
+
+            # Check blocked domains
+            if domain in self.blocked_domains:
+                matches.append(ScanMatch(
+                    pattern_name="blocked_domain",
+                    matched_text=url,
+                    start=start_pos,
+                    end=end_pos,
+                    confidence=1.0,
+                ))
+                max_confidence = 1.0
+                issues.add("Blocked domain")
+                continue
+
+            # Check IP-based URLs
+            if self.block_ip_urls and self._is_ip_address(domain.split(':')[0]):
+                matches.append(ScanMatch(
+                    pattern_name="ip_url",
+                    matched_text=url,
+                    start=start_pos,
+                    end=end_pos,
+                    confidence=0.8,
+                ))
+                max_confidence = max(max_confidence, 0.8)
+                issues.add("IP-based URL")
+
+            # Check suspicious TLDs
+            if self.block_suspicious_tlds:
+                tld = domain.split('.')[-1]
+                if tld in SUSPICIOUS_TLDS:
+                    matches.append(ScanMatch(
+                        pattern_name="suspicious_tld",
+                        matched_text=url,
+                        start=start_pos,
+                        end=end_pos,
+                        confidence=0.6,
+                        metadata={"tld": tld},
+                    ))
+                    max_confidence = max(max_confidence, 0.6)
+                    issues.add(f"Suspicious TLD (.{tld})")
+
+            # Check URL shorteners
+            if self.block_shorteners and domain in URL_SHORTENERS:
+                matches.append(ScanMatch(
+                    pattern_name="url_shortener",
+                    matched_text=url,
+                    start=start_pos,
+                    end=end_pos,
+                    confidence=0.5,
+                ))
+                max_confidence = max(max_confidence, 0.5)
+                issues.add("URL shortener")
+
+            # Check phishing (lookalike domains)
+            if self.check_homoglyphs:
+                phishing = self._check_phishing(domain)
+                if phishing:
+                    legit, fake = phishing
+                    matches.append(ScanMatch(
+                        pattern_name="phishing_domain",
+                        matched_text=url,
+                        start=start_pos,
+                        end=end_pos,
+                        confidence=0.9,
+                        metadata={"spoofed_brand": legit, "technique": fake},
+                    ))
+                    max_confidence = max(max_confidence, 0.9)
+                    issues.add(f"Phishing ({legit} lookalike)")
+
+                # Also check homoglyphs
+                normalized = _check_homoglyph(domain)
+                if normalized:
+                    matches.append(ScanMatch(
+                        pattern_name="homoglyph_attack",
+                        matched_text=url,
+                        start=start_pos,
+                        end=end_pos,
+                        confidence=0.85,
+                        metadata={"normalized": normalized},
+                    ))
+                    max_confidence = max(max_confidence, 0.85)
+                    issues.add("Homoglyph attack")
+
+        latency = (time.perf_counter() - start) * 1000
+
+        # Filter by threshold
+        significant_matches = [m for m in matches if m.confidence >= self.threshold]
+
+        if significant_matches:
+            return self._create_result(
+                passed=False,
+                matches=significant_matches,
+                score=max_confidence,
+                reason=f"Suspicious URLs detected: {', '.join(issues)}",
+                latency_ms=latency,
+                metadata={"issues": list(issues)},
+            )
+
+        return self._create_result(
+            passed=True,
+            matches=[],
+            score=0.0,
+            reason="No malicious URLs detected",
+            latency_ms=latency,
+        )

fi/evals/guardrails/types.py

@@ -0,0 +1,96 @@
+"""
+Guardrails Types Module.
+
+Defines response types for the guardrails system:
+- GuardrailResult: Result from a single model
+- GuardrailsResponse: Aggregated response from all models
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class GuardrailResult:
+    """Result from a single guardrail model check."""
+
+    passed: bool
+    category: str
+    score: float
+    model: str
+    reason: Optional[str] = None
+    action: str = "pass"  # "block", "flag", "redact", "warn", "pass"
+    latency_ms: float = 0.0
+
+    def __post_init__(self):
+        """Validate result."""
+        if not 0.0 <= self.score <= 1.0:
+            # Clamp score to valid range
+            self.score = max(0.0, min(1.0, self.score))
+
+
+@dataclass
+class GuardrailsResponse:
+    """Aggregated response from all guardrails."""
+
+    passed: bool
+    results: List[GuardrailResult] = field(default_factory=list)
+    blocked_categories: List[str] = field(default_factory=list)
+    flagged_categories: List[str] = field(default_factory=list)
+    redacted_content: Optional[str] = None
+    original_content: str = ""
+    total_latency_ms: float = 0.0
+    models_used: List[str] = field(default_factory=list)
+    error: Optional[str] = None
+
+    @classmethod
+    def create_passed(
+        cls,
+        content: str,
+        latency_ms: float = 0.0,
+        models_used: Optional[List[str]] = None,
+        results: Optional[List[GuardrailResult]] = None,
+    ) -> "GuardrailsResponse":
+        """Create a passed response."""
+        return cls(
+            passed=True,
+            original_content=content,
+            total_latency_ms=latency_ms,
+            models_used=models_used or [],
+            results=results or [],
+        )
+
+    @classmethod
+    def create_blocked(
+        cls,
+        content: str,
+        blocked_categories: List[str],
+        latency_ms: float = 0.0,
+        models_used: Optional[List[str]] = None,
+        results: Optional[List[GuardrailResult]] = None,
+        reason: Optional[str] = None,
+    ) -> "GuardrailsResponse":
+        """Create a blocked response."""
+        return cls(
+            passed=False,
+            original_content=content,
+            blocked_categories=blocked_categories,
+            total_latency_ms=latency_ms,
+            models_used=models_used or [],
+            results=results or [],
+            error=reason,
+        )
+
+    @classmethod
+    def create_error(
+        cls,
+        content: str,
+        error: str,
+        fail_open: bool = False,
+    ) -> "GuardrailsResponse":
+        """Create an error response."""
+        return cls(
+            passed=fail_open,  # If fail_open, allow content
+            original_content=content,
+            error=error,
+        )

fi/evals/llm/__init__.py

@@ -0,0 +1,3 @@
+from .providers.litellm import LiteLLMProvider
+
+__all__ = ["LiteLLMProvider"]

fi/evals/llm/base_llm_provider.py

@@ -0,0 +1,35 @@
+from abc import ABC, abstractmethod
+from typing import List, Dict, Any, Optional, Type
+
+from pydantic import BaseModel
+
+
+class LLMProvider(ABC):
+    """
+    Abstract base class for LLM providers.
+
+    This defines the standard interface that all LLM inference backends
+    must implement to be compatible with the LLM-as-a-judge framework.
+    """
+
+    @abstractmethod
+    def get_completion(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        response_format: Optional[Type[BaseModel] | Dict[str, str]] = None,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Generates a text completion from a list of messages.
+
+        Args:
+            model (str): The name or identifier of the model to use.
+            messages (List[Dict[str, Any]]): The chat messages, following the OpenAI format.
+                Content can be a string or a list of content parts for multimodal inputs.
+            **kwargs: Provider-specific arguments like temperature, max_tokens, etc.
+
+        Returns:
+            str: The content of the generated message.
+        """
+        raise NotImplementedError

fi/evals/llm/providers/litellm.py

@@ -0,0 +1,70 @@
+from typing import Any, Dict, List, Optional, Type
+import litellm
+from pydantic import BaseModel
+from ..base_llm_provider import LLMProvider
+import openai
+
+
+class LiteLLMProvider(LLMProvider):
+    """The default provider, using the litellm library to connect to any API."""
+
+    def __init__(self, credentials: Optional[Dict[str, Any]] = None):
+        """
+        Initializes the LiteLLMProvider.
+
+        Args:
+            credentials (Optional[Dict[str, Any]]): A dictionary containing authentication
+                details that map directly to litellm.completion() arguments.
+
+                Examples:
+                - For OpenAI: `{"api_key": "sk-..."}`
+                - For Azure: `{"api_key": "...", "api_base": "...", "api_version": "..."}`
+                - For other providers, see LiteLLM documentation.
+
+                If not provided, LiteLLM will fall back to its default behavior
+                (i.e., checking for environment variables like OPENAI_API_KEY).
+        """
+        self.credentials = credentials or {}
+        self.schema_support_cache: Dict[str, bool] = {}
+
+    def _supports_schema(self, model: str) -> bool:
+        """Checks if a model supports response_format with caching."""
+        if model not in self.schema_support_cache:
+            try:
+                self.schema_support_cache[model] = litellm.supports_response_schema(
+                    model
+                )
+            except Exception:
+                self.schema_support_cache[model] = False
+        return self.schema_support_cache[model]
+
+    def get_completion(
+        self,
+        model: str,
+        messages: List[Dict[str, Any]],
+        response_format: Optional[Type[BaseModel] | Dict[str, str]] = None,
+        **kwargs: Any,
+    ):
+        completion_args = {**self.credentials, **kwargs}
+
+        if response_format and self._supports_schema(model):
+            completion_args["response_format"] = response_format
+
+        try:
+            # drop unknown/unsupported params in kwargs
+            litellm.drop_params = True
+            response = litellm.completion(
+                model=model, messages=messages, **completion_args
+            )
+            content = response.choices[0].message.content
+            if content is None:
+                raise ValueError("Received null content from the LLM API.")
+            return content
+
+        except openai.APIError as openai_error:
+            # Wrap litellm exceptions in a standard error
+            raise RuntimeError(
+                f"LiteLLM provider failed: {openai_error}"
+            ) from openai_error
+        except Exception as e:
+            raise RuntimeError(f"Unknown error occured in LiteLLM :{e}")

fi/evals/local/__init__.py

@@ -0,0 +1,90 @@
+"""Local execution module for running evaluations without API calls.
+
+This module provides the infrastructure for running heuristic metrics locally,
+enabling offline evaluation and faster feedback loops during development.
+
+It also supports local LLM inference via Ollama for running LLM-as-judge
+evaluations without cloud API calls.
+
+Example:
+    >>> from fi.evals.local import LocalEvaluator, ExecutionMode
+    >>>
+    >>> # Run a metric locally
+    >>> evaluator = LocalEvaluator()
+    >>> result = evaluator.evaluate(
+    ...     metric_name="contains",
+    ...     inputs=[{"response": "Hello world"}],
+    ...     config={"keyword": "world"}
+    ... )
+    >>> print(result.results.eval_results[0].output)
+    1.0
+
+    >>> # Check if a metric can run locally
+    >>> evaluator.can_run_locally("contains")  # True
+    >>> evaluator.can_run_locally("groundedness")  # False (requires LLM)
+
+    >>> # Use hybrid mode to automatically route
+    >>> from fi.evals.local import HybridEvaluator
+    >>> hybrid = HybridEvaluator()
+    >>> partitions = hybrid.partition_evaluations([
+    ...     {"metric_name": "contains", "inputs": [...]},
+    ...     {"metric_name": "groundedness", "inputs": [...]},
+    ... ])
+    >>> # partitions[ExecutionMode.LOCAL] = [contains eval]
+    >>> # partitions[ExecutionMode.CLOUD] = [groundedness eval]
+
+    >>> # Use local LLM for LLM-based evaluations
+    >>> from fi.evals.local import OllamaLLM, HybridEvaluator
+    >>> llm = OllamaLLM()
+    >>> hybrid = HybridEvaluator(local_llm=llm)
+    >>> result = llm.judge(
+    ...     query="What is AI?",
+    ...     response="AI is artificial intelligence.",
+    ...     criteria="Evaluate if the response correctly answers the question."
+    ... )
+    >>> print(result["score"])
+    0.9
+"""
+
+from .execution_mode import (
+    RoutingMode,
+    LOCAL_CAPABLE_METRICS,
+    can_run_locally,
+    select_routing_mode,
+)
+from .registry import (
+    LocalMetricRegistry,
+    get_registry,
+)
+from .evaluator import (
+    LocalEvaluator,
+    LocalEvaluatorConfig,
+    LocalEvaluationResult,
+    HybridEvaluator,
+)
+from .llm import (
+    LocalLLMConfig,
+    OllamaLLM,
+    LocalLLMFactory,
+)
+
+
+__all__ = [
+    # Routing mode
+    "RoutingMode",
+    "LOCAL_CAPABLE_METRICS",
+    "can_run_locally",
+    "select_routing_mode",
+    # Registry
+    "LocalMetricRegistry",
+    "get_registry",
+    # Evaluator
+    "LocalEvaluator",
+    "LocalEvaluatorConfig",
+    "LocalEvaluationResult",
+    "HybridEvaluator",
+    # Local LLM
+    "LocalLLMConfig",
+    "OllamaLLM",
+    "LocalLLMFactory",
+]