crprotocol 2.0.0__py3-none-any.whl

crp/provenance/hallucination_scorer.py

@@ -0,0 +1,320 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Hallucination Risk Scorer — per-claim composite risk assessment (§7.14.3).
+
+**WHY THIS EXISTS**
+
+An auditor reviewing AI output asks ONE question:
+
+    "How likely is it that THIS claim is a hallucination?"
+
+Currently they must mentally fuse:
+  - Attribution score (was it grounded?)
+  - Fidelity score (was the source distorted?)
+  - Entailment verdict (does NLI confirm semantic support?)
+  - Claim specificity (is this a precise claim that's dangerous if wrong?)
+
+This module fuses those four signals into ONE auditable risk score per
+claim, with a clear risk level (LOW / MEDIUM / HIGH / CRITICAL) and a
+list of human-readable risk factors explaining WHY.
+
+**RISK FORMULA**
+
+    risk = 1.0 - (w_a * attribution + w_f * fidelity + w_e * entailment + w_s * (1 - specificity))
+
+Where:
+  - attribution: top_score from DPE (0-1, higher = better sourced)
+  - fidelity: 1.0 if no distortions/fabrications for this claim, else degraded
+  - entailment: P(ENTAILED) from NLI (0-1, higher = semantically confirmed)
+  - specificity: density of specific entities in the claim (higher = riskier)
+  - w_a, w_f, w_e, w_s: configurable weights (default 0.30, 0.25, 0.30, 0.15)
+
+Risk levels:
+  - risk < 0.25 → LOW
+  - risk < 0.50 → MEDIUM
+  - risk < 0.75 → HIGH
+  - risk ≥ 0.75 → CRITICAL
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from ._types import (
+    AttributionType,
+    ClaimAttribution,
+    ClaimRiskAssessment,
+    ClaimType,
+    DistortionResult,
+    EntailmentLabel,
+    EntailmentResult,
+    FabricationResult,
+    FidelityReport,
+    HallucinationRisk,
+    HallucinationRiskReport,
+    ProvenanceConfig,
+)
+
+# ---------------------------------------------------------------------------
+# Claim specificity analysis
+# ---------------------------------------------------------------------------
+
+# Specific entities that make a claim "risky if wrong"
+_NUMBER_RE = re.compile(r"\b\d[\d,]*(?:\.\d+)?\s*%?\b")
+_DATE_RE = re.compile(
+    r"\b(?:(?:19|20)\d{2}|Q[1-4]\s+\d{4}|"
+    r"(?:January|February|March|April|May|June|July|August|"
+    r"September|October|November|December)\s+\d{4})\b",
+    re.IGNORECASE,
+)
+_PROPER_NOUN_RE = re.compile(r"\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\b")
+_MEASUREMENT_RE = re.compile(
+    r"\b\d+(?:\.\d+)?\s*(?:mg|kg|ml|cm|mm|km|lb|oz|GB|MB|TB|ms|MHz|GHz)\b",
+    re.IGNORECASE,
+)
+
+
+def compute_specificity(claim_text: str) -> float:
+    """Compute how specific a claim is (0.0=vague, 1.0=highly specific).
+
+    More specific claims are riskier if unsupported — "Revenue grew 23.4%
+    in Q3 2024 according to Deloitte" is far more dangerous wrong than
+    "Performance improved."
+
+    Specificity = min(1.0, entity_count / 5) — normalised density of
+    numbers, dates, proper nouns, and measurements.
+    """
+    entities = 0
+    entities += len(_NUMBER_RE.findall(claim_text))
+    entities += len(_DATE_RE.findall(claim_text))
+    entities += len(_PROPER_NOUN_RE.findall(claim_text))
+    entities += len(_MEASUREMENT_RE.findall(claim_text))
+    return min(1.0, entities / 5.0)
+
+
+# ---------------------------------------------------------------------------
+# Per-claim fidelity signal
+# ---------------------------------------------------------------------------
+
+
+def _claim_fidelity_signal(
+    claim_index: int,
+    fidelity: FidelityReport | None,
+) -> tuple[float, list[str]]:
+    """Compute fidelity signal for a single claim.
+
+    Returns (fidelity_score, risk_factors) where:
+      - 1.0 = no issues found
+      - <1.0 = distortions or fabrications detected
+    """
+    if fidelity is None:
+        return 1.0, []
+
+    score = 1.0
+    factors: list[str] = []
+
+    for d in fidelity.distortions:
+        if d.claim_index == claim_index:
+            score -= 0.20
+            factors.append(f"Distortion: {d.distortion_type.value} (sev={d.severity:.2f})")
+
+    for f in fidelity.fabrications:
+        if f.claim_index == claim_index:
+            score -= 0.15
+            factors.append(f"Fabrication: {f.entity_type.value} '{f.fabricated_entity}'")
+
+    return max(0.0, score), factors
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def score_hallucination_risk(
+    attributions: list[ClaimAttribution],
+    *,
+    fidelity: FidelityReport | None = None,
+    entailment_results: list[EntailmentResult] | None = None,
+    config: ProvenanceConfig | None = None,
+) -> HallucinationRiskReport:
+    """Score hallucination risk for every claim in the output.
+
+    Combines four independent signals per claim:
+      1. **Attribution** — how well-sourced is the claim?
+      2. **Fidelity** — did lexical checks find distortions?
+      3. **Entailment** — does NLI confirm semantic support?
+      4. **Specificity** — how specific (and thus risky) is the claim?
+
+    Args:
+        attributions: Scored claim attributions from the DPE pipeline.
+        fidelity: FidelityReport from the fidelity verification layer.
+        entailment_results: EntailmentResults from the entailment verifier.
+        config: ProvenanceConfig with risk weight configuration.
+
+    Returns:
+        HallucinationRiskReport with per-claim assessments and aggregates.
+    """
+    cfg = config or ProvenanceConfig()
+    if not cfg.risk_scoring_enabled:
+        return HallucinationRiskReport()
+
+    # Build entailment lookup by claim_index
+    ent_lookup: dict[int, EntailmentResult] = {}
+    if entailment_results:
+        for er in entailment_results:
+            ent_lookup[er.claim_index] = er
+
+    assessments: list[ClaimRiskAssessment] = []
+
+    for attr in attributions:
+        # Only score factual and hedge claims (the risky ones)
+        if attr.claim_type not in (ClaimType.FACTUAL_CLAIM, ClaimType.HEDGE):
+            assessments.append(ClaimRiskAssessment(
+                claim_index=attr.claim_index,
+                claim_text=attr.claim_text[:200],
+                risk_level=HallucinationRisk.LOW,
+                risk_score=0.0,
+                risk_factors=["Non-factual claim — low inherent risk"],
+            ))
+            continue
+
+        risk_factors: list[str] = []
+
+        # --- Signal 1: Attribution (higher = safer) ---
+        attribution_signal = attr.top_score
+        if attr.attribution_type == AttributionType.PARAMETRIC:
+            attribution_signal = max(0.0, attribution_signal - 0.30)
+            risk_factors.append("Parametric knowledge — not grounded in context")
+        elif attr.attribution_type == AttributionType.UNCERTAIN:
+            attribution_signal = 0.0
+            risk_factors.append("Uncertain attribution — source unknown")
+        elif attr.attribution_type == AttributionType.MIXED:
+            attribution_signal *= 0.80
+            risk_factors.append("Mixed attribution — partially parametric")
+
+        # --- Signal 2: Fidelity (higher = safer) ---
+        fidelity_signal, fidelity_factors = _claim_fidelity_signal(
+            attr.claim_index, fidelity,
+        )
+        risk_factors.extend(fidelity_factors)
+
+        # --- Signal 3: Entailment (higher = safer) ---
+        ent = ent_lookup.get(attr.claim_index)
+        if ent is not None:
+            entailment_signal = ent.entailment_score
+            if ent.label == EntailmentLabel.CONTRADICTION:
+                entailment_signal = 0.0
+                risk_factors.append(
+                    f"NLI CONTRADICTION (P={ent.contradiction_score:.2f}) — "
+                    f"claim semantically conflicts with source fact"
+                )
+            elif ent.label == EntailmentLabel.NEUTRAL:
+                entailment_signal = 0.3  # Partial credit for neutral
+                risk_factors.append("NLI neutral — claim not semantically supported")
+        else:
+            # No entailment data — use attribution as proxy
+            entailment_signal = attribution_signal * 0.5
+
+        # --- Signal 4: Specificity (higher = riskier) ---
+        specificity = compute_specificity(attr.claim_text)
+        if specificity > 0.6:
+            risk_factors.append(f"Highly specific claim (specificity={specificity:.2f})")
+
+        # --- Composite risk score ---
+        # Safety score = weighted combination of clean signals
+        #
+        # WEIGHT RATIONALE (G-3):
+        # - attribution (0.30): Primary grounding signal — whether the claim
+        #   can be traced to envelope facts. Highest weight because
+        #   ungrounded claims are the root cause of hallucinations.
+        # - entailment (0.30): Equal to attribution because semantic
+        #   verification catches meaning-level drift that attribution
+        #   scoring alone cannot (e.g., specificity loss, causation
+        #   inflation). Provides the ML-powered "second opinion".
+        # - fidelity (0.25): Lexical verification layer — catches number
+        #   changes, negation flips, qualifier drops. Slightly lower
+        #   weight because it's surface-level and the entailment layer
+        #   provides deeper semantic coverage.
+        # - specificity (0.15): Risk amplifier — highly specific claims
+        #   (numbers, dates, names) are more dangerous if wrong, but
+        #   specificity alone doesn't indicate hallucination.
+        #
+        safety = (
+            cfg.risk_weight_attribution * attribution_signal
+            + cfg.risk_weight_fidelity * fidelity_signal
+            + cfg.risk_weight_entailment * entailment_signal
+            + cfg.risk_weight_specificity * (1.0 - specificity)
+        )
+        risk_score = round(max(0.0, min(1.0, 1.0 - safety)), 4)
+
+        # CRITICAL SIGNAL OVERRIDE (G-3):
+        # If ANY key signal is catastrophically low (< 0.15), override
+        # risk to at least HIGH.  A single collapsed signal means the
+        # claim has a fundamental grounding/fidelity/semantic gap that
+        # the weighted average might mask.
+        _CRITICAL_FLOOR = 0.15
+        critical_signals = [
+            ("attribution", attribution_signal),
+            ("fidelity", fidelity_signal),
+            ("entailment", entailment_signal),
+        ]
+        for signal_name, signal_val in critical_signals:
+            if signal_val < _CRITICAL_FLOOR:
+                risk_score = max(risk_score, 0.50)  # Floor = HIGH
+                risk_factors.append(
+                    f"Critical signal override: {signal_name}={signal_val:.2f} < {_CRITICAL_FLOOR}"
+                )
+                break
+
+        # --- Risk level ---
+        if risk_score >= 0.75:
+            risk_level = HallucinationRisk.CRITICAL
+        elif risk_score >= 0.50:
+            risk_level = HallucinationRisk.HIGH
+        elif risk_score >= 0.25:
+            risk_level = HallucinationRisk.MEDIUM
+        else:
+            risk_level = HallucinationRisk.LOW
+
+        assessments.append(ClaimRiskAssessment(
+            claim_index=attr.claim_index,
+            claim_text=attr.claim_text[:200],
+            risk_level=risk_level,
+            risk_score=risk_score,
+            attribution_signal=round(attribution_signal, 4),
+            fidelity_signal=round(fidelity_signal, 4),
+            entailment_signal=round(entailment_signal, 4),
+            specificity_signal=round(specificity, 4),
+            risk_factors=risk_factors if risk_factors else ["No risk factors identified"],
+        ))
+
+    # --- Window-level aggregates ---
+    high_count = sum(1 for a in assessments if a.risk_level == HallucinationRisk.HIGH)
+    critical_count = sum(1 for a in assessments if a.risk_level == HallucinationRisk.CRITICAL)
+
+    factual_assessments = [
+        a for a in assessments if a.risk_score > 0.0
+    ]
+    mean_risk = (
+        sum(a.risk_score for a in factual_assessments) / len(factual_assessments)
+        if factual_assessments else 0.0
+    )
+
+    if critical_count > 0:
+        window_level = HallucinationRisk.CRITICAL
+    elif high_count > 0:
+        window_level = HallucinationRisk.HIGH
+    elif mean_risk >= 0.25:
+        window_level = HallucinationRisk.MEDIUM
+    else:
+        window_level = HallucinationRisk.LOW
+
+    return HallucinationRiskReport(
+        assessments=assessments,
+        high_risk_count=high_count,
+        critical_risk_count=critical_count,
+        mean_risk_score=round(mean_risk, 4),
+        window_risk_level=window_level,
+    )

crp/provenance/omission_analyzer.py

@@ -0,0 +1,106 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Omission Analyzer — detect when the model silently ignores important facts.
+
+15 high-priority facts went into the envelope.  The model used 4 and
+ignored 11.  If Fact #3 was "Product has a known safety defect" and the
+model never mentioned it — that is a **material omission**.
+
+This module identifies which envelope facts received NO attribution
+from any output claim and ranks them by importance (original packing
+score).  High-importance omissions are flagged for manual review.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from crp.envelope.packer import PackedFact
+
+from ._types import (
+    ClaimAttribution,
+    OmissionResult,
+    OmissionSeverity,
+)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def analyze_omissions(
+    attributions: list[ClaimAttribution],
+    packed_facts: Sequence[PackedFact],
+    *,
+    attribution_floor: float = 0.20,
+) -> list[OmissionResult]:
+    """Identify envelope facts that the model ignored.
+
+    For each packed fact, finds the maximum attribution score any output
+    claim gave it.  Facts with a maximum score below ``attribution_floor``
+    are considered omitted.
+
+    Results are sorted by fact relevance score descending — the most
+    important omissions first.
+
+    Args:
+        attributions: Scored claim attributions from the attribution scorer.
+        packed_facts: All facts that were packed into the envelope.
+        attribution_floor: Maximum composite score below which a fact
+                           is considered "not used" (default 0.20).
+
+    Returns:
+        List of OmissionResult sorted by importance (highest first).
+    """
+    if not packed_facts:
+        return []
+
+    # Build a map: fact_id → max composite score from any claim
+    max_scores: dict[str, float] = {pf.fact_id: 0.0 for pf in packed_facts}
+
+    for attr in attributions:
+        for fs in attr.attributed_facts:
+            if fs.fact_id in max_scores:
+                max_scores[fs.fact_id] = max(
+                    max_scores[fs.fact_id], fs.composite_score
+                )
+
+    # Determine relevance quartiles for severity classification
+    scores_list = sorted(
+        (pf.score for pf in packed_facts), reverse=True
+    )
+    n = len(scores_list)
+    q1_threshold = scores_list[n // 4] if n >= 4 else scores_list[0]
+    q2_threshold = scores_list[n // 2] if n >= 2 else scores_list[0]
+
+    results: list[OmissionResult] = []
+
+    for pf in packed_facts:
+        max_attr = max_scores.get(pf.fact_id, 0.0)
+
+        if max_attr >= attribution_floor:
+            continue  # Fact was adequately used
+
+        # Classify severity based on packing relevance score
+        if pf.score >= q1_threshold:
+            severity = OmissionSeverity.CRITICAL
+        elif pf.score >= q2_threshold:
+            severity = OmissionSeverity.HIGH
+        elif pf.score > 0.0:
+            severity = OmissionSeverity.MEDIUM
+        else:
+            severity = OmissionSeverity.LOW
+
+        results.append(OmissionResult(
+            fact_id=pf.fact_id,
+            fact_text_preview=pf.text[:120],
+            fact_relevance_score=round(pf.score, 4),
+            max_attribution_score=round(max_attr, 4),
+            severity=severity,
+        ))
+
+    # Sort by relevance (most important omissions first)
+    results.sort(key=lambda r: r.fact_relevance_score, reverse=True)
+
+    return results

crp/provenance/provenance_chain.py

@@ -0,0 +1,205 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Provenance Chain Builder — link claims → facts → windows → tasks (§7.14.3).
+
+Constructs full provenance chains from attribution results, tracing each claim
+back through the CRP pipeline:
+
+    Claim → attributed Fact → source Window → Envelope → original Task
+
+Also enriches FactScore objects with fact metadata (source_window_id,
+extraction_stage) when a WarmStateStore or fact lookup is available.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from crp.envelope.packer import PackedFact
+
+from ._types import (
+    AttributionType,
+    ClaimAttribution,
+    ProvenanceChain,
+    ProvenanceLink,
+)
+
+
+# ---------------------------------------------------------------------------
+# Fact metadata enrichment
+# ---------------------------------------------------------------------------
+
+
+def enrich_fact_metadata(
+    attributions: list[ClaimAttribution],
+    fact_metadata: dict[str, dict[str, Any]],
+) -> None:
+    """Enrich FactScore entries with fact provenance metadata (in-place).
+
+    Args:
+        attributions: List of claim attributions to enrich.
+        fact_metadata: Dict mapping fact_id → {
+            "source_window_id": str,
+            "extraction_stage": int,
+            "confidence": float,
+            ...
+        }
+    """
+    for attr in attributions:
+        for fs in attr.attributed_facts:
+            meta = fact_metadata.get(fs.fact_id, {})
+            fs.fact_source_window = meta.get("source_window_id", "")
+            fs.fact_extraction_stage = meta.get("extraction_stage", 0)
+
+
+# ---------------------------------------------------------------------------
+# Chain construction
+# ---------------------------------------------------------------------------
+
+
+def build_provenance_chain(
+    attribution: ClaimAttribution,
+    *,
+    session_id: str = "",
+    window_id: str = "",
+    envelope_saturation: float = 0.0,
+    envelope_facts_included: int = 0,
+    task_input_preview: str = "",
+) -> ProvenanceChain:
+    """Build a full provenance chain for a single claim attribution.
+
+    The chain traces from the claim back to its source:
+        Claim → Fact → Window → Envelope → Task
+
+    For PARAMETRIC claims (no supporting fact), the chain is shorter.
+
+    Args:
+        attribution: Scored claim attribution from attribution_scorer.
+        session_id: Current session ID.
+        window_id: Current window ID.
+        envelope_saturation: Envelope saturation ratio.
+        envelope_facts_included: Number of facts in the envelope.
+        task_input_preview: First 120 chars of the task input.
+
+    Returns:
+        ProvenanceChain with linked provenance levels.
+    """
+    links: list[ProvenanceLink] = []
+
+    # Level 1: The claim itself
+    links.append(ProvenanceLink(
+        level="claim",
+        label=f"Claim #{attribution.claim_index}: {attribution.claim_type.value}",
+        detail={
+            "claim_text": attribution.claim_text[:200],
+            "claim_type": attribution.claim_type.value,
+            "attribution_type": attribution.attribution_type.value,
+            "confidence": attribution.confidence,
+        },
+    ))
+
+    # Level 2: Attributed fact(s)
+    if attribution.attribution_type in (
+        AttributionType.CONTEXT_GROUNDED,
+        AttributionType.MIXED,
+    ) and attribution.attributed_facts:
+        top_fact = attribution.attributed_facts[0]
+        links.append(ProvenanceLink(
+            level="fact",
+            label=f"Fact {top_fact.fact_id[:8]}... (score: {top_fact.composite_score:.2f})",
+            detail={
+                "fact_id": top_fact.fact_id,
+                "fact_preview": top_fact.fact_text_preview,
+                "composite_score": top_fact.composite_score,
+                "semantic_similarity": top_fact.semantic_similarity,
+                "lexical_overlap": top_fact.lexical_overlap,
+                "source_window": top_fact.fact_source_window,
+                "extraction_stage": top_fact.fact_extraction_stage,
+            },
+        ))
+
+        # Level 3: Source window (if known)
+        if top_fact.fact_source_window:
+            links.append(ProvenanceLink(
+                level="window",
+                label=f"Window {top_fact.fact_source_window[:8]}... (stage {top_fact.fact_extraction_stage})",
+                detail={
+                    "window_id": top_fact.fact_source_window,
+                    "extraction_stage": top_fact.fact_extraction_stage,
+                },
+            ))
+    elif attribution.attribution_type == AttributionType.PARAMETRIC:
+        links.append(ProvenanceLink(
+            level="fact",
+            label="No supporting context fact (likely parametric knowledge)",
+            detail={
+                "attribution_type": "PARAMETRIC",
+                "top_score": attribution.top_score,
+                "note": "Claim appears to originate from model training data, "
+                        "not from provided context.",
+            },
+        ))
+
+    # Level 4: Envelope context
+    links.append(ProvenanceLink(
+        level="envelope",
+        label=f"Envelope ({envelope_facts_included} facts, "
+              f"saturation: {envelope_saturation:.0%})",
+        detail={
+            "window_id": window_id,
+            "facts_included": envelope_facts_included,
+            "saturation": round(envelope_saturation, 4),
+        },
+    ))
+
+    # Level 5: Task input
+    links.append(ProvenanceLink(
+        level="task",
+        label=f"Session {session_id[:8]}..." if session_id else "Session",
+        detail={
+            "session_id": session_id,
+            "task_preview": task_input_preview[:120],
+        },
+    ))
+
+    return ProvenanceChain(
+        claim_text=attribution.claim_text[:200],
+        claim_index=attribution.claim_index,
+        attribution_type=attribution.attribution_type,
+        links=links,
+    )
+
+
+def build_all_chains(
+    attributions: list[ClaimAttribution],
+    *,
+    session_id: str = "",
+    window_id: str = "",
+    envelope_saturation: float = 0.0,
+    envelope_facts_included: int = 0,
+    task_input_preview: str = "",
+) -> list[ProvenanceChain]:
+    """Build provenance chains for all attributed claims.
+
+    Args:
+        attributions: All claim attributions from scorer.
+        session_id: Current session ID.
+        window_id: Current window ID.
+        envelope_saturation: Envelope saturation ratio.
+        envelope_facts_included: Facts in envelope.
+        task_input_preview: First 120 chars of task input.
+
+    Returns:
+        List of ProvenanceChain objects (one per attribution).
+    """
+    return [
+        build_provenance_chain(
+            attr,
+            session_id=session_id,
+            window_id=window_id,
+            envelope_saturation=envelope_saturation,
+            envelope_facts_included=envelope_facts_included,
+            task_input_preview=task_input_preview,
+        )
+        for attr in attributions
+    ]