crprotocol 2.0.0__py3-none-any.whl

crp/provenance/_embeddings.py

@@ -0,0 +1,97 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Shared semantic embedding module for DPE components (§7.14.3).
+
+Provides lazy-loaded sentence-transformer embeddings used by:
+  - attribution_scorer (G-1): real semantic similarity vs hash-BOW
+  - entailment_verifier (P-1): ML-driven fallback when NLI unavailable
+  - distortion_detector (P-3): semantic drift detection
+
+The model (all-MiniLM-L6-v2, ~80 MB, 384-dim, CPU-only) is loaded
+once and shared across all components to avoid duplicate memory usage.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Module-level model cache (lazy singleton)
+# ---------------------------------------------------------------------------
+
+_model: Any = None
+_model_load_failed: bool = False
+_DEFAULT_MODEL = "all-MiniLM-L6-v2"
+
+
+def get_embedder(*, model_name: str = _DEFAULT_MODEL) -> Any:
+    """Lazy-load the SentenceTransformer model (singleton).
+
+    Returns the model object or None if loading fails.
+    """
+    global _model, _model_load_failed  # noqa: PLW0603
+
+    if _model_load_failed:
+        return None
+
+    if _model is not None:
+        return _model
+
+    try:
+        from sentence_transformers import SentenceTransformer  # type: ignore[import-untyped]
+        logger.info("Loading embedding model: %s", model_name)
+        _model = SentenceTransformer(model_name)
+        return _model
+    except Exception as exc:
+        logger.warning(
+            "Embedding model unavailable (%s), semantic features degraded: %s",
+            model_name, exc,
+        )
+        _model_load_failed = True
+        return None
+
+
+def encode_texts(
+    texts: list[str],
+    *,
+    _model_override: Any = None,
+) -> list[list[float]] | None:
+    """Encode texts into dense embeddings.
+
+    Args:
+        texts: List of strings to encode.
+        _model_override: Injected model for testing (skips singleton).
+
+    Returns:
+        List of embedding vectors (as lists of floats), or None if
+        the model is unavailable.
+    """
+    model = _model_override or get_embedder()
+    if model is None:
+        return None
+
+    try:
+        embeddings = model.encode(texts, convert_to_numpy=True)
+        return [emb.tolist() for emb in embeddings]
+    except Exception as exc:
+        logger.warning("Embedding encode failed: %s", exc)
+        return None
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    """Compute cosine similarity between two vectors."""
+    dot = sum(x * y for x, y in zip(a, b))
+    norm_a = math.sqrt(sum(x * x for x in a)) or 1e-12
+    norm_b = math.sqrt(sum(x * x for x in b)) or 1e-12
+    return dot / (norm_a * norm_b)
+
+
+def reset_cache() -> None:
+    """Reset the module-level model cache (for testing)."""
+    global _model, _model_load_failed  # noqa: PLW0603
+    _model = None
+    _model_load_failed = False

crp/provenance/_types.py

@@ -0,0 +1,378 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Decision Provenance Engine — data types (§7.14.3).
+
+Dataclasses for claim attribution, fact scoring, provenance chains,
+and provenance reports used by the DPE pipeline.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# Claim classification
+# ---------------------------------------------------------------------------
+
+
+class ClaimType(str, Enum):
+    """Classification of individual sentences/claims in LLM output."""
+
+    FACTUAL_CLAIM = "FACTUAL_CLAIM"     # Verifiable factual assertion
+    OPINION = "OPINION"                  # Subjective view or judgment
+    PROCEDURAL = "PROCEDURAL"            # Action or instruction
+    HEDGE = "HEDGE"                      # Qualified/uncertain statement
+    CONNECTIVE = "CONNECTIVE"            # Structural/transitional text
+
+
+class AttributionType(str, Enum):
+    """How a claim maps to its knowledge source."""
+
+    CONTEXT_GROUNDED = "CONTEXT_GROUNDED"   # Supported by envelope fact(s)
+    PARAMETRIC = "PARAMETRIC"               # Likely from model training data
+    MIXED = "MIXED"                         # Partial context + parametric
+    UNCERTAIN = "UNCERTAIN"                 # Low-confidence attribution
+
+
+# ---------------------------------------------------------------------------
+# Fidelity verification — did the model FAITHFULLY represent its sources?
+# ---------------------------------------------------------------------------
+
+
+class DistortionType(str, Enum):
+    """How the model distorted a source fact in its output."""
+
+    NUMBER_CHANGED = "NUMBER_CHANGED"           # 10% → 15%
+    NEGATION_FLIP = "NEGATION_FLIP"             # "is safe" → "is not safe"
+    QUALIFIER_DROPPED = "QUALIFIER_DROPPED"     # "approximately 10" → "10"
+    QUALIFIER_ADDED = "QUALIFIER_ADDED"         # "10" → "always 10"
+    SCOPE_CHANGED = "SCOPE_CHANGED"             # "in Q3" → "annually"
+    ENTITY_SUBSTITUTED = "ENTITY_SUBSTITUTED"   # "Company A" → "Company B"
+    SEMANTIC_DRIFT = "SEMANTIC_DRIFT"           # Meaning-level deviation despite lexical similarity
+
+
+class FabricationType(str, Enum):
+    """Category of fabricated entity in a claim."""
+
+    NUMBER = "NUMBER"               # Invented number not in any fact
+    PERCENTAGE = "PERCENTAGE"       # Invented percentage
+    DATE = "DATE"                   # Invented date/year
+    PROPER_NOUN = "PROPER_NOUN"     # Invented name/entity
+    CITATION = "CITATION"           # Invented citation/reference
+
+
+class OmissionSeverity(str, Enum):
+    """How important the omitted fact was."""
+
+    CRITICAL = "CRITICAL"       # Top-quartile relevance, omitted entirely
+    HIGH = "HIGH"               # High relevance, omitted
+    MEDIUM = "MEDIUM"           # Medium relevance, omitted
+    LOW = "LOW"                 # Low relevance, omitted (expected)
+
+
+# ---------------------------------------------------------------------------
+# Scoring results
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FactScore:
+    """Attribution score between a single claim and a single envelope fact."""
+
+    fact_id: str = ""
+    fact_text_preview: str = ""         # First 120 chars of fact text
+    semantic_similarity: float = 0.0    # Bag-of-words cosine similarity
+    lexical_overlap: float = 0.0        # N-gram token overlap ratio
+    composite_score: float = 0.0        # Weighted combination
+    fact_source_window: str = ""        # Which window created this fact
+    fact_extraction_stage: int = 0      # Which pipeline stage (1-6)
+
+
+@dataclass
+class ClaimAttribution:
+    """Attribution result for a single claim in the LLM output."""
+
+    claim_text: str = ""
+    claim_index: int = 0                           # Position in output (0-based)
+    claim_type: ClaimType = ClaimType.CONNECTIVE
+    attributed_facts: list[FactScore] = field(default_factory=list)
+    top_score: float = 0.0                         # Highest composite score
+    attribution_type: AttributionType = AttributionType.UNCERTAIN
+    confidence: float = 0.0                        # Overall attribution confidence
+
+
+# ---------------------------------------------------------------------------
+# Provenance chain
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ProvenanceLink:
+    """Single link in a provenance chain — traces from claim → source."""
+
+    level: str = ""         # "claim", "fact", "window", "envelope", "task"
+    label: str = ""         # Human-readable label for this link
+    detail: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ProvenanceChain:
+    """Full provenance chain for one claim — linked list from output to input."""
+
+    claim_text: str = ""
+    claim_index: int = 0
+    attribution_type: AttributionType = AttributionType.UNCERTAIN
+    links: list[ProvenanceLink] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Provenance report
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ProvenanceReport:
+    """Complete provenance report for a single dispatch window."""
+
+    session_id: str = ""
+    window_id: str = ""
+    timestamp: float = 0.0
+
+    # Counts
+    total_claims: int = 0
+    factual_claims: int = 0
+    opinion_claims: int = 0
+    procedural_claims: int = 0
+    hedge_claims: int = 0
+    connective_claims: int = 0
+
+    # Attribution summary
+    context_grounded_count: int = 0
+    parametric_count: int = 0
+    mixed_count: int = 0
+    uncertain_count: int = 0
+    grounding_ratio: float = 0.0       # context_grounded / factual_claims
+
+    # Payload
+    attributions: list[ClaimAttribution] = field(default_factory=list)
+    chains: list[ProvenanceChain] = field(default_factory=list)
+
+    # Integrity
+    chain_verified: bool = False
+    output_token_count: int = 0
+    envelope_facts_count: int = 0
+
+    # Fidelity verification (None until fidelity checks run)
+    fidelity: FidelityReport | None = None
+
+    # Semantic entailment verification (None until entailment runs)
+    entailment_results: list[EntailmentResult] = field(default_factory=list)
+
+    # Hallucination risk assessment (None until risk scoring runs)
+    risk_report: HallucinationRiskReport | None = None
+
+
+# ---------------------------------------------------------------------------
+# Fidelity verification results
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DistortionResult:
+    """A specific distortion found between a grounded claim and its source fact."""
+
+    claim_index: int = 0
+    claim_text: str = ""
+    source_fact_id: str = ""
+    source_fact_preview: str = ""
+    distortion_type: DistortionType = DistortionType.NUMBER_CHANGED
+    severity: float = 0.0          # 0.0-1.0
+    detail: str = ""               # Human-readable explanation
+    claim_value: str = ""          # The value in the claim
+    fact_value: str = ""           # The value in the source fact
+
+
+@dataclass
+class FabricationResult:
+    """A specific fabrication found in a claim — an entity not in any source fact."""
+
+    claim_index: int = 0
+    claim_text: str = ""
+    fabricated_entity: str = ""
+    entity_type: FabricationType = FabricationType.NUMBER
+    severity: float = 0.0         # 0.0-1.0
+    detail: str = ""
+
+
+@dataclass
+class OmissionResult:
+    """An envelope fact that the model ignored entirely."""
+
+    fact_id: str = ""
+    fact_text_preview: str = ""
+    fact_relevance_score: float = 0.0    # Original packing score
+    max_attribution_score: float = 0.0   # Highest score any claim gave this fact
+    severity: OmissionSeverity = OmissionSeverity.LOW
+
+
+@dataclass
+class ContradictionResult:
+    """Two claims that contradict each other."""
+
+    claim_a_index: int = 0
+    claim_a_text: str = ""
+    claim_b_index: int = 0
+    claim_b_text: str = ""
+    contradiction_type: str = ""     # "NEGATION" | "NUMBER_CONFLICT" | "SEMANTIC"
+    severity: float = 0.0           # 0.0-1.0
+    detail: str = ""
+
+
+@dataclass
+class FidelityReport:
+    """Complete fidelity verification results for a dispatch window.
+
+    Answers: "Given source attribution, did the model faithfully represent
+    the sources, or did it distort, fabricate, omit, or contradict?"
+    """
+
+    distortions: list[DistortionResult] = field(default_factory=list)
+    fabrications: list[FabricationResult] = field(default_factory=list)
+    omissions: list[OmissionResult] = field(default_factory=list)
+    contradictions: list[ContradictionResult] = field(default_factory=list)
+
+    # Aggregate counts
+    distortion_count: int = 0
+    fabrication_count: int = 0
+    critical_omission_count: int = 0
+    contradiction_count: int = 0
+
+    # Composite fidelity score (1.0 = perfect fidelity, 0.0 = severe issues)
+    fidelity_score: float = 1.0
+
+
+# ---------------------------------------------------------------------------
+# Semantic Entailment — ML-powered claim↔fact verification
+# ---------------------------------------------------------------------------
+
+
+class EntailmentLabel(str, Enum):
+    """NLI classification of a claim against its source fact."""
+
+    ENTAILED = "ENTAILED"               # Claim logically follows from fact
+    CONTRADICTION = "CONTRADICTION"     # Claim contradicts the fact
+    NEUTRAL = "NEUTRAL"                 # Claim is unrelated to the fact
+
+
+@dataclass
+class EntailmentResult:
+    """Semantic entailment verdict for a single claim↔fact pair.
+
+    Uses Natural Language Inference (NLI) to determine whether a claim
+    is *semantically* supported by its attributed source fact — beyond
+    lexical overlap.
+    """
+
+    claim_index: int = 0
+    claim_text: str = ""
+    fact_id: str = ""
+    fact_text_preview: str = ""
+    label: EntailmentLabel = EntailmentLabel.NEUTRAL
+    confidence: float = 0.0            # P(predicted_label)
+    entailment_score: float = 0.0      # P(entailed)
+    contradiction_score: float = 0.0   # P(contradiction)
+    neutral_score: float = 0.0         # P(neutral)
+    used_model: bool = False           # True if NLI model ran; False if heuristic
+
+
+# ---------------------------------------------------------------------------
+# Hallucination Risk — composite per-claim risk assessment
+# ---------------------------------------------------------------------------
+
+
+class HallucinationRisk(str, Enum):
+    """Per-claim hallucination risk level."""
+
+    LOW = "LOW"                 # Well-sourced, semantically faithful
+    MEDIUM = "MEDIUM"           # Partially sourced or minor fidelity issues
+    HIGH = "HIGH"               # Poorly sourced or semantic mismatch
+    CRITICAL = "CRITICAL"       # Contradicts source or fabricated content
+
+
+@dataclass
+class ClaimRiskAssessment:
+    """Hallucination risk assessment for a single claim.
+
+    Aggregates four independent signals into one auditable risk score:
+      1. Attribution signal — how well-sourced is this claim?
+      2. Fidelity signal — did lexical checks find distortions?
+      3. Entailment signal — does NLI confirm semantic support?
+      4. Specificity signal — how specific (and thus risky) is the claim?
+    """
+
+    claim_index: int = 0
+    claim_text: str = ""
+    risk_level: HallucinationRisk = HallucinationRisk.LOW
+    risk_score: float = 0.0            # 0.0=safe, 1.0=critical
+    # Individual signals (all 0.0-1.0; higher = safer)
+    attribution_signal: float = 0.0
+    fidelity_signal: float = 1.0
+    entailment_signal: float = 0.0
+    specificity_signal: float = 0.0    # Higher = more specific = riskier
+    risk_factors: list[str] = field(default_factory=list)
+
+
+@dataclass
+class HallucinationRiskReport:
+    """Window-level hallucination risk report.
+
+    Answers: \"For each claim, how likely is it that the model hallucinated,
+    and what is the overall risk profile of this output?\"
+    """
+
+    assessments: list[ClaimRiskAssessment] = field(default_factory=list)
+    high_risk_count: int = 0
+    critical_risk_count: int = 0
+    mean_risk_score: float = 0.0
+    window_risk_level: HallucinationRisk = HallucinationRisk.LOW
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class ProvenanceConfig:
+    """Configuration for the Decision Provenance Engine."""
+
+    enabled: bool = True
+
+    # Claim detection
+    min_claim_length: int = 10          # Skip very short fragments
+    max_claims_per_output: int = 50     # Safety limit
+
+    # Attribution scoring
+    similarity_threshold: float = 0.50  # Below this → PARAMETRIC
+    mixed_threshold: float = 0.35       # Between mixed and parametric
+    lexical_weight: float = 0.40        # Weight for lexical overlap
+    semantic_weight: float = 0.60       # Weight for semantic similarity
+
+    # Report generation
+    generate_report: bool = True
+    fact_preview_length: int = 120      # Chars of fact text in previews
+
+    # Semantic entailment
+    entailment_enabled: bool = True
+    entailment_model: str = "cross-encoder/nli-MiniLM2-L6-H768"
+    entailment_contradiction_threshold: float = 0.70  # P(contradiction) above this → flag
+
+    # Hallucination risk scoring
+    risk_scoring_enabled: bool = True
+    risk_weight_attribution: float = 0.30
+    risk_weight_fidelity: float = 0.25
+    risk_weight_entailment: float = 0.30
+    risk_weight_specificity: float = 0.15