dprovenancekit 0.1.0__py3-none-any.whl

dprovenancekit/__init__.py

@@ -0,0 +1,212 @@
+"""DProvenanceKit — reasoning observability and regression testing for AI systems.
+
+A Python port of the Swift DProvenanceKit. Run → Record → Query → Diff → Detect
+Regressions.
+
+    kit = DProvenanceKit(MyEvent)
+    store = InMemoryTraceStore()
+    with kit.run(context_id="case-1", store=store):
+        kit.record(MyEvent.document_evaluated("DocA", 0.95))
+        kit.record(MyEvent.conflict_detected("timeline_inconsistency"))
+
+    runs = store.query_runs(
+        TraceQueryDSL().requiring_step("conflictDetected").missing_step("documentEvaluated")
+    )
+"""
+
+from __future__ import annotations
+
+# Core event model
+from .priority import TracePriority
+from .event import (
+    TraceableEvent,
+    TraceEvent,
+    TraceEventRow,
+    RunRow,
+    AnyTraceableEvent,
+)
+from .edge import TraceEdge, TraceEdgeType
+from .graph import TraceGraph, TraceExplanation
+from .drop_stats import TraceDropStats, TraceDropTally
+from .config import BufferCapacity, EvictionPolicy, OfflineConfig
+
+# Recording + context
+from .context import TraceContext, AnyActiveTraceRun
+from .kit import DProvenanceKit, ActiveTraceRun
+
+# Query
+from .query import (
+    TraceRun,
+    TraceQueryDSL,
+    TraceQueryNode,
+    TraceQueryPlanner,
+    TraceQueryCompiler,
+    CompiledSQLQuery,
+    IndexConstraint,
+)
+
+# Buffer + stores
+from .write_buffer import TraceWriteBuffer
+from .store import (
+    TraceStore,
+    InMemoryTraceStore,
+    TraceError,
+    NodeNotFoundError,
+    NotImplementedTraceError,
+)
+from .sqlite_store import SQLiteTraceStore, SQLiteConnection, SQLiteWriter
+from .raw_store import RawTraceStore, RawTraceRun, RawTraceEvent
+from .cloud_store import (
+    CloudTraceStore,
+    CloudWriter,
+    CloudWriterError,
+    FlushTimedOut,
+    CloudTraceStoreError,
+    UnsupportedSchemaError,
+    ServerError,
+    default_transport,
+)
+from .circuit_breaker import CircuitBreaker, CircuitState
+
+# Live querying + anomalies
+from .live_engine import LiveTraceQueryEngine, TraceQuerySubscription, QueryState
+from .anomaly import Anomaly, AnomalyRule, AnomalyDetector, LiveAnomalySubscription
+
+# Diff + replay
+from .diff import TraceDiffEngine, TraceDiffResult, Change, ChangeKind
+from .replay import (
+    TraceReplayEngine,
+    ReplaySnapshot,
+    ReplayEvent,
+    ReplaySource,
+    ReplayManifest,
+    ReplaySnapshotMetadata,
+    SpanNode,
+    SequenceGap,
+)
+from .snapshot_diff import (
+    SnapshotDiffEngine,
+    SnapshotDiffResult,
+    SpanChange,
+    SpanChangeKind,
+    EventChange,
+    EventChangeKind,
+    DivergencePoint,
+    DiffSummary,
+)
+from .render_hints import RenderHints, DiffPresentationMode
+
+# Alignment
+from .alignment_config import (
+    AlignmentConfiguration,
+    AlignmentProfile,
+    AlignmentMode,
+    AlignmentStrategy,
+    AnyEquivalenceEvaluator,
+)
+from .alignment_engine import TraceAlignmentEngine, VerificationCaptureMode
+from .alignment_models import (
+    TraceAlignmentResult,
+    EventAlignment,
+    AlignmentState,
+    AlignmentStateKind,
+    AlignmentStrength,
+    AlignmentStrengthCategory,
+    AmbiguousMatch,
+    AlignmentExplanation,
+    HeuristicEvidence,
+    HeuristicEvidenceCategory,
+    RegressionRisk,
+    RegressionLevel,
+    AlignmentFinding,
+    AlignmentFindingKind,
+    DecisionTimelineEntry,
+)
+from .alignment_meta import AlignmentMetaEvent, MetaEventKind
+from .alignment_contract import AlignmentExecutionContract
+from .alignment_evidence import (
+    AlignmentBinding,
+    BindingDecision,
+    EquivalenceDecisionRecord,
+    EquivalenceReason,
+    InterpretationStep,
+    AlignmentEvidence,
+    AlignmentEvidenceCollector,
+    NullEvidenceCollector,
+    EvidenceCollector,
+    VerificationArtifacts,
+)
+from .alignment_semantics import EquivalenceDecision, DefaultEquivalenceModel
+from .alignment_matcher import DefaultTraceMatcher
+from .alignment_interpreter import DefaultAlignmentInterpreter
+from .alignment_findings import AlignmentFindingsExtractor
+from .alignment_narrative import AlignmentNarrativeCompiler
+from .alignment_render import AlignmentRenderNode, RenderHint, render_models
+from .alignment_snapshot import (
+    AlignmentSnapshot,
+    AlignmentSnapshotValidator,
+    DriftToleranceMode,
+    SnapshotValidationError,
+)
+
+# Verification
+from .verification import (
+    FidelityVector,
+    FormalizationMap,
+    DefaultFormalizationMapBuilder,
+    CoverageInvariant,
+    CompletenessInvariant,
+    CausalOrderingInvariant,
+    NoHallucinationInvariant,
+    ExplainabilityAuditor,
+    TraceGraphValidator,
+    TraceGraphProvenanceValidator,
+    TraceGraphValidationError,
+    StructuralCycleDetected,
+    SelfReferentialEdge,
+)
+
+# Benchmark + corpus
+from .benchmark import (
+    BenchmarkRunner,
+    BenchmarkReport,
+    BenchmarkCase,
+    BenchmarkCaseResult,
+    BenchmarkDataset,
+    BenchmarkStabilityReport,
+    BenchmarkDeltaReport,
+    CategoryMetrics,
+    CategoryDeltaMetrics,
+    CausalRank,
+    ExpectedFinding,
+    DeterministicBoundary,
+    EnvironmentContext,
+    BenchmarkFailureDiagnoser,
+    DiagnosedFailure,
+    FailureCause,
+    FailureSeverityProfile,
+    SignalFailure,
+    ModelFailure,
+    SearchFailure,
+    DataFailure,
+)
+from .corpus import DProvenanceCorpus
+from .perturbation import EvaluationPerturbationLayer, PerturbationMode
+
+# View models (pure logic)
+from .viewmodel import SpanViewModel, FlattenedSpanNode, flatten_span_tree
+
+# Regression-gate test helper
+from .testing import (
+    RegressionGate,
+    RegressionReport,
+    RegressionError,
+    assert_no_regression,
+    exact_equality_evaluator,
+    run_fingerprint,
+)
+
+# Framework-agnostic instrumentation (decorators / context manager)
+from .instrument import TracedEvent, traced, traced_run, record_event
+
+__version__ = "0.1.0"

dprovenancekit/alignment_config.py

@@ -0,0 +1,182 @@
+"""Alignment profiles, the pluggable equivalence evaluator, and the configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Callable
+
+from .alignment_contract import AlignmentExecutionContract
+
+
+class AlignmentMode(Enum):
+    LINEAR = "linear"
+    SPAN_AWARE = "spanAware"
+    FULL_GRAPH = "fullGraph"
+
+
+class AlignmentStrategy(Enum):
+    STRICT_AUDIT = "strict_audit"
+    DEVELOPER_DEBUG = "developer_debug"
+    SEMANTIC_EXPLORATION = "semantic_exploration"
+
+
+@dataclass(frozen=True)
+class AlignmentProfile:
+    strategy: AlignmentStrategy
+    version: int
+    type_weight: float
+    payload_weight: float
+    structural_weight: float
+    temporal_weight: float
+    semantic_threshold: float
+    max_ambiguous_candidates: int
+    ambiguity_delta_threshold: float
+    alignment_mode: AlignmentMode
+
+
+AlignmentProfile.strict_audit_v1 = AlignmentProfile(  # type: ignore[attr-defined]
+    strategy=AlignmentStrategy.STRICT_AUDIT,
+    version=1,
+    type_weight=0.5,
+    payload_weight=0.5,
+    structural_weight=0.0,
+    temporal_weight=0.0,
+    semantic_threshold=0.99,
+    max_ambiguous_candidates=1,
+    ambiguity_delta_threshold=0.0,
+    alignment_mode=AlignmentMode.LINEAR,
+)
+
+AlignmentProfile.developer_debug_v1 = AlignmentProfile(  # type: ignore[attr-defined]
+    strategy=AlignmentStrategy.DEVELOPER_DEBUG,
+    version=1,
+    type_weight=0.4,
+    payload_weight=0.4,
+    structural_weight=0.15,
+    temporal_weight=0.05,
+    semantic_threshold=0.75,
+    max_ambiguous_candidates=3,
+    ambiguity_delta_threshold=0.10,
+    alignment_mode=AlignmentMode.SPAN_AWARE,
+)
+
+
+@dataclass(frozen=True)
+class AnyEquivalenceEvaluator:
+    """A type-erased equivalence evaluator. ``evaluator`` scores two payloads in 0..1;
+    ``ambiguity_threshold_fn`` returns the per-event ambiguity floor (default 0.4)."""
+
+    evaluator_identifier: str
+    evaluator: Callable
+    ambiguity_threshold_fn: Callable = None  # type: ignore[assignment]
+
+    def __post_init__(self):
+        if self.ambiguity_threshold_fn is None:
+            object.__setattr__(self, "ambiguity_threshold_fn", lambda _e: 0.4)
+
+    def evaluate_similarity(self, base, comparison) -> float:
+        return self.evaluator(base, comparison)
+
+    def ambiguity_threshold(self, event) -> float:
+        return self.ambiguity_threshold_fn(event)
+
+
+@dataclass(frozen=True)
+class AlignmentConfiguration:
+    profile: AlignmentProfile
+    equivalence_evaluator: AnyEquivalenceEvaluator
+    engine_version: str = "1.0.0"
+
+    @property
+    def profile_hash(self) -> str:
+        return AlignmentExecutionContract.compute_profile_hash(
+            profile=self.profile,
+            evaluator_identifier=self.equivalence_evaluator.evaluator_identifier,
+            engine_version=self.engine_version,
+        )
+
+    def score_match(self, base, comp):
+        """Weighted heuristic score over type / payload / structure / temporal locality.
+
+        Returns ``(score, AlignmentExplanation)``.
+        """
+        from .alignment_models import (
+            AlignmentExplanation,
+            HeuristicEvidence,
+            HeuristicEvidenceCategory,
+        )
+
+        profile = self.profile
+        score = 0.0
+        evidence = []
+        primary_reason = ""
+
+        # 1. Type match.
+        type_sim = 1.0 if base.payload.type_identifier == comp.payload.type_identifier else 0.0
+        type_contribution = type_sim * profile.type_weight
+        score += type_contribution
+        if type_contribution > 0:
+            evidence.append(
+                HeuristicEvidence(
+                    HeuristicEvidenceCategory.TYPE_MATCH,
+                    type_contribution,
+                    f"Type match ({base.payload.type_identifier})",
+                )
+            )
+            primary_reason = "Exact Type Match"
+
+        # 2. Payload similarity.
+        payload_sim = self.equivalence_evaluator.evaluate_similarity(base.payload, comp.payload)
+        payload_contribution = payload_sim * profile.payload_weight
+        score += payload_contribution
+        if payload_contribution > 0:
+            evidence.append(
+                HeuristicEvidence(
+                    HeuristicEvidenceCategory.PAYLOAD_SIMILARITY,
+                    payload_contribution,
+                    f"Semantic equivalence score: {payload_sim:.2f}",
+                )
+            )
+            if not primary_reason:
+                primary_reason = "Semantic Payload Match"
+
+        # 3. Structural context (span awareness).
+        structural_sim = 0.0
+        if profile.alignment_mode != AlignmentMode.LINEAR:
+            if base.parent_span_id == comp.parent_span_id and base.parent_span_id is not None:
+                structural_sim = 1.0
+            elif base.parent_span_id is None and comp.parent_span_id is None:
+                structural_sim = 1.0
+        structural_contribution = structural_sim * profile.structural_weight
+        score += structural_contribution
+        if structural_contribution > 0:
+            evidence.append(
+                HeuristicEvidence(
+                    HeuristicEvidenceCategory.STRUCTURAL_CONTEXT,
+                    structural_contribution,
+                    "Parent span matched",
+                )
+            )
+
+        # 4. Temporal locality (rough heuristic on sequence index distance).
+        seq_diff = abs(int(base.sequence) - int(comp.sequence))
+        temp_sim = max(0.0, 1.0 - (seq_diff / 10.0))
+        temp_contribution = temp_sim * profile.temporal_weight
+        score += temp_contribution
+        if temp_contribution > 0:
+            evidence.append(
+                HeuristicEvidence(
+                    HeuristicEvidenceCategory.TEMPORAL_LOCALITY,
+                    temp_contribution,
+                    f"Temporal locality (+/-{seq_diff} events)",
+                )
+            )
+
+        if not primary_reason:
+            primary_reason = "Low Confidence Match"
+
+        explanation = AlignmentExplanation(
+            primary_reason=primary_reason, final_score=score, ranked_evidence=evidence
+        )
+        return score, explanation

dprovenancekit/alignment_contract.py

@@ -0,0 +1,73 @@
+"""Canonical ordering, normalization, and the profile hash — a frozen execution spec.
+
+Strips out non-deterministic ordering flicker so two runs of the engine over the same
+inputs produce byte-identical render output (and therefore the same snapshot hash).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from typing import List
+
+from .alignment_models import (
+    AmbiguousMatch,
+    EventAlignment,
+    HeuristicEvidence,
+    sort_evidence,
+)
+
+CONTRACT_VERSION = "1.0.0"
+
+
+class AlignmentExecutionContract:
+    contract_version = CONTRACT_VERSION
+
+    @staticmethod
+    def canonical_sort_evidence(evidence: List[HeuristicEvidence]) -> List[HeuristicEvidence]:
+        return sort_evidence(evidence)
+
+    @staticmethod
+    def canonical_sort_ambiguity(ambiguity: List[AmbiguousMatch]) -> List[AmbiguousMatch]:
+        return sorted(ambiguity, key=lambda a: (-a.strength, a.event.sequence))
+
+    @staticmethod
+    def canonical_sort_alignments(alignments: List[EventAlignment]) -> List[EventAlignment]:
+        def key(a: EventAlignment):
+            base = a.base_event
+            comp = a.comparison_event
+            seq = (base.sequence if base else (comp.sequence if comp else 0))
+            id_ = ""
+            if base is not None:
+                id_ = str(base.id)
+            elif comp is not None:
+                id_ = str(comp.id)
+            return (seq, id_)
+
+        return sorted(alignments, key=key)
+
+    @staticmethod
+    def compute_profile_hash(profile, evaluator_identifier: str, engine_version: str) -> str:
+        payload = (
+            f"contractVersion:{CONTRACT_VERSION}\n"
+            f"engineVersion:{engine_version}\n"
+            f"strategy:{profile.strategy.value}\n"
+            f"profileVersion:{profile.version}\n"
+            f"typeWeight:{_fmt(profile.type_weight)}\n"
+            f"payloadWeight:{_fmt(profile.payload_weight)}\n"
+            f"structuralWeight:{_fmt(profile.structural_weight)}\n"
+            f"temporalWeight:{_fmt(profile.temporal_weight)}\n"
+            f"semanticThreshold:{_fmt(profile.semantic_threshold)}\n"
+            f"maxAmbiguousCandidates:{profile.max_ambiguous_candidates}\n"
+            f"ambiguityDeltaThreshold:{_fmt(profile.ambiguity_delta_threshold)}\n"
+            f"alignmentMode:{profile.alignment_mode.value}\n"
+            f"evaluatorIdentifier:{evaluator_identifier}"
+        )
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _fmt(value: float) -> str:
+    """Format a float the way Swift's default ``Double`` interpolation would: an integral
+    value keeps one decimal (``0.0``), others use the shortest round-trip repr."""
+    if value == int(value):
+        return f"{value:.1f}"
+    return repr(value)

dprovenancekit/alignment_engine.py

@@ -0,0 +1,111 @@
+"""The behavioral-equivalence engine: ``TraceAlignmentEngine``."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Callable, Optional
+
+from .alignment_config import AlignmentConfiguration
+from .alignment_evidence import (
+    AlignmentEvidenceCollector,
+    NullEvidenceCollector,
+    VerificationArtifacts,
+)
+from .alignment_interpreter import DefaultAlignmentInterpreter
+from .alignment_matcher import DefaultTraceMatcher
+from .alignment_models import (
+    AlignmentStateKind,
+    RegressionLevel,
+    RegressionRisk,
+    TraceAlignmentResult,
+)
+from .alignment_semantics import DefaultEquivalenceModel
+from .priority import TracePriority
+from .query import TraceRun
+
+
+class VerificationCaptureMode(Enum):
+    DISABLED = "disabled"
+    EVIDENCE_ONLY = "evidenceOnly"
+
+
+class TraceAlignmentEngine:
+    def __init__(
+        self,
+        configuration: AlignmentConfiguration,
+        capture_mode: VerificationCaptureMode = VerificationCaptureMode.DISABLED,
+        meta_trace_callback: Optional[Callable] = None,
+    ):
+        self.configuration = configuration
+        self.capture_mode = capture_mode
+        self.meta_trace_callback = meta_trace_callback
+        self._matcher = DefaultTraceMatcher(configuration)
+        self._semantics = DefaultEquivalenceModel(configuration)
+        self._interpreter = DefaultAlignmentInterpreter(configuration, meta_trace_callback)
+
+    def align(
+        self,
+        base: TraceRun,
+        comparison: TraceRun,
+        minimum_priority: TracePriority = TracePriority.STRUCTURAL,
+    ) -> TraceAlignmentResult:
+        base_events = [e for e in base.events if e.payload.priority >= minimum_priority]
+        comp_events = [e for e in comparison.events if e.payload.priority >= minimum_priority]
+
+        collector = (
+            AlignmentEvidenceCollector()
+            if self.capture_mode == VerificationCaptureMode.EVIDENCE_ONLY
+            else NullEvidenceCollector()
+        )
+
+        bindings = self._matcher.match(base_events, comp_events, evidence_collector=collector)
+
+        def equivalence(a, b):
+            return self._semantics.evaluate(a, b, evidence_collector=collector)
+
+        alignments = self._interpreter.interpret(
+            base=base_events,
+            comparison=comp_events,
+            bindings=bindings,
+            equivalence=equivalence,
+            evidence_collector=collector,
+        )
+
+        # Regression risk: removing a critical reasoning step is a high risk.
+        removed_critical = [
+            a
+            for a in alignments
+            if a.state.is_removed
+            and a.base_event is not None
+            and a.base_event.payload.priority == TracePriority.CRITICAL
+        ]
+        if removed_critical:
+            critical_types = ", ".join(a.base_event.payload.type_identifier for a in removed_critical)
+            risk = RegressionRisk(
+                level=RegressionLevel.HIGH,
+                strength=0.95,
+                reasoning=f"Critical reasoning steps removed: {critical_types}",
+            )
+        else:
+            risk = RegressionRisk(
+                level=RegressionLevel.NONE,
+                strength=1.0,
+                reasoning="No critical steps removed.",
+            )
+
+        v_artifacts = None
+        if isinstance(collector, AlignmentEvidenceCollector):
+            v_artifacts = VerificationArtifacts(evidence=collector.export_evidence())
+
+        return TraceAlignmentResult(
+            base_run_id=base.run_id,
+            comparison_run_id=comparison.run_id,
+            profile_hash=self.configuration.profile_hash,
+            engine_version="v2-causal-strict",
+            alignments=alignments,
+            regression_risk=risk,
+            verification_artifacts=v_artifacts,
+        )
+
+    def evaluate_score(self, base, comparison):
+        return self.configuration.score_match(base, comparison)

dprovenancekit/alignment_evidence.py

@@ -0,0 +1,103 @@
+"""Auditable evidence emitted during alignment: bindings, equivalence decisions, steps."""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from typing import List, Optional
+
+
+@dataclass(frozen=True)
+class EquivalenceReason:
+    description: str
+
+
+@dataclass(frozen=True)
+class AlignmentBinding:
+    base_event_id: "object"  # uuid.UUID
+    comparison_event_id: "object"
+    similarity_score: float
+
+
+@dataclass(frozen=True)
+class BindingDecision:
+    base_id: str
+    comparison_id: str
+    similarity_score: float
+
+
+@dataclass(frozen=True)
+class EquivalenceDecisionRecord:
+    lhs: str
+    rhs: str
+    confidence: float
+    equivalent: bool
+    reason: EquivalenceReason
+
+
+@dataclass(frozen=True)
+class InterpretationStep:
+    source_binding: Optional[AlignmentBinding]
+    base_id: Optional[str]
+    comparison_id: Optional[str]
+    output_state: str
+    rationale: str
+    base_sequence: Optional[int] = None
+    comparison_sequence: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class AlignmentEvidence:
+    bindings: List[BindingDecision]
+    equivalence_decisions: List[EquivalenceDecisionRecord]
+    interpretation_steps: List[InterpretationStep]
+
+
+@dataclass(frozen=True)
+class VerificationArtifacts:
+    evidence: AlignmentEvidence
+
+
+class EvidenceCollector:
+    def record_binding(self, decision: BindingDecision) -> None: ...
+    def record_equivalence(self, record: EquivalenceDecisionRecord) -> None: ...
+    def record_interpretation(self, step: InterpretationStep) -> None: ...
+
+
+class NullEvidenceCollector(EvidenceCollector):
+    def record_binding(self, decision: BindingDecision) -> None:
+        pass
+
+    def record_equivalence(self, record: EquivalenceDecisionRecord) -> None:
+        pass
+
+    def record_interpretation(self, step: InterpretationStep) -> None:
+        pass
+
+
+class AlignmentEvidenceCollector(EvidenceCollector):
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._bindings: List[BindingDecision] = []
+        self._equivalence_decisions: List[EquivalenceDecisionRecord] = []
+        self._interpretation_steps: List[InterpretationStep] = []
+
+    def record_binding(self, decision: BindingDecision) -> None:
+        with self._lock:
+            self._bindings.append(decision)
+
+    def record_equivalence(self, record: EquivalenceDecisionRecord) -> None:
+        with self._lock:
+            self._equivalence_decisions.append(record)
+
+    def record_interpretation(self, step: InterpretationStep) -> None:
+        with self._lock:
+            self._interpretation_steps.append(step)
+
+    def export_evidence(self) -> AlignmentEvidence:
+        with self._lock:
+            return AlignmentEvidence(
+                bindings=list(self._bindings),
+                equivalence_decisions=list(self._equivalence_decisions),
+                interpretation_steps=list(self._interpretation_steps),
+            )