spanforge 1.0.0__py3-none-any.whl

spanforge/namespaces/eval_.py

@@ -0,0 +1,251 @@
+"""spanforge.namespaces.eval_ — Evaluation payload types (RFC-0001).
+
+Classes
+-------
+EvalScoreRecordedPayload        llm.eval.score.recorded
+EvalRegressionDetectedPayload   llm.eval.regression.detected
+EvalScenarioStartedPayload      llm.eval.scenario.started
+EvalScenarioCompletedPayload    llm.eval.scenario.completed
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from spanforge.namespaces.trace import ModelInfo
+
+__all__ = [
+    "EvalRegressionDetectedPayload",
+    "EvalScenarioCompletedPayload",
+    "EvalScenarioStartedPayload",
+    "EvalScoreRecordedPayload",
+]
+
+_VALID_SEVERITIES = frozenset({"low", "medium", "high", "critical"})
+_VALID_STATUSES = frozenset({"passed", "failed", "error", "cancelled"})
+
+
+@dataclass
+class EvalScoreRecordedPayload:
+    """RFC-0001 — A single evaluation score recorded for a subject event."""
+
+    evaluator: str
+    metric_name: str
+    score: float
+    score_min: float | None = None
+    score_max: float | None = None
+    threshold: float | None = None
+    passed: bool | None = None
+    subject_event_id: str | None = None
+    subject_type: str | None = None
+    eval_run_id: str | None = None
+    rationale: str | None = None
+    model: ModelInfo | None = None  # judge model
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.evaluator, str) or not self.evaluator:
+            raise ValueError("EvalScoreRecordedPayload.evaluator must be non-empty")
+        if not isinstance(self.metric_name, str) or not self.metric_name:
+            raise ValueError("EvalScoreRecordedPayload.metric_name must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "evaluator": self.evaluator,
+            "metric_name": self.metric_name,
+            "score": self.score,
+        }
+        for f in (
+            "score_min",
+            "score_max",
+            "threshold",
+            "passed",
+            "subject_event_id",
+            "subject_type",
+            "eval_run_id",
+            "rationale",
+        ):
+            v = getattr(self, f)
+            if v is not None:
+                d[f] = v
+        if self.model is not None:
+            d["model"] = self.model.to_dict()
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> EvalScoreRecordedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            evaluator=data["evaluator"],
+            metric_name=data["metric_name"],
+            score=float(data["score"]),
+            score_min=float(data["score_min"]) if "score_min" in data else None,
+            score_max=float(data["score_max"]) if "score_max" in data else None,
+            threshold=float(data["threshold"]) if "threshold" in data else None,
+            passed=bool(data["passed"]) if "passed" in data else None,
+            subject_event_id=data.get("subject_event_id"),
+            subject_type=data.get("subject_type"),
+            eval_run_id=data.get("eval_run_id"),
+            rationale=data.get("rationale"),
+            model=ModelInfo.from_dict(data["model"]) if "model" in data else None,
+        )
+
+
+@dataclass
+class EvalRegressionDetectedPayload:
+    """RFC-0001 — A metric regression detected between baseline and current."""
+
+    metric_name: str
+    baseline_score: float
+    current_score: float
+    delta: float
+    regression_pct: float
+    severity: str | None = None  # "low"|"medium"|"high"|"critical"
+    affected_model: ModelInfo | None = None
+    eval_run_id: str | None = None
+    sample_count: int | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.metric_name, str) or not self.metric_name:
+            raise ValueError("EvalRegressionDetectedPayload.metric_name must be non-empty")
+        if self.severity is not None and self.severity not in _VALID_SEVERITIES:
+            raise ValueError(
+                f"EvalRegressionDetectedPayload.severity must be one of {sorted(_VALID_SEVERITIES)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "metric_name": self.metric_name,
+            "baseline_score": self.baseline_score,
+            "current_score": self.current_score,
+            "delta": self.delta,
+            "regression_pct": self.regression_pct,
+        }
+        if self.severity is not None:
+            d["severity"] = self.severity
+        if self.affected_model is not None:
+            d["affected_model"] = self.affected_model.to_dict()
+        if self.eval_run_id is not None:
+            d["eval_run_id"] = self.eval_run_id
+        if self.sample_count is not None:
+            d["sample_count"] = self.sample_count
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> EvalRegressionDetectedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            metric_name=data["metric_name"],
+            baseline_score=float(data["baseline_score"]),
+            current_score=float(data["current_score"]),
+            delta=float(data["delta"]),
+            regression_pct=float(data["regression_pct"]),
+            severity=data.get("severity"),
+            affected_model=ModelInfo.from_dict(data["affected_model"])
+            if "affected_model" in data
+            else None,
+            eval_run_id=data.get("eval_run_id"),
+            sample_count=int(data["sample_count"]) if "sample_count" in data else None,
+        )
+
+
+@dataclass
+class EvalScenarioStartedPayload:
+    """RFC-0001 — An evaluation scenario has started."""
+
+    scenario_id: str
+    scenario_name: str
+    evaluator: str
+    dataset_id: str | None = None
+    expected_sample_count: int | None = None
+    metrics: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.scenario_id:
+            raise ValueError("EvalScenarioStartedPayload.scenario_id must be non-empty")
+        if not self.scenario_name:
+            raise ValueError("EvalScenarioStartedPayload.scenario_name must be non-empty")
+        if not self.evaluator:
+            raise ValueError("EvalScenarioStartedPayload.evaluator must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "scenario_id": self.scenario_id,
+            "scenario_name": self.scenario_name,
+            "evaluator": self.evaluator,
+        }
+        if self.dataset_id is not None:
+            d["dataset_id"] = self.dataset_id
+        if self.expected_sample_count is not None:
+            d["expected_sample_count"] = self.expected_sample_count
+        if self.metrics:
+            d["metrics"] = list(self.metrics)
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> EvalScenarioStartedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            scenario_id=data["scenario_id"],
+            scenario_name=data["scenario_name"],
+            evaluator=data["evaluator"],
+            dataset_id=data.get("dataset_id"),
+            expected_sample_count=int(data["expected_sample_count"])
+            if "expected_sample_count" in data
+            else None,
+            metrics=list(data.get("metrics", [])),
+        )
+
+
+@dataclass
+class EvalScenarioCompletedPayload:
+    """RFC-0001 — An evaluation scenario has completed."""
+
+    scenario_id: str
+    status: str  # "passed"|"failed"|"error"|"cancelled"
+    duration_ms: float
+    completed_sample_count: int | None = None
+    scores_summary: dict[str, float] | None = None
+    errors: list[str] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.scenario_id:
+            raise ValueError("EvalScenarioCompletedPayload.scenario_id must be non-empty")
+        if self.status not in _VALID_STATUSES:
+            raise ValueError(
+                f"EvalScenarioCompletedPayload.status must be one of {sorted(_VALID_STATUSES)}"
+            )
+        if self.duration_ms < 0:
+            raise ValueError("EvalScenarioCompletedPayload.duration_ms must be non-negative")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "scenario_id": self.scenario_id,
+            "status": self.status,
+            "duration_ms": self.duration_ms,
+        }
+        if self.completed_sample_count is not None:
+            d["completed_sample_count"] = self.completed_sample_count
+        if self.scores_summary is not None:
+            d["scores_summary"] = dict(self.scores_summary)
+        if self.errors is not None:
+            d["errors"] = list(self.errors)
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> EvalScenarioCompletedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            scenario_id=data["scenario_id"],
+            status=data["status"],
+            duration_ms=float(data["duration_ms"]),
+            completed_sample_count=int(data["completed_sample_count"])
+            if "completed_sample_count" in data
+            else None,
+            scores_summary=dict(data["scores_summary"]) if "scores_summary" in data else None,
+            errors=list(data["errors"]) if "errors" in data else None,
+        )

spanforge/namespaces/feedback.py

@@ -0,0 +1,241 @@
+"""spanforge.namespaces.feedback — User feedback namespace payload types.
+
+Provides dataclasses for the ``llm.feedback.*`` event namespace, covering
+all supported feedback rating modalities:
+
+1. **Thumbs** — binary thumbs-up / thumbs-down feedback.
+2. **Star** — 1–5 star rating.
+3. **Likert** — 1–5 Likert scale response.
+4. **Free-text** — open-ended qualitative comment (stored hashed, not raw).
+
+Classes
+-------
+FeedbackRating
+    Enum of supported rating types.
+FeedbackSubmittedPayload
+    ``llm.feedback.submitted`` events — the primary payload for any feedback.
+FeedbackSummaryPayload
+    ``llm.feedback.summary`` events — aggregated feedback for a session /
+    trace / response.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+__all__ = [
+    "FeedbackRating",
+    "FeedbackSubmittedPayload",
+    "FeedbackSummaryPayload",
+]
+
+
+# ---------------------------------------------------------------------------
+# Rating type enum
+# ---------------------------------------------------------------------------
+
+
+class FeedbackRating(str, Enum):
+    """Supported feedback rating modalities.
+
+    Attributes:
+        THUMBS_UP:   Binary positive feedback.
+        THUMBS_DOWN: Binary negative feedback.
+        STAR_1:      1 out of 5 stars.
+        STAR_2:      2 out of 5 stars.
+        STAR_3:      3 out of 5 stars.
+        STAR_4:      4 out of 5 stars.
+        STAR_5:      5 out of 5 stars.
+        LIKERT_1:    Strongly disagree (Likert 1/5).
+        LIKERT_2:    Disagree (Likert 2/5).
+        LIKERT_3:    Neutral (Likert 3/5).
+        LIKERT_4:    Agree (Likert 4/5).
+        LIKERT_5:    Strongly agree (Likert 5/5).
+        FREE_TEXT:   Open-ended qualitative comment.
+    """
+
+    THUMBS_UP = "thumbs_up"
+    THUMBS_DOWN = "thumbs_down"
+    STAR_1 = "star_1"
+    STAR_2 = "star_2"
+    STAR_3 = "star_3"
+    STAR_4 = "star_4"
+    STAR_5 = "star_5"
+    LIKERT_1 = "likert_1"
+    LIKERT_2 = "likert_2"
+    LIKERT_3 = "likert_3"
+    LIKERT_4 = "likert_4"
+    LIKERT_5 = "likert_5"
+    FREE_TEXT = "free_text"
+
+    def numeric_value(self) -> float | None:
+        """Return a 0.0–1.0 normalised numeric value for ratings that have one.
+
+        Returns ``None`` for :attr:`FREE_TEXT` (non-numeric).  Thumbs are
+        mapped to ``0.0`` / ``1.0``; Star and Likert scales are mapped to
+        their (value - 1) / 4 position on a 0–1 scale.
+        """
+        _map: dict[str, float] = {
+            "thumbs_up": 1.0,
+            "thumbs_down": 0.0,
+            "star_1": 0.0,
+            "star_2": 0.25,
+            "star_3": 0.5,
+            "star_4": 0.75,
+            "star_5": 1.0,
+            "likert_1": 0.0,
+            "likert_2": 0.25,
+            "likert_3": 0.5,
+            "likert_4": 0.75,
+            "likert_5": 1.0,
+        }
+        return _map.get(self.value)
+
+
+# ---------------------------------------------------------------------------
+# Payload dataclasses
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class FeedbackSubmittedPayload:
+    """Payload for ``llm.feedback.submitted`` events.
+
+    Raw free-text comments are **never stored**; when *rating* is
+    ``FeedbackRating.FREE_TEXT`` the *comment_hash* field holds the SHA-256
+    digest of the comment text.
+
+    Attributes:
+        feedback_id:   Unique identifier for this feedback record (ULID).
+        session_id:    Session or conversation this feedback applies to.
+        trace_id:      Trace ID of the specific LLM call being rated.
+        rating:        The :class:`FeedbackRating` value.
+        comment_hash:  SHA-256 hex digest of the free-text comment, or ``""``
+                       when *rating* is not ``FREE_TEXT``.
+        user_id_hash:  SHA-256 hex digest of the user identifier, or ``""``
+                       when the submission is anonymous.
+        source:        Feedback collection channel (e.g. ``"widget"``,
+                       ``"api"``, ``"email"``).
+        metadata:      Arbitrary key-value metadata (e.g. page URL, A/B variant).
+        linked_trust_dimension:
+                       Optional T.R.U.S.T. dimension this feedback should
+                       influence (e.g. ``"reliability"``).
+    """
+
+    feedback_id: str
+    session_id: str
+    trace_id: str
+    rating: FeedbackRating
+    comment_hash: str = ""
+    user_id_hash: str = ""
+    source: str = "api"
+    metadata: dict[str, Any] = field(default_factory=dict)
+    linked_trust_dimension: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.feedback_id:
+            raise ValueError("FeedbackSubmittedPayload.feedback_id must be non-empty")
+        if not self.session_id:
+            raise ValueError("FeedbackSubmittedPayload.session_id must be non-empty")
+        if not isinstance(self.rating, FeedbackRating):
+            # Accept raw string values for convenience.
+            self.rating = FeedbackRating(self.rating)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a plain dict."""
+        d: dict[str, Any] = {
+            "feedback_id": self.feedback_id,
+            "session_id": self.session_id,
+            "trace_id": self.trace_id,
+            "rating": self.rating.value,
+            "comment_hash": self.comment_hash,
+            "user_id_hash": self.user_id_hash,
+            "source": self.source,
+            "metadata": self.metadata,
+        }
+        if self.linked_trust_dimension is not None:
+            d["linked_trust_dimension"] = self.linked_trust_dimension
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FeedbackSubmittedPayload:
+        """Deserialise from a plain dict."""
+        return cls(
+            feedback_id=str(data["feedback_id"]),
+            session_id=str(data["session_id"]),
+            trace_id=str(data.get("trace_id", "")),
+            rating=FeedbackRating(data["rating"]),
+            comment_hash=str(data.get("comment_hash", "")),
+            user_id_hash=str(data.get("user_id_hash", "")),
+            source=str(data.get("source", "api")),
+            metadata=dict(data.get("metadata", {})),
+            linked_trust_dimension=data.get("linked_trust_dimension"),
+        )
+
+
+@dataclass
+class FeedbackSummaryPayload:
+    """Payload for ``llm.feedback.summary`` events.
+
+    Aggregated feedback statistics over a session or time window.
+
+    Attributes:
+        session_id:       Session or aggregation window identifier.
+        total_feedback:   Total number of feedback events in the window.
+        thumbs_up_count:  Count of ``THUMBS_UP`` ratings.
+        thumbs_down_count: Count of ``THUMBS_DOWN`` ratings.
+        avg_star_rating:  Mean star rating (1–5); ``None`` if no star ratings.
+        avg_likert_score: Mean Likert score (1–5); ``None`` if no Likert ratings.
+        free_text_count:  Number of free-text comments submitted.
+        positive_rate:    Fraction of positive feedback (0.0–1.0) — computed
+                          from all numeric ratings above the neutral threshold.
+    """
+
+    session_id: str
+    total_feedback: int = 0
+    thumbs_up_count: int = 0
+    thumbs_down_count: int = 0
+    avg_star_rating: float | None = None
+    avg_likert_score: float | None = None
+    free_text_count: int = 0
+    positive_rate: float = 0.0
+
+    def __post_init__(self) -> None:
+        if not self.session_id:
+            raise ValueError("FeedbackSummaryPayload.session_id must be non-empty")
+        if not (0.0 <= self.positive_rate <= 1.0):
+            raise ValueError(
+                f"FeedbackSummaryPayload.positive_rate must be in [0, 1]; got {self.positive_rate}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a plain dict."""
+        d: dict[str, Any] = {
+            "session_id": self.session_id,
+            "total_feedback": self.total_feedback,
+            "thumbs_up_count": self.thumbs_up_count,
+            "thumbs_down_count": self.thumbs_down_count,
+            "free_text_count": self.free_text_count,
+            "positive_rate": self.positive_rate,
+        }
+        if self.avg_star_rating is not None:
+            d["avg_star_rating"] = self.avg_star_rating
+        if self.avg_likert_score is not None:
+            d["avg_likert_score"] = self.avg_likert_score
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FeedbackSummaryPayload:
+        """Deserialise from a plain dict."""
+        return cls(
+            session_id=str(data["session_id"]),
+            total_feedback=int(data.get("total_feedback", 0)),
+            thumbs_up_count=int(data.get("thumbs_up_count", 0)),
+            thumbs_down_count=int(data.get("thumbs_down_count", 0)),
+            avg_star_rating=data.get("avg_star_rating"),
+            avg_likert_score=data.get("avg_likert_score"),
+            free_text_count=int(data.get("free_text_count", 0)),
+            positive_rate=float(data.get("positive_rate", 0.0)),
+        )

spanforge/namespaces/fence.py

@@ -0,0 +1,193 @@
+"""spanforge.namespaces.fence — Fence payload types (RFC-0001).
+
+Classes
+-------
+FenceValidatedPayload           llm.fence.validated
+FenceRetryTriggeredPayload      llm.fence.retry.triggered
+FenceMaxRetriesExceededPayload  llm.fence.max_retries.exceeded
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from spanforge.namespaces.trace import CostBreakdown
+
+__all__ = [
+    "FenceMaxRetriesExceededPayload",
+    "FenceRetryTriggeredPayload",
+    "FenceValidatedPayload",
+]
+
+_VALID_OUTPUT_TYPES = frozenset({"json_schema", "pydantic", "regex", "xml", "custom"})
+
+
+@dataclass
+class FenceValidatedPayload:
+    """RFC-0001 — Structured output passed validation on a given attempt."""
+
+    fence_id: str
+    schema_name: str
+    attempt: int
+    output_type: str | None = None  # "json_schema"|"pydantic"|"regex"|"xml"|"custom"
+    span_id: str | None = None
+    validation_duration_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.fence_id:
+            raise ValueError("FenceValidatedPayload.fence_id must be non-empty")
+        if not self.schema_name:
+            raise ValueError("FenceValidatedPayload.schema_name must be non-empty")
+        if not isinstance(self.attempt, int) or self.attempt < 1:
+            raise ValueError("FenceValidatedPayload.attempt must be a positive int")
+        if self.output_type is not None and self.output_type not in _VALID_OUTPUT_TYPES:
+            raise ValueError(
+                f"FenceValidatedPayload.output_type must be one of {sorted(_VALID_OUTPUT_TYPES)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "fence_id": self.fence_id,
+            "schema_name": self.schema_name,
+            "attempt": self.attempt,
+        }
+        if self.output_type is not None:
+            d["output_type"] = self.output_type
+        if self.span_id is not None:
+            d["span_id"] = self.span_id
+        if self.validation_duration_ms is not None:
+            d["validation_duration_ms"] = self.validation_duration_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FenceValidatedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            fence_id=data["fence_id"],
+            schema_name=data["schema_name"],
+            attempt=int(data["attempt"]),
+            output_type=data.get("output_type"),
+            span_id=data.get("span_id"),
+            validation_duration_ms=float(data["validation_duration_ms"])
+            if "validation_duration_ms" in data
+            else None,
+        )
+
+
+@dataclass
+class FenceRetryTriggeredPayload:
+    """RFC-0001 — A validation failure triggered a retry."""
+
+    fence_id: str
+    schema_name: str
+    attempt: int
+    max_attempts: int
+    violation_summary: str
+    output_type: str | None = None
+    span_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.fence_id:
+            raise ValueError("FenceRetryTriggeredPayload.fence_id must be non-empty")
+        if not self.schema_name:
+            raise ValueError("FenceRetryTriggeredPayload.schema_name must be non-empty")
+        if not isinstance(self.attempt, int) or self.attempt < 1:
+            raise ValueError("FenceRetryTriggeredPayload.attempt must be a positive int")
+        if not isinstance(self.max_attempts, int) or self.max_attempts < 1:
+            raise ValueError("FenceRetryTriggeredPayload.max_attempts must be a positive int")
+        if not self.violation_summary:
+            raise ValueError("FenceRetryTriggeredPayload.violation_summary must be non-empty")
+        if self.output_type is not None and self.output_type not in _VALID_OUTPUT_TYPES:
+            raise ValueError(
+                f"FenceRetryTriggeredPayload.output_type must be one of {sorted(_VALID_OUTPUT_TYPES)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "fence_id": self.fence_id,
+            "schema_name": self.schema_name,
+            "attempt": self.attempt,
+            "max_attempts": self.max_attempts,
+            "violation_summary": self.violation_summary,
+        }
+        if self.output_type is not None:
+            d["output_type"] = self.output_type
+        if self.span_id is not None:
+            d["span_id"] = self.span_id
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FenceRetryTriggeredPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            fence_id=data["fence_id"],
+            schema_name=data["schema_name"],
+            attempt=int(data["attempt"]),
+            max_attempts=int(data["max_attempts"]),
+            violation_summary=data["violation_summary"],
+            output_type=data.get("output_type"),
+            span_id=data.get("span_id"),
+        )
+
+
+@dataclass
+class FenceMaxRetriesExceededPayload:
+    """RFC-0001 — All retry attempts exhausted; output remains invalid."""
+
+    fence_id: str
+    schema_name: str
+    attempts_made: int
+    final_violation_summary: str
+    output_type: str | None = None
+    span_id: str | None = None
+    total_extra_cost: CostBreakdown | None = None
+
+    def __post_init__(self) -> None:
+        if not self.fence_id:
+            raise ValueError("FenceMaxRetriesExceededPayload.fence_id must be non-empty")
+        if not self.schema_name:
+            raise ValueError("FenceMaxRetriesExceededPayload.schema_name must be non-empty")
+        if not isinstance(self.attempts_made, int) or self.attempts_made < 1:
+            raise ValueError("FenceMaxRetriesExceededPayload.attempts_made must be a positive int")
+        if not self.final_violation_summary:
+            raise ValueError(
+                "FenceMaxRetriesExceededPayload.final_violation_summary must be non-empty"
+            )
+        if self.output_type is not None and self.output_type not in _VALID_OUTPUT_TYPES:
+            raise ValueError(
+                f"FenceMaxRetriesExceededPayload.output_type must be one of {sorted(_VALID_OUTPUT_TYPES)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "fence_id": self.fence_id,
+            "schema_name": self.schema_name,
+            "attempts_made": self.attempts_made,
+            "final_violation_summary": self.final_violation_summary,
+        }
+        if self.output_type is not None:
+            d["output_type"] = self.output_type
+        if self.span_id is not None:
+            d["span_id"] = self.span_id
+        if self.total_extra_cost is not None:
+            d["total_extra_cost"] = self.total_extra_cost.to_dict()
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FenceMaxRetriesExceededPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            fence_id=data["fence_id"],
+            schema_name=data["schema_name"],
+            attempts_made=int(data["attempts_made"]),
+            final_violation_summary=data["final_violation_summary"],
+            output_type=data.get("output_type"),
+            span_id=data.get("span_id"),
+            total_extra_cost=CostBreakdown.from_dict(data["total_extra_cost"])
+            if "total_extra_cost" in data
+            else None,
+        )