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

fi/evals/metrics/hallucination/nli.py

@@ -0,0 +1,253 @@
+"""
+Natural Language Inference utilities for hallucination detection.
+
+Provides entailment checking between claims and context.
+Uses transformer-based NLI when available (pip install ai-evaluation[nli]),
+falls back to word-overlap heuristic with a warning.
+"""
+
+import re
+import warnings
+from typing import Tuple, List, Optional
+from enum import Enum
+
+
+_NLI_MODEL = "cross-encoder/nli-deberta-v3-base"
+
+# Try to import transformers
+_NLI_AVAILABLE = False
+try:
+    from transformers import pipeline as _hf_pipeline
+    _NLI_AVAILABLE = True
+except ImportError:
+    pass
+
+_nli_pipeline = None
+_heuristic_warning_issued = False
+
+
+class NLILabel(Enum):
+    """NLI classification labels."""
+
+    ENTAILMENT = "entailment"
+    CONTRADICTION = "contradiction"
+    NEUTRAL = "neutral"
+
+
+def _get_nli_pipeline():
+    """Lazy-load NLI pipeline. Returns the pipeline or False on failure."""
+    global _nli_pipeline
+    if _nli_pipeline is not None:
+        return _nli_pipeline
+
+    if not _NLI_AVAILABLE:
+        _nli_pipeline = False
+        return False
+
+    try:
+        _nli_pipeline = _hf_pipeline(
+            "text-classification",
+            model=_NLI_MODEL,
+            device=-1,  # CPU
+        )
+    except Exception as exc:
+        warnings.warn(
+            f"Failed to load NLI model '{_NLI_MODEL}': {exc}. "
+            "Falling back to word-overlap heuristic. "
+            "Install with: pip install ai-evaluation[nli]",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        _nli_pipeline = False
+
+    return _nli_pipeline
+
+
+def _warn_heuristic_fallback():
+    """Issue a one-time warning that we're using the heuristic fallback."""
+    global _heuristic_warning_issued
+    if not _heuristic_warning_issued:
+        _heuristic_warning_issued = True
+        warnings.warn(
+            "NLI model not available — using word-overlap heuristic for "
+            "hallucination detection. Results will be approximate. "
+            "For accurate NLI, install: pip install ai-evaluation[nli]",
+            RuntimeWarning,
+            stacklevel=3,
+        )
+
+
+_LABEL_MAP = {
+    "ENTAILMENT": NLILabel.ENTAILMENT,
+    "CONTRADICTION": NLILabel.CONTRADICTION,
+    "NEUTRAL": NLILabel.NEUTRAL,
+    "entailment": NLILabel.ENTAILMENT,
+    "contradiction": NLILabel.CONTRADICTION,
+    "neutral": NLILabel.NEUTRAL,
+}
+
+
+def check_entailment(premise: str, hypothesis: str) -> Tuple[NLILabel, float]:
+    """
+    Check if premise entails hypothesis using NLI model.
+
+    Args:
+        premise: The source text (context)
+        hypothesis: The claim to verify
+
+    Returns:
+        Tuple of (NLI label, confidence score)
+    """
+    nli = _get_nli_pipeline()
+
+    if not nli:
+        _warn_heuristic_fallback()
+        return check_entailment_heuristic(premise, hypothesis)
+
+    try:
+        result = nli(
+            {"text": premise, "text_pair": hypothesis},
+            truncation=True,
+            max_length=512,
+        )
+        # Dict input returns a single dict, not a list
+        entry = result[0] if isinstance(result, list) else result
+        label = _LABEL_MAP.get(entry["label"], NLILabel.NEUTRAL)
+        score = entry["score"]
+        return label, score
+    except Exception:
+        return check_entailment_heuristic(premise, hypothesis)
+
+
+# ---------------------------------------------------------------------------
+# Heuristic fallback
+# ---------------------------------------------------------------------------
+
+_STOPWORDS = frozenset({
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "must", "shall", "can", "to", "of", "in",
+    "for", "on", "with", "at", "by", "from", "as", "and", "or", "but",
+    "if", "that", "this", "it", "its", "they", "their", "he", "she",
+    "him", "her", "his", "we", "our", "you", "your",
+})
+
+_NEGATIONS = frozenset({
+    "not", "n't", "never", "no", "none", "neither", "nor", "cannot",
+})
+
+
+def _tokenize(text: str) -> set:
+    """Tokenize text into content words, stripping punctuation."""
+    return set(re.findall(r"\b\w+\b", text.lower()))
+
+
+def check_entailment_heuristic(
+    premise: str, hypothesis: str
+) -> Tuple[NLILabel, float]:
+    """
+    Heuristic entailment check using word overlap and similarity.
+
+    Fallback when NLI model is not available. Uses:
+    - Content word overlap for entailment signal
+    - Negation asymmetry for contradiction detection
+    - Numeric mismatch detection
+
+    Args:
+        premise: The source text (context)
+        hypothesis: The claim to verify
+
+    Returns:
+        Tuple of (NLI label, confidence score)
+    """
+    premise_words = _tokenize(premise)
+    hypothesis_words = _tokenize(hypothesis)
+
+    premise_content = premise_words - _STOPWORDS
+    hypothesis_content = hypothesis_words - _STOPWORDS
+
+    if not hypothesis_content:
+        return NLILabel.NEUTRAL, 0.5
+
+    overlap = len(premise_content & hypothesis_content)
+    coverage = overlap / len(hypothesis_content)
+
+    # Check for negation asymmetry
+    premise_has_neg = bool(premise_words & _NEGATIONS)
+    hypothesis_has_neg = bool(hypothesis_words & _NEGATIONS)
+
+    if premise_has_neg != hypothesis_has_neg and coverage > 0.5:
+        return NLILabel.CONTRADICTION, 0.6
+
+    # Check for numeric mismatch — only when high overlap + claim has numbers not in premise
+    premise_numbers = set(re.findall(r"\b\d+(?:\.\d+)?\b", premise))
+    hypothesis_numbers = set(re.findall(r"\b\d+(?:\.\d+)?\b", hypothesis))
+
+    if hypothesis_numbers and premise_numbers and coverage > 0.5:
+        novel_numbers = hypothesis_numbers - premise_numbers
+        if novel_numbers and len(novel_numbers) <= 2:
+            return NLILabel.CONTRADICTION, 0.55
+
+    if coverage >= 0.65:
+        return NLILabel.ENTAILMENT, coverage
+    elif coverage >= 0.3:
+        return NLILabel.NEUTRAL, coverage
+    else:
+        return NLILabel.NEUTRAL, coverage
+
+
+def check_contradiction(claim: str, context: str) -> Tuple[bool, float]:
+    """
+    Check if claim contradicts the context.
+
+    Args:
+        claim: The claim to check
+        context: The context to check against
+
+    Returns:
+        Tuple of (is_contradiction, confidence)
+    """
+    label, score = check_entailment(context, claim)
+
+    if label == NLILabel.CONTRADICTION:
+        return True, score
+
+    return False, 0.0
+
+
+def nli_score_for_claim(
+    claim: str, contexts: List[str]
+) -> Tuple[NLILabel, float, Optional[str]]:
+    """
+    Get the best NLI score for a claim against multiple contexts.
+
+    Args:
+        claim: The claim to verify
+        contexts: List of context passages
+
+    Returns:
+        Tuple of (best_label, best_score, best_context_snippet)
+    """
+    best_label = NLILabel.NEUTRAL
+    best_score = 0.0
+    best_context = None
+
+    for ctx in contexts:
+        label, score = check_entailment(ctx, claim)
+
+        if label == NLILabel.CONTRADICTION and score > 0.5:
+            # Contradiction takes priority if confident
+            snippet = ctx[:200] + "..." if len(ctx) > 200 else ctx
+            return label, score, snippet
+
+        if label == NLILabel.ENTAILMENT and score > best_score:
+            best_label = label
+            best_score = score
+            best_context = ctx[:200] + "..." if len(ctx) > 200 else ctx
+        elif label == NLILabel.NEUTRAL and best_label != NLILabel.ENTAILMENT:
+            if score > best_score:
+                best_label = label
+                best_score = score
+                best_context = ctx[:200] + "..." if len(ctx) > 200 else ctx
+
+    return best_label, best_score, best_context

fi/evals/metrics/hallucination/sentinel.py

@@ -0,0 +1,106 @@
+"""
+Hallucination Sentinel — fast pre-screening before full NLI.
+
+Provides rule-based screening to quickly flag responses
+that are likely or unlikely to contain hallucinations,
+avoiding expensive NLI inference for obvious cases.
+"""
+
+import re
+from typing import Dict, List, Literal, Tuple
+
+
+RiskLevel = Literal["low", "medium", "high"]
+
+
+# Patterns that indicate high hallucination risk
+_HIGH_RISK_PATTERNS = [
+    r"\baccording to (?:recent|latest|new)\b",
+    r"\bstudies (?:show|prove|confirm|suggest)\b",
+    r"\bresearch (?:shows|proves|confirms|suggests)\b",
+    r"\bstatistics (?:show|indicate|reveal)\b",
+    r"\b\d+(?:\.\d+)?%\b",  # Specific percentages
+    r"\bin \d{4}\b",  # Specific years
+    r"\bexactly \d+\b",  # Exact numbers
+    r"\bproven (?:fact|to be)\b",
+    r"\bit is (?:well[- ]known|widely accepted|universally agreed)\b",
+]
+
+# Patterns that indicate the response is hedging (lower risk)
+_HEDGE_PATTERNS = [
+    r"\bI (?:think|believe|am not sure)\b",
+    r"\b(?:might|may|could|possibly|perhaps|probably)\b",
+    r"\b(?:it seems|it appears|it looks like)\b",
+    r"\bI don't (?:know|have)\b",
+    r"\bnot (?:certain|sure|clear)\b",
+]
+
+
+class HallucinationSentinel:
+    """Fast rule-based screening for hallucination risk."""
+
+    def __init__(
+        self,
+        extra_risk_patterns: List[str] = None,
+    ):
+        self.risk_patterns = _HIGH_RISK_PATTERNS + (extra_risk_patterns or [])
+
+    def screen(
+        self, response: str, context: str
+    ) -> Tuple[RiskLevel, Dict]:
+        """
+        Screen a response for hallucination risk.
+
+        Args:
+            response: The LLM response to screen
+            context: The source context
+
+        Returns:
+            Tuple of (risk_level, details dict)
+        """
+        response_lower = response.lower()
+        context_lower = context.lower()
+
+        details: Dict = {
+            "risk_signals": [],
+            "hedge_signals": [],
+        }
+
+        # Check risk patterns
+        risk_count = 0
+        for pattern in self.risk_patterns:
+            matches = re.findall(pattern, response_lower, re.IGNORECASE)
+            if matches:
+                risk_count += len(matches)
+                details["risk_signals"].append(pattern)
+
+        # Check hedging patterns
+        hedge_count = 0
+        for pattern in _HEDGE_PATTERNS:
+            if re.search(pattern, response_lower, re.IGNORECASE):
+                hedge_count += 1
+                details["hedge_signals"].append(pattern)
+
+        # Check if claims reference things not in context
+        # Simple: response words not found in context
+        response_words = set(re.findall(r"\b\w{4,}\b", response_lower))
+        context_words = set(re.findall(r"\b\w{4,}\b", context_lower))
+        novel_ratio = len(response_words - context_words) / max(len(response_words), 1)
+        details["novel_word_ratio"] = round(novel_ratio, 3)
+
+        # Determine risk level
+        if risk_count >= 3 or (risk_count >= 1 and novel_ratio > 0.6):
+            risk_level: RiskLevel = "high"
+        elif risk_count >= 1 or novel_ratio > 0.5:
+            risk_level = "medium"
+        else:
+            risk_level = "low"
+
+        # Hedging reduces risk
+        if hedge_count >= 2 and risk_level == "high":
+            risk_level = "medium"
+
+        details["risk_count"] = risk_count
+        details["hedge_count"] = hedge_count
+
+        return risk_level, details

fi/evals/metrics/hallucination/types.py

@@ -0,0 +1,132 @@
+"""
+Types for Hallucination Detection.
+
+These types support NLI-based and semantic analysis for
+detecting hallucinations in LLM outputs.
+"""
+
+from typing import Any, Dict, List, Literal, Optional, Union
+from pydantic import BaseModel, Field
+
+from ...types import BaseMetricInput
+
+
+class Claim(BaseModel):
+    """Represents a single claim extracted from text."""
+
+    text: str = Field(..., description="The claim text")
+    source_span: Optional[str] = Field(
+        default=None,
+        description="Original text span the claim was extracted from"
+    )
+    confidence: Optional[float] = Field(
+        default=None,
+        description="Confidence score for claim extraction (0-1)"
+    )
+
+
+class HallucinationInput(BaseMetricInput):
+    """
+    Input for hallucination detection metrics.
+
+    Evaluates whether the response contains claims not supported
+    by the provided context/source.
+    """
+
+    # The LLM response to check for hallucinations
+    response: str = Field(
+        ...,
+        description="The LLM response to evaluate for hallucinations."
+    )
+
+    # The source/context that the response should be faithful to
+    context: Union[str, List[str]] = Field(
+        ...,
+        description="Source context(s) the response should be grounded in."
+    )
+
+    # Optional: pre-extracted claims from response
+    claims: Optional[List[Claim]] = Field(
+        default=None,
+        description="Pre-extracted claims from response. If not provided, claims are extracted automatically."
+    )
+
+    # Optional: the query that generated the response
+    query: Optional[str] = Field(
+        default=None,
+        description="The original query/question that generated the response."
+    )
+
+
+class ClaimExtractionInput(BaseMetricInput):
+    """
+    Input for claim extraction from text.
+
+    Extracts atomic, verifiable claims from a text passage.
+    """
+
+    response: str = Field(
+        ...,
+        description="The text to extract claims from."
+    )
+
+    # Extraction granularity
+    granularity: Literal["sentence", "clause", "atomic"] = Field(
+        default="sentence",
+        description="Granularity of claim extraction: sentence, clause, or atomic (finest)."
+    )
+
+
+class FactualConsistencyInput(BaseMetricInput):
+    """
+    Input for factual consistency checking.
+
+    Evaluates whether claims in the response are consistent with
+    known facts or a reference text.
+    """
+
+    response: str = Field(
+        ...,
+        description="The response to check for factual consistency."
+    )
+
+    # Reference for fact-checking
+    reference: Optional[str] = Field(
+        default=None,
+        description="Reference text containing ground truth facts."
+    )
+
+    # Pre-extracted claims
+    claims: Optional[List[Claim]] = Field(
+        default=None,
+        description="Pre-extracted claims from the response."
+    )
+
+
+class NLIResult(BaseModel):
+    """Result of Natural Language Inference classification."""
+
+    premise: str = Field(..., description="The premise (context)")
+    hypothesis: str = Field(..., description="The hypothesis (claim)")
+    label: Literal["entailment", "neutral", "contradiction"] = Field(
+        ...,
+        description="NLI classification label"
+    )
+    scores: Dict[str, float] = Field(
+        default_factory=dict,
+        description="Probability scores for each label"
+    )
+
+
+class HallucinationResult(BaseModel):
+    """Detailed result of hallucination detection."""
+
+    score: float = Field(..., description="Overall hallucination score (0=hallucinated, 1=faithful)")
+    claims_analyzed: int = Field(..., description="Number of claims analyzed")
+    supported_claims: int = Field(..., description="Number of claims supported by context")
+    unsupported_claims: int = Field(..., description="Number of unsupported claims")
+    contradicted_claims: int = Field(..., description="Number of contradicted claims")
+    claim_details: List[Dict[str, Any]] = Field(
+        default_factory=list,
+        description="Detailed analysis for each claim"
+    )

fi/evals/metrics/heuristics/aggregation_metrics.py

@@ -0,0 +1,85 @@
+import json
+from typing import Any, Dict, List, Optional
+
+from ..base_metric import BaseMetric, BaseMetricInputType
+
+
+class AggregatedMetric(BaseMetric[BaseMetricInputType]):
+    """
+    Combines multiple metric evaluators into a single aggregated score.
+
+    This metric assumes all sub-metrics can operate on the same input type.
+
+    Config:
+        - aggregator (str): 'average' or 'weighted_average'.
+        - metrics (List[BaseMetricInput]): A list of instantiated metric objects.
+        - weights (List[float]): Required if aggregator is 'weighted_average'.
+    """
+
+    SUPPORTED_AGGREGATORS = ["average", "weighted_average"]
+
+    @property
+    def metric_name(self) -> str:
+        return "aggregated_metric"
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None):
+        super().__init__(config)
+        self.aggregator = self.config.get("aggregator", "average")
+        self.metrics: List[BaseMetric] = self.config.get("metrics", [])
+        self.weights: List[float] = self.config.get("weights", [])
+
+        if self.aggregator not in self.SUPPORTED_AGGREGATORS:
+            raise ValueError(f"Unsupported aggregator: {self.aggregator}")
+        if not self.metrics:
+            raise ValueError(
+                "AggregatedMetric requires at least one metric in its config."
+            )
+        if not all(isinstance(m, BaseMetric) for m in self.metrics):
+            raise TypeError("All items in 'metrics' must be instances of BaseMetric.")
+        
+        # Explicitly set the input model based on the first sub-metric
+        self.input_model = self.metrics[0].input_model
+
+        if self.aggregator == "weighted_average":
+            if not self.weights or len(self.weights) != len(self.metrics):
+                raise ValueError(
+                    "Weights are required for 'weighted_average' and must match the number of metrics."
+                )
+
+    def _normalize_score(self, value: Any) -> float:
+        """Converts various score types to a float, clamping between 0 and 1."""
+        if isinstance(value, bool):
+            return 1.0 if value else 0.0
+        try:
+            float_value = float(value)
+            return max(0.0, min(1.0, float_value))
+        except (ValueError, TypeError):
+            return 0.0
+
+    def compute_one(self, inputs: BaseMetricInputType) -> Dict[str, Any]:
+        metric_scores = []
+        metric_details = {}
+
+        for metric in self.metrics:
+            try:
+                result_dict = metric.compute_one(inputs)
+                score = self._normalize_score(result_dict.get("output", 0.0))
+            except Exception:
+                # If a sub-metric fails, record a score of 0.0 for it
+                score = 0.0
+
+            metric_scores.append(score)
+            metric_details[metric.metric_name] = score
+
+        if not metric_scores:
+            return {"output": 0.0, "reason": "No metric scores were produced."}
+
+        if self.aggregator == "average":
+            aggregated_score = sum(metric_scores) / len(metric_scores)
+        else:  # weighted_average
+            weighted_sum = sum(w * s for w, s in zip(self.weights, metric_scores))
+            total_weight = sum(self.weights)
+            aggregated_score = weighted_sum / total_weight if total_weight > 0 else 0.0
+
+        reason = f"Aggregated score calculated using '{self.aggregator}'. Details: {json.dumps(metric_details)}"
+        return {"output": aggregated_score, "reason": reason}

fi/evals/metrics/heuristics/json_metrics.py

@@ -0,0 +1,87 @@
+import json
+from typing import Any, Dict
+import re
+
+# This would ideally be in a separate helper file
+from jsonschema import validate
+from jsonschema.exceptions import ValidationError as JsonSchemaValidationError
+
+from ..base_metric import BaseMetric
+from ...types import TextMetricInput, JsonMetricInput
+
+
+class ContainsJson(BaseMetric[TextMetricInput]):
+    """Checks if the response text contains a valid JSON object or array."""
+
+    @property
+    def metric_name(self) -> str:
+        return "contains_json"
+
+    def compute_one(self, inputs: TextMetricInput) -> Dict[str, Any]:
+        text = inputs.response.strip()
+        # Simple regex to find potential JSON candidates
+        json_candidates = re.findall(r"\{.*\}|\[.*\]", text, re.DOTALL)
+        for candidate in json_candidates:
+            try:
+                json.loads(candidate)
+                return {
+                    "output": 1.0,
+                    "reason": "A valid JSON entity was found in the response.",
+                }
+            except json.JSONDecodeError:
+                continue
+        return {"output": 0.0, "reason": "No valid JSON entity found in the response."}
+
+
+class IsJson(BaseMetric[TextMetricInput]):
+    """Checks if the entire response text is a single, valid JSON object."""
+
+    @property
+    def metric_name(self) -> str:
+        return "is_json"
+
+    def compute_one(self, inputs: TextMetricInput) -> Dict[str, Any]:
+        try:
+            json.loads(inputs.response)
+            return {"output": 1.0, "reason": "Response is a valid JSON object."}
+        except json.JSONDecodeError as e:
+            return {
+                "output": 0.0,
+                "reason": f"Response is not a valid JSON object: {e}",
+            }
+
+
+class JsonSchema(BaseMetric[JsonMetricInput]):
+    """Validates the `response` against a provided JSON schema."""
+
+    @property
+    def metric_name(self) -> str:
+        return "json_schema"
+
+    def compute_one(self, inputs: JsonMetricInput) -> Dict[str, Any]:
+        if not inputs.schema:
+            raise ValueError("JsonSchema metric requires 'schema' to be provided.")
+        try:
+            actual_data = (
+                json.loads(inputs.response)
+                if isinstance(inputs.response, str)
+                else inputs.response
+            )
+        except json.JSONDecodeError as e:
+            return {"output": 0.0, "reason": f"Actual JSON is invalid: {e}"}
+        try:
+            schema_data = (
+                json.loads(inputs.schema)
+                if isinstance(inputs.schema, str)
+                else inputs.schema
+            )
+        except json.JSONDecodeError as e:
+            return {"output": 0.0, "reason": f"Schema JSON is invalid: {e}"}
+        try:
+            validate(instance=actual_data, schema=schema_data)
+            return {"output": 1.0, "reason": "JSON conforms to the schema."}
+        except JsonSchemaValidationError as e:
+            return {
+                "output": 0.0,
+                "reason": f"JSON schema validation failed: {e.message}",
+            }