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

fi/evals/streaming/policy.py

@@ -0,0 +1,307 @@
+"""Early stop policies for streaming evaluation.
+
+Defines conditions under which streaming evaluation should stop early.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Callable, Any
+from .types import EarlyStopReason, EarlyStopCondition, ChunkResult
+
+
+@dataclass
+class PolicyState:
+    """Tracks state for policy evaluation."""
+
+    consecutive_failures: Dict[str, int] = field(default_factory=dict)
+    total_failures: Dict[str, int] = field(default_factory=dict)
+    triggered_conditions: List[str] = field(default_factory=list)
+
+
+class EarlyStopPolicy:
+    """
+    Policy that determines when to stop streaming evaluation early.
+
+    Manages a set of conditions that can trigger early stopping, such as
+    toxicity thresholds, safety violations, or custom conditions.
+
+    Example:
+        policy = EarlyStopPolicy()
+        policy.add_condition(
+            name="high_toxicity",
+            eval_name="toxicity",
+            threshold=0.7,
+            comparison="above",
+        )
+
+        for chunk_result in stream:
+            should_stop, reason = policy.check(chunk_result)
+            if should_stop:
+                break
+    """
+
+    def __init__(self):
+        """Initialize the policy."""
+        self._conditions: List[EarlyStopCondition] = []
+        self._custom_checks: List[Callable[[ChunkResult], Optional[EarlyStopReason]]] = []
+        self._state = PolicyState()
+
+    def add_condition(
+        self,
+        name: str,
+        eval_name: str,
+        threshold: float,
+        comparison: str = "below",
+        consecutive_chunks: int = 1,
+    ) -> "EarlyStopPolicy":
+        """
+        Add a threshold-based stop condition.
+
+        Args:
+            name: Name for this condition
+            eval_name: Name of the evaluation to check
+            threshold: Threshold value
+            comparison: "below" (stop if score < threshold) or "above" (stop if score > threshold)
+            consecutive_chunks: Number of consecutive chunks that must fail
+
+        Returns:
+            Self for chaining
+        """
+        condition = EarlyStopCondition(
+            name=name,
+            eval_name=eval_name,
+            threshold=threshold,
+            comparison=comparison,
+            consecutive_chunks=consecutive_chunks,
+        )
+        self._conditions.append(condition)
+        return self
+
+    def add_toxicity_stop(
+        self,
+        threshold: float = 0.7,
+        consecutive: int = 1,
+    ) -> "EarlyStopPolicy":
+        """
+        Add toxicity-based stop condition.
+
+        Args:
+            threshold: Stop if toxicity score exceeds this
+            consecutive: Number of consecutive chunks
+
+        Returns:
+            Self for chaining
+        """
+        return self.add_condition(
+            name="toxicity_stop",
+            eval_name="toxicity",
+            threshold=threshold,
+            comparison="above",
+            consecutive_chunks=consecutive,
+        )
+
+    def add_safety_stop(
+        self,
+        threshold: float = 0.3,
+        consecutive: int = 1,
+    ) -> "EarlyStopPolicy":
+        """
+        Add safety-based stop condition.
+
+        Args:
+            threshold: Stop if safety score drops below this
+            consecutive: Number of consecutive chunks
+
+        Returns:
+            Self for chaining
+        """
+        return self.add_condition(
+            name="safety_stop",
+            eval_name="safety",
+            threshold=threshold,
+            comparison="below",
+            consecutive_chunks=consecutive,
+        )
+
+    def add_quality_stop(
+        self,
+        threshold: float = 0.3,
+        consecutive: int = 3,
+    ) -> "EarlyStopPolicy":
+        """
+        Add quality-based stop condition.
+
+        Args:
+            threshold: Stop if quality score stays below this
+            consecutive: Number of consecutive chunks
+
+        Returns:
+            Self for chaining
+        """
+        return self.add_condition(
+            name="quality_stop",
+            eval_name="quality",
+            threshold=threshold,
+            comparison="below",
+            consecutive_chunks=consecutive,
+        )
+
+    def add_custom_check(
+        self,
+        check_fn: Callable[[ChunkResult], Optional[EarlyStopReason]],
+    ) -> "EarlyStopPolicy":
+        """
+        Add a custom check function.
+
+        Args:
+            check_fn: Function that takes ChunkResult and returns
+                      EarlyStopReason if should stop, None otherwise
+
+        Returns:
+            Self for chaining
+        """
+        self._custom_checks.append(check_fn)
+        return self
+
+    def check(self, chunk_result: ChunkResult) -> tuple:
+        """
+        Check if any stop conditions are triggered.
+
+        Args:
+            chunk_result: Result from evaluating a chunk
+
+        Returns:
+            Tuple of (should_stop: bool, reason: EarlyStopReason)
+        """
+        # Check threshold-based conditions
+        for condition in self._conditions:
+            if not condition.enabled:
+                continue
+
+            score = chunk_result.scores.get(condition.eval_name)
+            if score is None:
+                continue
+
+            # Track consecutive failures
+            key = condition.name
+            if self._check_threshold(score, condition.threshold, condition.comparison):
+                self._state.consecutive_failures[key] = (
+                    self._state.consecutive_failures.get(key, 0) + 1
+                )
+                self._state.total_failures[key] = (
+                    self._state.total_failures.get(key, 0) + 1
+                )
+
+                # Check if consecutive threshold met
+                if condition.check(score, self._state.consecutive_failures[key]):
+                    self._state.triggered_conditions.append(condition.name)
+                    return True, self._get_reason_for_condition(condition)
+            else:
+                # Reset consecutive count
+                self._state.consecutive_failures[key] = 0
+
+        # Check custom conditions
+        for check_fn in self._custom_checks:
+            reason = check_fn(chunk_result)
+            if reason is not None:
+                return True, reason
+
+        return False, EarlyStopReason.NONE
+
+    def _check_threshold(
+        self,
+        score: float,
+        threshold: float,
+        comparison: str,
+    ) -> bool:
+        """Check if score triggers threshold."""
+        if comparison == "below":
+            return score < threshold
+        else:
+            return score > threshold
+
+    def _get_reason_for_condition(
+        self,
+        condition: EarlyStopCondition,
+    ) -> EarlyStopReason:
+        """Get the appropriate stop reason for a condition."""
+        name_lower = condition.name.lower()
+        eval_lower = condition.eval_name.lower()
+
+        if "toxic" in name_lower or "toxic" in eval_lower:
+            return EarlyStopReason.TOXICITY
+        elif "safe" in name_lower or "safe" in eval_lower:
+            return EarlyStopReason.SAFETY
+        elif "pii" in name_lower or "pii" in eval_lower:
+            return EarlyStopReason.PII
+        elif "jailbreak" in name_lower or "jailbreak" in eval_lower:
+            return EarlyStopReason.JAILBREAK
+        else:
+            return EarlyStopReason.THRESHOLD
+
+    def reset(self) -> None:
+        """Reset policy state."""
+        self._state = PolicyState()
+
+    def enable_condition(self, name: str) -> None:
+        """Enable a condition by name."""
+        for condition in self._conditions:
+            if condition.name == name:
+                condition.enabled = True
+                break
+
+    def disable_condition(self, name: str) -> None:
+        """Disable a condition by name."""
+        for condition in self._conditions:
+            if condition.name == name:
+                condition.enabled = False
+                break
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get policy statistics."""
+        return {
+            "conditions": [c.to_dict() for c in self._conditions],
+            "consecutive_failures": dict(self._state.consecutive_failures),
+            "total_failures": dict(self._state.total_failures),
+            "triggered_conditions": list(self._state.triggered_conditions),
+            "custom_checks": len(self._custom_checks),
+        }
+
+    @classmethod
+    def default(cls) -> "EarlyStopPolicy":
+        """
+        Create a policy with sensible defaults.
+
+        Returns:
+            EarlyStopPolicy with toxicity and safety stops
+        """
+        policy = cls()
+        policy.add_toxicity_stop(threshold=0.7, consecutive=1)
+        policy.add_safety_stop(threshold=0.3, consecutive=1)
+        return policy
+
+    @classmethod
+    def strict(cls) -> "EarlyStopPolicy":
+        """
+        Create a strict policy for high-risk applications.
+
+        Returns:
+            EarlyStopPolicy with strict thresholds
+        """
+        policy = cls()
+        policy.add_toxicity_stop(threshold=0.5, consecutive=1)
+        policy.add_safety_stop(threshold=0.5, consecutive=1)
+        policy.add_quality_stop(threshold=0.4, consecutive=2)
+        return policy
+
+    @classmethod
+    def permissive(cls) -> "EarlyStopPolicy":
+        """
+        Create a permissive policy that only stops on severe issues.
+
+        Returns:
+            EarlyStopPolicy with high thresholds
+        """
+        policy = cls()
+        policy.add_toxicity_stop(threshold=0.9, consecutive=2)
+        policy.add_safety_stop(threshold=0.1, consecutive=2)
+        return policy

fi/evals/streaming/scorers.py

@@ -0,0 +1,368 @@
+"""Streaming-compatible scorer functions.
+
+Provides lightweight evaluation functions optimized for streaming evaluation.
+These scorers are designed to be fast and work with incremental text.
+"""
+
+import re
+from typing import Callable, List, Set
+
+
+# Toxicity word lists (simplified for demonstration)
+TOXIC_WORDS: Set[str] = {
+    "hate", "kill", "attack", "destroy", "violent", "threat",
+    "abuse", "harass", "racist", "sexist", "discriminate",
+}
+
+PROFANITY_WORDS: Set[str] = {
+    # Basic profanity patterns (simplified)
+}
+
+# PII patterns
+PII_PATTERNS = {
+    "email": re.compile(r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'),
+    "phone": re.compile(r'\b(?:\+?1[-.\s]?)?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}\b'),
+    "ssn": re.compile(r'\b\d{3}-\d{2}-\d{4}\b'),
+    "credit_card": re.compile(r'\b(?:\d{4}[-\s]?){3}\d{4}\b'),
+    "ip_address": re.compile(r'\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b'),
+}
+
+# Jailbreak patterns
+JAILBREAK_PATTERNS = [
+    re.compile(r'ignore\s+(?:all\s+)?(?:previous\s+)?instructions?', re.IGNORECASE),
+    re.compile(r'disregard\s+(?:all\s+)?(?:previous\s+)?instructions?', re.IGNORECASE),
+    re.compile(r'forget\s+(?:all\s+)?(?:previous\s+)?instructions?', re.IGNORECASE),
+    re.compile(r'you\s+are\s+now\s+(?:a\s+)?(?:different|new)', re.IGNORECASE),
+    re.compile(r'pretend\s+(?:you\s+are|to\s+be)', re.IGNORECASE),
+    re.compile(r'act\s+as\s+(?:if|though)', re.IGNORECASE),
+]
+
+
+def toxicity_scorer(chunk: str, cumulative: str) -> float:
+    """
+    Score text for toxicity.
+
+    Returns a score from 0.0 (not toxic) to 1.0 (highly toxic).
+    Uses the cumulative text for better context.
+
+    Args:
+        chunk: Current chunk text
+        cumulative: All text so far
+
+    Returns:
+        Toxicity score (0.0 = safe, 1.0 = toxic)
+    """
+    text = cumulative.lower()
+    words = set(re.findall(r'\b\w+\b', text))
+
+    toxic_count = len(words.intersection(TOXIC_WORDS))
+    total_words = len(words) if words else 1
+
+    # Calculate toxicity ratio with diminishing returns
+    raw_score = toxic_count / max(total_words, 10)
+
+    # Scale to 0-1 range with sensitivity adjustment
+    score = min(1.0, raw_score * 5)
+
+    return score
+
+
+def safety_scorer(chunk: str, cumulative: str) -> float:
+    """
+    Score text for general safety.
+
+    Returns a score from 0.0 (unsafe) to 1.0 (safe).
+    Higher is better (opposite of toxicity).
+
+    Args:
+        chunk: Current chunk text
+        cumulative: All text so far
+
+    Returns:
+        Safety score (0.0 = unsafe, 1.0 = safe)
+    """
+    # Inverse of toxicity
+    toxicity = toxicity_scorer(chunk, cumulative)
+    return 1.0 - toxicity
+
+
+def pii_scorer(chunk: str, cumulative: str) -> float:
+    """
+    Score text for PII presence.
+
+    Returns a score from 0.0 (no PII) to 1.0 (contains PII).
+    Lower is better (no PII is good).
+
+    Args:
+        chunk: Current chunk text
+        cumulative: All text so far
+
+    Returns:
+        PII score (0.0 = no PII, 1.0 = contains PII)
+    """
+    text = cumulative
+    pii_found = 0
+
+    for pattern_name, pattern in PII_PATTERNS.items():
+        matches = pattern.findall(text)
+        pii_found += len(matches)
+
+    # Return 1.0 if any PII found, otherwise 0.0
+    # Could be weighted by severity in production
+    return min(1.0, pii_found * 0.5)
+
+
+def jailbreak_scorer(chunk: str, cumulative: str) -> float:
+    """
+    Score text for jailbreak attempt patterns.
+
+    Returns a score from 0.0 (no jailbreak) to 1.0 (jailbreak detected).
+    Lower is better.
+
+    Args:
+        chunk: Current chunk text
+        cumulative: All text so far
+
+    Returns:
+        Jailbreak score (0.0 = safe, 1.0 = jailbreak detected)
+    """
+    text = cumulative
+
+    for pattern in JAILBREAK_PATTERNS:
+        if pattern.search(text):
+            return 1.0
+
+    return 0.0
+
+
+def coherence_scorer(chunk: str, cumulative: str) -> float:
+    """
+    Score text for coherence.
+
+    A simple heuristic based on sentence structure.
+    Returns 1.0 for coherent text, lower for incoherent.
+
+    Args:
+        chunk: Current chunk text
+        cumulative: All text so far
+
+    Returns:
+        Coherence score (0.0 = incoherent, 1.0 = coherent)
+    """
+    text = cumulative.strip()
+
+    if not text:
+        return 1.0
+
+    # Count sentences
+    sentences = re.split(r'[.!?]+', text)
+    sentences = [s.strip() for s in sentences if s.strip()]
+
+    if not sentences:
+        return 0.5
+
+    # Check for basic coherence indicators
+    score = 1.0
+
+    # Penalize very short average sentence length
+    avg_words = sum(len(s.split()) for s in sentences) / len(sentences)
+    if avg_words < 3:
+        score -= 0.3
+
+    # Penalize excessive repetition
+    words = cumulative.lower().split()
+    if len(words) > 10:
+        unique_ratio = len(set(words)) / len(words)
+        if unique_ratio < 0.3:
+            score -= 0.4
+
+    # Penalize gibberish (high non-alpha ratio)
+    alpha_chars = sum(1 for c in text if c.isalpha() or c.isspace())
+    if len(text) > 0:
+        alpha_ratio = alpha_chars / len(text)
+        if alpha_ratio < 0.7:
+            score -= 0.3
+
+    return max(0.0, score)
+
+
+def quality_scorer(chunk: str, cumulative: str) -> float:
+    """
+    Score text for overall quality.
+
+    Combines multiple heuristics for a quality assessment.
+
+    Args:
+        chunk: Current chunk text
+        cumulative: All text so far
+
+    Returns:
+        Quality score (0.0 = poor, 1.0 = high quality)
+    """
+    text = cumulative.strip()
+
+    if not text:
+        return 0.5
+
+    scores = []
+
+    # Coherence component
+    scores.append(coherence_scorer(chunk, cumulative))
+
+    # Length appropriateness (not too short, not repetitive)
+    words = text.split()
+    if len(words) > 5:
+        scores.append(0.8)
+    else:
+        scores.append(0.5)
+
+    # Punctuation presence
+    if re.search(r'[.!?,]', text):
+        scores.append(0.9)
+    else:
+        scores.append(0.6)
+
+    return sum(scores) / len(scores) if scores else 0.5
+
+
+def create_keyword_scorer(
+    keywords: Set[str],
+    return_high_on_match: bool = True,
+) -> Callable[[str, str], float]:
+    """
+    Create a custom keyword-based scorer.
+
+    Args:
+        keywords: Set of keywords to detect
+        return_high_on_match: If True, returns high score on match
+
+    Returns:
+        Scorer function
+    """
+    keywords_lower = {k.lower() for k in keywords}
+
+    def scorer(chunk: str, cumulative: str) -> float:
+        text = cumulative.lower()
+        words = set(re.findall(r'\b\w+\b', text))
+
+        matches = len(words.intersection(keywords_lower))
+
+        if return_high_on_match:
+            return min(1.0, matches * 0.2)
+        else:
+            return max(0.0, 1.0 - matches * 0.2)
+
+    return scorer
+
+
+def create_pattern_scorer(
+    patterns: List[re.Pattern],
+    return_high_on_match: bool = True,
+) -> Callable[[str, str], float]:
+    """
+    Create a custom regex pattern-based scorer.
+
+    Args:
+        patterns: List of compiled regex patterns
+        return_high_on_match: If True, returns high score on match
+
+    Returns:
+        Scorer function
+    """
+    def scorer(chunk: str, cumulative: str) -> float:
+        text = cumulative
+
+        for pattern in patterns:
+            if pattern.search(text):
+                return 1.0 if return_high_on_match else 0.0
+
+        return 0.0 if return_high_on_match else 1.0
+
+    return scorer
+
+
+class CompositeScorer:
+    """
+    Combines multiple scorers with weights.
+
+    Example:
+        scorer = CompositeScorer()
+        scorer.add(toxicity_scorer, weight=2.0)
+        scorer.add(coherence_scorer, weight=1.0)
+
+        combined_score = scorer(chunk, cumulative)
+    """
+
+    def __init__(self):
+        """Initialize composite scorer."""
+        self._scorers: List[tuple] = []  # (scorer_fn, weight)
+
+    def add(
+        self,
+        scorer: Callable[[str, str], float],
+        weight: float = 1.0,
+    ) -> "CompositeScorer":
+        """
+        Add a scorer with weight.
+
+        Args:
+            scorer: Scorer function
+            weight: Weight for this scorer
+
+        Returns:
+            Self for chaining
+        """
+        self._scorers.append((scorer, weight))
+        return self
+
+    def __call__(self, chunk: str, cumulative: str) -> float:
+        """
+        Calculate weighted average of all scorers.
+
+        Args:
+            chunk: Current chunk text
+            cumulative: All text so far
+
+        Returns:
+            Weighted average score
+        """
+        if not self._scorers:
+            return 0.5
+
+        total_weight = sum(w for _, w in self._scorers)
+        weighted_sum = sum(
+            scorer(chunk, cumulative) * weight
+            for scorer, weight in self._scorers
+        )
+
+        return weighted_sum / total_weight if total_weight > 0 else 0.5
+
+
+# Pre-configured composite scorers
+def safety_composite_scorer(chunk: str, cumulative: str) -> float:
+    """
+    Composite scorer for overall safety.
+
+    Combines toxicity, PII, and jailbreak detection.
+    Returns 1.0 for safe, 0.0 for unsafe.
+    """
+    # Invert toxicity and PII scores (lower is better for them)
+    toxicity = 1.0 - toxicity_scorer(chunk, cumulative)
+    pii = 1.0 - pii_scorer(chunk, cumulative)
+    jailbreak = 1.0 - jailbreak_scorer(chunk, cumulative)
+
+    # Weighted combination (jailbreak is most critical)
+    return (toxicity * 0.3 + pii * 0.3 + jailbreak * 0.4)
+
+
+def quality_composite_scorer(chunk: str, cumulative: str) -> float:
+    """
+    Composite scorer for overall quality.
+
+    Combines coherence and quality metrics.
+    Returns 1.0 for high quality, 0.0 for low quality.
+    """
+    coherence = coherence_scorer(chunk, cumulative)
+    quality = quality_scorer(chunk, cumulative)
+
+    return (coherence * 0.5 + quality * 0.5)