spanforge 2.0.0__py3-none-any.whl

spanforge/namespaces/chain.py

@@ -0,0 +1,74 @@
+"""spanforge.namespaces.chain \u2014 Chain namespace payload types (RFC-0001 SPANFORGE).
+
+Classes
+-------
+ChainPayload    chain.started / chain.step_completed / chain.completed / chain.failed
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["ChainPayload"]
+
+
+@dataclass
+class ChainPayload:
+    """RFC-0001 SPANFORGE \u2014 payload for chain.* events.
+
+    Captures multi-step prompt chain state: step sequence, inter-step data
+    flow references, and cumulative error/cost/latency propagation.
+    """
+
+    chain_id: str
+    step_index: int
+    step_name: str
+    cumulative_latency_ms: float
+    cumulative_token_cost: float
+    error_propagated: bool
+    total_steps: int | None = None
+    input_refs: list[str] = field(default_factory=list)   # event ULIDs of inputs
+    output_refs: list[str] = field(default_factory=list)  # event ULIDs of outputs
+
+    def __post_init__(self) -> None:
+        if not self.chain_id:
+            raise ValueError("ChainPayload.chain_id must be non-empty")
+        if self.step_index < 0:
+            raise ValueError("ChainPayload.step_index must be >= 0")
+        if not self.step_name:
+            raise ValueError("ChainPayload.step_name must be non-empty")
+        if self.cumulative_latency_ms < 0:
+            raise ValueError("ChainPayload.cumulative_latency_ms must be >= 0")
+        if self.cumulative_token_cost < 0:
+            raise ValueError("ChainPayload.cumulative_token_cost must be >= 0")
+        if self.total_steps is not None and self.total_steps < 1:
+            raise ValueError("ChainPayload.total_steps must be >= 1")
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "chain_id": self.chain_id,
+            "step_index": self.step_index,
+            "step_name": self.step_name,
+            "cumulative_latency_ms": self.cumulative_latency_ms,
+            "cumulative_token_cost": self.cumulative_token_cost,
+            "error_propagated": self.error_propagated,
+            "input_refs": list(self.input_refs),
+            "output_refs": list(self.output_refs),
+        }
+        if self.total_steps is not None:
+            d["total_steps"] = self.total_steps
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ChainPayload:
+        return cls(
+            chain_id=data["chain_id"],
+            step_index=int(data["step_index"]),
+            step_name=data["step_name"],
+            cumulative_latency_ms=float(data["cumulative_latency_ms"]),
+            cumulative_token_cost=float(data["cumulative_token_cost"]),
+            error_propagated=bool(data["error_propagated"]),
+            total_steps=data.get("total_steps"),
+            input_refs=list(data.get("input_refs", [])),
+            output_refs=list(data.get("output_refs", [])),
+        )

spanforge/namespaces/confidence.py

@@ -0,0 +1,69 @@
+"""spanforge.namespaces.confidence \u2014 Confidence namespace payload types (RFC-0001 SPANFORGE).
+
+Classes
+-------
+ConfidencePayload   confidence.sample / confidence.threshold_breach
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ["ConfidencePayload"]
+
+
+@dataclass
+class ConfidencePayload:
+    """RFC-0001 SPANFORGE \u2014 payload for confidence.* events.
+
+    Tracks output confidence score distributions per decision type and model,
+    measured against the deployment baseline (T \u2014 Traceability).
+    """
+
+    model_id: str
+    decision_type: str
+    score: float            # 0.0\u20131.0
+    threshold_breached: bool
+    sampled_at: str         # ISO 8601 timestamp
+    baseline_mean: float | None = None
+    baseline_stddev: float | None = None
+    z_score: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.model_id:
+            raise ValueError("ConfidencePayload.model_id must be non-empty")
+        if not self.decision_type:
+            raise ValueError("ConfidencePayload.decision_type must be non-empty")
+        if not (0.0 <= self.score <= 1.0):
+            raise ValueError("ConfidencePayload.score must be in [0.0, 1.0]")
+        if not self.sampled_at:
+            raise ValueError("ConfidencePayload.sampled_at must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "model_id": self.model_id,
+            "decision_type": self.decision_type,
+            "score": self.score,
+            "threshold_breached": self.threshold_breached,
+            "sampled_at": self.sampled_at,
+        }
+        if self.baseline_mean is not None:
+            d["baseline_mean"] = self.baseline_mean
+        if self.baseline_stddev is not None:
+            d["baseline_stddev"] = self.baseline_stddev
+        if self.z_score is not None:
+            d["z_score"] = self.z_score
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ConfidencePayload:
+        return cls(
+            model_id=data["model_id"],
+            decision_type=data["decision_type"],
+            score=float(data["score"]),
+            threshold_breached=bool(data["threshold_breached"]),
+            sampled_at=data["sampled_at"],
+            baseline_mean=data.get("baseline_mean"),
+            baseline_stddev=data.get("baseline_stddev"),
+            z_score=data.get("z_score"),
+        )

spanforge/namespaces/consent.py

@@ -0,0 +1,85 @@
+"""spanforge.namespaces.consent — Consent namespace payload types (RFC-0001 SPANFORGE).
+
+Classes
+-------
+ConsentPayload    consent.granted / consent.revoked / consent.violation
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+__all__ = ["ConsentPayload"]
+
+_VALID_STATUSES = frozenset({"granted", "revoked", "violation"})
+_VALID_LEGAL_BASES = frozenset({
+    "consent", "contract", "legal_obligation",
+    "vital_interest", "public_task", "legitimate_interest",
+})
+
+
+@dataclass
+class ConsentPayload:
+    """RFC-0001 SPANFORGE — payload for consent.* events.
+
+    Tracks data-subject consent grants, revocations, and boundary violations
+    for GDPR Art. 6/7 and EU AI Act compliance (U — User Rights).
+    """
+
+    subject_id: str
+    scope: str
+    purpose: str
+    status: Literal["granted", "revoked", "violation"]
+    legal_basis: str = "consent"
+    expiry: str | None = None  # ISO 8601 timestamp
+    agent_id: str | None = None
+    violation_detail: str | None = None
+    data_categories: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.subject_id:
+            raise ValueError("ConsentPayload.subject_id must be non-empty")
+        if not self.scope:
+            raise ValueError("ConsentPayload.scope must be non-empty")
+        if not self.purpose:
+            raise ValueError("ConsentPayload.purpose must be non-empty")
+        if self.status not in _VALID_STATUSES:
+            raise ValueError(
+                f"ConsentPayload.status must be one of {sorted(_VALID_STATUSES)}"
+            )
+        if self.legal_basis not in _VALID_LEGAL_BASES:
+            raise ValueError(
+                f"ConsentPayload.legal_basis must be one of {sorted(_VALID_LEGAL_BASES)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "subject_id": self.subject_id,
+            "scope": self.scope,
+            "purpose": self.purpose,
+            "status": self.status,
+            "legal_basis": self.legal_basis,
+        }
+        if self.expiry is not None:
+            d["expiry"] = self.expiry
+        if self.agent_id is not None:
+            d["agent_id"] = self.agent_id
+        if self.violation_detail is not None:
+            d["violation_detail"] = self.violation_detail
+        if self.data_categories:
+            d["data_categories"] = list(self.data_categories)
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ConsentPayload:
+        return cls(
+            subject_id=data["subject_id"],
+            scope=data["scope"],
+            purpose=data["purpose"],
+            status=data["status"],
+            legal_basis=data.get("legal_basis", "consent"),
+            expiry=data.get("expiry"),
+            agent_id=data.get("agent_id"),
+            violation_detail=data.get("violation_detail"),
+            data_categories=list(data.get("data_categories", [])),
+        )

spanforge/namespaces/cost.py

@@ -0,0 +1,175 @@
+"""spanforge.namespaces.cost — Cost payload types (RFC-0001 §9).
+
+Classes
+-------
+CostTokenRecordedPayload
+    RFC §9.1 — cost recorded for a single model call.
+CostSessionRecordedPayload
+    RFC §9.2 — aggregate cost across a session.
+CostAttributedPayload
+    RFC §9.3 — cost attributed to a specific target.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from spanforge.namespaces.trace import (
+    CostBreakdown,
+    ModelInfo,
+    PricingTier,
+    TokenUsage,
+)
+
+__all__ = [
+    "CostAttributedPayload",
+    "CostSessionRecordedPayload",
+    "CostTokenRecordedPayload",
+]
+
+_VALID_ATTRIBUTION_TYPES = frozenset({"direct", "proportional", "estimated", "manual"})
+
+
+@dataclass
+class CostTokenRecordedPayload:
+    """RFC-0001 §9.1 — Cost recorded for a single model call (one span).
+
+    Used with event type: ``llm.cost.token.recorded``.
+    """
+
+    cost: CostBreakdown
+    token_usage: TokenUsage
+    model: ModelInfo
+    pricing_tier: PricingTier | None = None
+    span_id: str | None = None
+    agent_run_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.cost, CostBreakdown):
+            raise TypeError("CostTokenRecordedPayload.cost must be a CostBreakdown")
+        if not isinstance(self.token_usage, TokenUsage):
+            raise TypeError("CostTokenRecordedPayload.token_usage must be a TokenUsage")
+        if not isinstance(self.model, ModelInfo):
+            raise TypeError("CostTokenRecordedPayload.model must be a ModelInfo")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "cost": self.cost.to_dict(),
+            "token_usage": self.token_usage.to_dict(),
+            "model": self.model.to_dict(),
+        }
+        if self.pricing_tier is not None:
+            d["pricing_tier"] = self.pricing_tier.to_dict()
+        if self.span_id is not None:
+            d["span_id"] = self.span_id
+        if self.agent_run_id is not None:
+            d["agent_run_id"] = self.agent_run_id
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CostTokenRecordedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            cost=CostBreakdown.from_dict(data["cost"]),
+            token_usage=TokenUsage.from_dict(data["token_usage"]),
+            model=ModelInfo.from_dict(data["model"]),
+            pricing_tier=PricingTier.from_dict(data["pricing_tier"]) if "pricing_tier" in data else None,  # noqa: E501
+            span_id=data.get("span_id"),
+            agent_run_id=data.get("agent_run_id"),
+        )
+
+
+@dataclass
+class CostSessionRecordedPayload:
+    """RFC-0001 §9.2 — Aggregate cost across a session.
+
+    Used with event type: ``llm.cost.session.recorded``.
+    A session is any arbitrary grouping (user session, request batch, experiment run).
+    """
+
+    total_cost: CostBreakdown
+    total_token_usage: TokenUsage
+    call_count: int
+    session_duration_ms: float | None = None
+    models_used: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.total_cost, CostBreakdown):
+            raise TypeError("CostSessionRecordedPayload.total_cost must be a CostBreakdown")
+        if not isinstance(self.total_token_usage, TokenUsage):
+            raise TypeError("CostSessionRecordedPayload.total_token_usage must be a TokenUsage")
+        if not isinstance(self.call_count, int) or self.call_count < 0:
+            raise ValueError("CostSessionRecordedPayload.call_count must be a non-negative int")
+        if self.session_duration_ms is not None and self.session_duration_ms < 0:
+            raise ValueError("CostSessionRecordedPayload.session_duration_ms must be non-negative")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "total_cost": self.total_cost.to_dict(),
+            "total_token_usage": self.total_token_usage.to_dict(),
+            "call_count": self.call_count,
+        }
+        if self.session_duration_ms is not None:
+            d["session_duration_ms"] = self.session_duration_ms
+        if self.models_used:
+            d["models_used"] = list(self.models_used)
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CostSessionRecordedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            total_cost=CostBreakdown.from_dict(data["total_cost"]),
+            total_token_usage=TokenUsage.from_dict(data["total_token_usage"]),
+            call_count=int(data["call_count"]),
+            session_duration_ms=float(data["session_duration_ms"]) if "session_duration_ms" in data else None,  # noqa: E501
+            models_used=list(data.get("models_used", [])),
+        )
+
+
+@dataclass
+class CostAttributedPayload:
+    """RFC-0001 §9.3 — Cost attributed to a specific target.
+
+    Used with event type: ``llm.cost.attributed``.
+    ``attribution_type`` describes how the cost share was computed.
+    """
+
+    cost: CostBreakdown
+    attribution_target: str
+    attribution_type: str  # "direct"|"proportional"|"estimated"|"manual"
+    source_event_ids: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.cost, CostBreakdown):
+            raise TypeError("CostAttributedPayload.cost must be a CostBreakdown")
+        if not isinstance(self.attribution_target, str) or not self.attribution_target:
+            raise ValueError("CostAttributedPayload.attribution_target must be a non-empty string")
+        if self.attribution_type not in _VALID_ATTRIBUTION_TYPES:
+            raise ValueError(
+                f"CostAttributedPayload.attribution_type must be one of {sorted(_VALID_ATTRIBUTION_TYPES)}"  # noqa: E501
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "cost": self.cost.to_dict(),
+            "attribution_target": self.attribution_target,
+            "attribution_type": self.attribution_type,
+        }
+        if self.source_event_ids:
+            d["source_event_ids"] = list(self.source_event_ids)
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CostAttributedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            cost=CostBreakdown.from_dict(data["cost"]),
+            attribution_target=data["attribution_target"],
+            attribution_type=data["attribution_type"],
+            source_event_ids=list(data.get("source_event_ids", [])),
+        )

spanforge/namespaces/decision.py

@@ -0,0 +1,135 @@
+"""spanforge.namespaces.decision — Decision namespace payload types (RFC-0001 SPANFORGE).
+
+Classes
+-------
+DecisionDriver          Factor contributing to a decision (T \u2014 Transparency)
+DecisionPayload         decision.made / decision.revised / decision.rejected
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "DecisionDriver",
+    "DecisionPayload",
+]
+
+_VALID_DECISION_TYPES = frozenset({
+    "classification", "routing", "generation", "tool_selection", "other",
+})
+
+
+@dataclass
+class DecisionDriver:
+    """A single factor that contributed to an agent decision (T \u2014 Transparency).
+
+    ``weight`` and ``confidence`` must be in the range [0.0, 1.0].
+    The sum of all ``weight`` values in a list should equal 1.0 but is
+    not enforced here (enforcement is the caller's responsibility).
+    """
+
+    factor_name: str
+    weight: float       # 0.0\u20131.0; fractional contribution to the overall decision
+    contribution: float  # signed contribution to the final decision score
+    evidence: str       # human-readable evidence string
+    confidence: float   # 0.0\u20131.0
+
+    def __post_init__(self) -> None:
+        if not self.factor_name:
+            raise ValueError("DecisionDriver.factor_name must be non-empty")
+        if not (0.0 <= self.weight <= 1.0):
+            raise ValueError("DecisionDriver.weight must be in [0.0, 1.0]")
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError("DecisionDriver.confidence must be in [0.0, 1.0]")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "factor_name": self.factor_name,
+            "weight": self.weight,
+            "contribution": self.contribution,
+            "evidence": self.evidence,
+            "confidence": self.confidence,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DecisionDriver:
+        return cls(
+            factor_name=data["factor_name"],
+            weight=float(data["weight"]),
+            contribution=float(data["contribution"]),
+            evidence=data["evidence"],
+            confidence=float(data["confidence"]),
+        )
+
+
+@dataclass
+class DecisionPayload:
+    """RFC-0001 SPANFORGE \u2014 payload for decision.* events.
+
+    Captures every individual agent decision at inference time, including
+    the full set of contributing decision drivers for T \u2014 Transparency.
+
+    ``actor`` is an optional dict representation of an ActorContext and is
+    intentionally typed as ``dict | None`` to avoid a circular import.
+    """
+
+    decision_id: str        # ULID
+    agent_id: str
+    decision_type: str      # classification | routing | generation | tool_selection | other
+    input_summary: str
+    output_summary: str
+    confidence: float       # 0.0\u20131.0
+    latency_ms: float
+    rationale_hash: str     # SHA-256 of the full rationale text
+    decision_drivers: list[DecisionDriver] = field(default_factory=list)
+    actor: dict[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.decision_id:
+            raise ValueError("DecisionPayload.decision_id must be non-empty")
+        if not self.agent_id:
+            raise ValueError("DecisionPayload.agent_id must be non-empty")
+        if self.decision_type not in _VALID_DECISION_TYPES:
+            raise ValueError(
+                f"DecisionPayload.decision_type must be one of {sorted(_VALID_DECISION_TYPES)}"
+            )
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError("DecisionPayload.confidence must be in [0.0, 1.0]")
+        if self.latency_ms < 0:
+            raise ValueError("DecisionPayload.latency_ms must be >= 0")
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "decision_id": self.decision_id,
+            "agent_id": self.agent_id,
+            "decision_type": self.decision_type,
+            "input_summary": self.input_summary,
+            "output_summary": self.output_summary,
+            "confidence": self.confidence,
+            "latency_ms": self.latency_ms,
+            "rationale_hash": self.rationale_hash,
+            "decision_drivers": [d.to_dict() for d in self.decision_drivers],
+        }
+        if self.actor is not None:
+            d["actor"] = self.actor
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DecisionPayload:
+        drivers = [
+            DecisionDriver.from_dict(dd)
+            for dd in data.get("decision_drivers", [])
+        ]
+        return cls(
+            decision_id=data["decision_id"],
+            agent_id=data["agent_id"],
+            decision_type=data["decision_type"],
+            input_summary=data["input_summary"],
+            output_summary=data["output_summary"],
+            confidence=float(data["confidence"]),
+            latency_ms=float(data["latency_ms"]),
+            rationale_hash=data["rationale_hash"],
+            decision_drivers=drivers,
+            actor=data.get("actor"),
+        )

spanforge/namespaces/diff.py

@@ -0,0 +1,146 @@
+"""spanforge.namespaces.diff — Diff payload types (RFC-0001).
+
+Classes
+-------
+DiffComputedPayload         llm.diff.computed
+DiffRegressionFlaggedPayload llm.diff.regression.flagged
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = [
+    "DiffComputedPayload",
+    "DiffRegressionFlaggedPayload",
+]
+
+_VALID_DIFF_TYPES = frozenset({"prompt", "response", "template", "token_usage", "cost"})
+_VALID_ALGORITHMS = frozenset({
+    "embedding_cosine", "levenshtein", "token_edit", "lcs", "semantic_embedding"
+})
+_VALID_SEVERITIES = frozenset({"low", "medium", "high", "critical"})
+
+
+@dataclass
+class DiffComputedPayload:
+    """RFC-0001 — A diff was computed between two events."""
+
+    ref_event_id: str
+    target_event_id: str
+    diff_type: str        # "prompt"|"response"|"template"|"token_usage"|"cost"
+    similarity_score: float
+    added_tokens: int | None = None
+    removed_tokens: int | None = None
+    diff_algorithm: str | None = None
+    ref_content_hash: str | None = None    # 64 hex chars
+    target_content_hash: str | None = None # 64 hex chars
+    computation_duration_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.ref_event_id:
+            raise ValueError("DiffComputedPayload.ref_event_id must be non-empty")
+        if not self.target_event_id:
+            raise ValueError("DiffComputedPayload.target_event_id must be non-empty")
+        if self.diff_type not in _VALID_DIFF_TYPES:
+            raise ValueError(f"DiffComputedPayload.diff_type must be one of {sorted(_VALID_DIFF_TYPES)}")  # noqa: E501
+        if not (0.0 <= self.similarity_score <= 1.0):
+            raise ValueError("DiffComputedPayload.similarity_score must be in [0,1]")
+        if self.diff_algorithm is not None and self.diff_algorithm not in _VALID_ALGORITHMS:
+            raise ValueError(f"DiffComputedPayload.diff_algorithm must be one of {sorted(_VALID_ALGORITHMS)}")  # noqa: E501
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "ref_event_id": self.ref_event_id,
+            "target_event_id": self.target_event_id,
+            "diff_type": self.diff_type,
+            "similarity_score": self.similarity_score,
+        }
+        if self.added_tokens is not None:
+            d["added_tokens"] = self.added_tokens
+        if self.removed_tokens is not None:
+            d["removed_tokens"] = self.removed_tokens
+        if self.diff_algorithm is not None:
+            d["diff_algorithm"] = self.diff_algorithm
+        if self.ref_content_hash is not None:
+            d["ref_content_hash"] = self.ref_content_hash
+        if self.target_content_hash is not None:
+            d["target_content_hash"] = self.target_content_hash
+        if self.computation_duration_ms is not None:
+            d["computation_duration_ms"] = self.computation_duration_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DiffComputedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            ref_event_id=data["ref_event_id"],
+            target_event_id=data["target_event_id"],
+            diff_type=data["diff_type"],
+            similarity_score=float(data["similarity_score"]),
+            added_tokens=int(data["added_tokens"]) if "added_tokens" in data else None,
+            removed_tokens=int(data["removed_tokens"]) if "removed_tokens" in data else None,
+            diff_algorithm=data.get("diff_algorithm"),
+            ref_content_hash=data.get("ref_content_hash"),
+            target_content_hash=data.get("target_content_hash"),
+            computation_duration_ms=float(data["computation_duration_ms"]) if "computation_duration_ms" in data else None,  # noqa: E501
+        )
+
+
+@dataclass
+class DiffRegressionFlaggedPayload:
+    """RFC-0001 — A diff score fell below the similarity threshold."""
+
+    ref_event_id: str
+    target_event_id: str
+    diff_type: str
+    similarity_score: float
+    threshold: float
+    severity: str  # "low"|"medium"|"high"|"critical"
+    diff_event_id: str | None = None
+    alert_target: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.ref_event_id:
+            raise ValueError("DiffRegressionFlaggedPayload.ref_event_id must be non-empty")
+        if not self.target_event_id:
+            raise ValueError("DiffRegressionFlaggedPayload.target_event_id must be non-empty")
+        if self.diff_type not in _VALID_DIFF_TYPES:
+            raise ValueError(f"DiffRegressionFlaggedPayload.diff_type must be one of {sorted(_VALID_DIFF_TYPES)}")  # noqa: E501
+        if not (0.0 <= self.similarity_score <= 1.0):
+            raise ValueError("DiffRegressionFlaggedPayload.similarity_score must be in [0,1]")
+        if not (0.0 <= self.threshold <= 1.0):
+            raise ValueError("DiffRegressionFlaggedPayload.threshold must be in [0,1]")
+        if self.severity not in _VALID_SEVERITIES:
+            raise ValueError(f"DiffRegressionFlaggedPayload.severity must be one of {sorted(_VALID_SEVERITIES)}")  # noqa: E501
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "ref_event_id": self.ref_event_id,
+            "target_event_id": self.target_event_id,
+            "diff_type": self.diff_type,
+            "similarity_score": self.similarity_score,
+            "threshold": self.threshold,
+            "severity": self.severity,
+        }
+        if self.diff_event_id is not None:
+            d["diff_event_id"] = self.diff_event_id
+        if self.alert_target is not None:
+            d["alert_target"] = self.alert_target
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DiffRegressionFlaggedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            ref_event_id=data["ref_event_id"],
+            target_event_id=data["target_event_id"],
+            diff_type=data["diff_type"],
+            similarity_score=float(data["similarity_score"]),
+            threshold=float(data["threshold"]),
+            severity=data["severity"],
+            diff_event_id=data.get("diff_event_id"),
+            alert_target=data.get("alert_target"),
+        )