spanforge 2.0.0__py3-none-any.whl

spanforge/namespaces/drift.py

@@ -0,0 +1,79 @@
+"""spanforge.namespaces.drift \u2014 Drift namespace payload types (RFC-0001 SPANFORGE).
+
+Classes
+-------
+DriftPayload    drift.detected / drift.threshold_breach / drift.resolved
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+__all__ = ["DriftPayload"]
+
+_VALID_STATUSES = frozenset({"detected", "threshold_breach", "resolved"})
+
+
+@dataclass
+class DriftPayload:
+    """RFC-0001 SPANFORGE \u2014 payload for drift.* events.
+
+    Captures Z-score and KL-divergence statistical drift signals against the
+    deployment baseline (T \u2014 Traceability).
+    """
+
+    metric_name: str
+    agent_id: str
+    current_value: float
+    baseline_mean: float
+    baseline_stddev: float
+    z_score: float
+    threshold: float
+    window_seconds: int
+    status: Literal["detected", "threshold_breach", "resolved"]
+    kl_divergence: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.metric_name:
+            raise ValueError("DriftPayload.metric_name must be non-empty")
+        if not self.agent_id:
+            raise ValueError("DriftPayload.agent_id must be non-empty")
+        if self.status not in _VALID_STATUSES:
+            raise ValueError(
+                f"DriftPayload.status must be one of {sorted(_VALID_STATUSES)}"
+            )
+        if self.window_seconds <= 0:
+            raise ValueError("DriftPayload.window_seconds must be > 0")
+        if self.baseline_stddev < 0:
+            raise ValueError("DriftPayload.baseline_stddev must be >= 0")
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "metric_name": self.metric_name,
+            "agent_id": self.agent_id,
+            "current_value": self.current_value,
+            "baseline_mean": self.baseline_mean,
+            "baseline_stddev": self.baseline_stddev,
+            "z_score": self.z_score,
+            "threshold": self.threshold,
+            "window_seconds": self.window_seconds,
+            "status": self.status,
+        }
+        if self.kl_divergence is not None:
+            d["kl_divergence"] = self.kl_divergence
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DriftPayload:
+        return cls(
+            metric_name=data["metric_name"],
+            agent_id=data["agent_id"],
+            current_value=float(data["current_value"]),
+            baseline_mean=float(data["baseline_mean"]),
+            baseline_stddev=float(data["baseline_stddev"]),
+            z_score=float(data["z_score"]),
+            threshold=float(data["threshold"]),
+            window_seconds=int(data["window_seconds"]),
+            status=data["status"],
+            kl_divergence=data.get("kl_divergence"),
+        )

spanforge/namespaces/eval_.py

@@ -0,0 +1,232 @@
+"""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)}")  # noqa: E501
+
+    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,  # noqa: E501
+            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,  # noqa: E501
+            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)}")  # noqa: E501
+        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,  # noqa: E501
+            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/fence.py

@@ -0,0 +1,180 @@
+"""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)}")  # noqa: E501
+
+    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,  # noqa: E501
+        )
+
+
+@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)}")  # noqa: E501
+
+    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")  # noqa: E501
+        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)}")  # noqa: E501
+
+    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,  # noqa: E501
+        )

spanforge/namespaces/guard.py

@@ -0,0 +1,104 @@
+"""spanforge.namespaces.guard — Guard payload types (RFC-0001).
+
+A single ``GuardPayload`` class is used for all four guard event types.
+
+Classes
+-------
+GuardPayload    llm.guard.input.blocked, llm.guard.input.passed,
+                llm.guard.output.blocked, llm.guard.output.passed
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["GuardPayload"]
+
+_VALID_DIRECTIONS = frozenset({"input", "output"})
+_VALID_ACTIONS = frozenset({"blocked", "passed", "flagged", "modified", "escalated"})
+
+
+@dataclass
+class GuardPayload:
+    """RFC-0001 — Result of a guard classifier applied to LLM input or output.
+
+    Used with all four guard event types:
+    ``llm.guard.input.blocked``, ``llm.guard.input.passed``,
+    ``llm.guard.output.blocked``, ``llm.guard.output.passed``.
+
+    ``content_hash`` stores a SHA-256 hash of the content that was classified.
+    Raw content MUST NOT be stored.
+    """
+
+    classifier: str
+    direction: str    # "input" | "output"
+    action: str       # "blocked"|"passed"|"flagged"|"modified"|"escalated"
+    score: float
+    score_min: float | None = None
+    score_max: float | None = None
+    threshold: float | None = None
+    categories: list[str] = field(default_factory=list)
+    triggered_categories: list[str] = field(default_factory=list)
+    span_id: str | None = None
+    latency_ms: float | None = None
+    policy_id: str | None = None
+    content_hash: str | None = None  # 64 lowercase hex chars, SHA-256
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.classifier, str) or not self.classifier:
+            raise ValueError("GuardPayload.classifier must be non-empty")
+        if self.direction not in _VALID_DIRECTIONS:
+            raise ValueError(f"GuardPayload.direction must be one of {sorted(_VALID_DIRECTIONS)}")
+        if self.action not in _VALID_ACTIONS:
+            raise ValueError(f"GuardPayload.action must be one of {sorted(_VALID_ACTIONS)}")
+        if not isinstance(self.score, (int, float)):
+            raise ValueError("GuardPayload.score must be a number")  # noqa: TRY004
+        if self.latency_ms is not None and self.latency_ms < 0:
+            raise ValueError("GuardPayload.latency_ms must be non-negative")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "classifier": self.classifier,
+            "direction": self.direction,
+            "action": self.action,
+            "score": self.score,
+        }
+        if self.score_min is not None:
+            d["score_min"] = self.score_min
+        if self.score_max is not None:
+            d["score_max"] = self.score_max
+        if self.threshold is not None:
+            d["threshold"] = self.threshold
+        if self.categories:
+            d["categories"] = list(self.categories)
+        if self.triggered_categories:
+            d["triggered_categories"] = list(self.triggered_categories)
+        if self.span_id is not None:
+            d["span_id"] = self.span_id
+        if self.latency_ms is not None:
+            d["latency_ms"] = self.latency_ms
+        if self.policy_id is not None:
+            d["policy_id"] = self.policy_id
+        if self.content_hash is not None:
+            d["content_hash"] = self.content_hash
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> GuardPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            classifier=data["classifier"],
+            direction=data["direction"],
+            action=data["action"],
+            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,
+            categories=list(data.get("categories", [])),
+            triggered_categories=list(data.get("triggered_categories", [])),
+            span_id=data.get("span_id"),
+            latency_ms=float(data["latency_ms"]) if "latency_ms" in data else None,
+            policy_id=data.get("policy_id"),
+            content_hash=data.get("content_hash"),
+        )

spanforge/namespaces/hitl.py

@@ -0,0 +1,92 @@
+"""spanforge.namespaces.hitl — Human-in-the-Loop namespace payload types (RFC-0001 SPANFORGE).
+
+Classes
+-------
+HITLPayload    hitl.queued / hitl.reviewed / hitl.escalated / hitl.timeout
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+__all__ = ["HITLPayload"]
+
+_VALID_STATUSES = frozenset({"queued", "approved", "rejected", "escalated", "timeout"})
+_VALID_RISK_TIERS = frozenset({"low", "medium", "high", "critical"})
+
+
+@dataclass
+class HITLPayload:
+    """RFC-0001 SPANFORGE — payload for hitl.* events.
+
+    Captures human-in-the-loop review decisions for EU AI Act mandatory
+    human oversight on high-risk AI systems (R — Responsibility).
+    """
+
+    decision_id: str
+    agent_id: str
+    risk_tier: Literal["low", "medium", "high", "critical"]
+    status: Literal["queued", "approved", "rejected", "escalated", "timeout"]
+    reason: str
+    reviewer: str | None = None
+    sla_seconds: int = 3600
+    queued_at: str | None = None  # ISO 8601
+    resolved_at: str | None = None  # ISO 8601
+    escalation_tier: int = 0
+    confidence: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.decision_id:
+            raise ValueError("HITLPayload.decision_id must be non-empty")
+        if not self.agent_id:
+            raise ValueError("HITLPayload.agent_id must be non-empty")
+        if self.risk_tier not in _VALID_RISK_TIERS:
+            raise ValueError(
+                f"HITLPayload.risk_tier must be one of {sorted(_VALID_RISK_TIERS)}"
+            )
+        if self.status not in _VALID_STATUSES:
+            raise ValueError(
+                f"HITLPayload.status must be one of {sorted(_VALID_STATUSES)}"
+            )
+        if not self.reason:
+            raise ValueError("HITLPayload.reason must be non-empty")
+        if self.sla_seconds <= 0:
+            raise ValueError("HITLPayload.sla_seconds must be > 0")
+        if self.confidence is not None and not (0.0 <= self.confidence <= 1.0):
+            raise ValueError("HITLPayload.confidence must be in [0.0, 1.0]")
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "decision_id": self.decision_id,
+            "agent_id": self.agent_id,
+            "risk_tier": self.risk_tier,
+            "status": self.status,
+            "reason": self.reason,
+            "sla_seconds": self.sla_seconds,
+            "escalation_tier": self.escalation_tier,
+        }
+        if self.reviewer is not None:
+            d["reviewer"] = self.reviewer
+        if self.queued_at is not None:
+            d["queued_at"] = self.queued_at
+        if self.resolved_at is not None:
+            d["resolved_at"] = self.resolved_at
+        if self.confidence is not None:
+            d["confidence"] = self.confidence
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> HITLPayload:
+        return cls(
+            decision_id=data["decision_id"],
+            agent_id=data["agent_id"],
+            risk_tier=data["risk_tier"],
+            status=data["status"],
+            reason=data["reason"],
+            reviewer=data.get("reviewer"),
+            sla_seconds=int(data.get("sla_seconds", 3600)),
+            queued_at=data.get("queued_at"),
+            resolved_at=data.get("resolved_at"),
+            escalation_tier=int(data.get("escalation_tier", 0)),
+            confidence=data.get("confidence"),
+        )