spanforge 1.0.0__py3-none-any.whl

spanforge/namespaces/audit.py

@@ -0,0 +1,256 @@
+"""spanforge.namespaces.audit — Audit chain payload types (RFC-0001 §11 + RFC-0001 SPANFORGE).
+
+Classes
+-------
+AuditKeyRotatedPayload      llm.audit.key.rotated
+AuditChainVerifiedPayload   llm.audit.chain.verified
+AuditChainTamperedPayload   llm.audit.chain.tampered
+AuditChainPayload           audit.event_signed / audit.chain_verified / audit.tamper_detected
+                            RFC-0001 SPANFORGE tamper-evident cross-reference chain
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "AuditChainPayload",
+    "AuditChainTamperedPayload",
+    "AuditChainVerifiedPayload",
+    "AuditKeyRotatedPayload",
+]
+
+_VALID_ROTATION_REASONS = frozenset(
+    {"scheduled", "suspected_compromise", "policy_update", "key_expiry", "manual"}
+)
+_VALID_SEVERITIES = frozenset({"low", "medium", "high", "critical"})
+
+
+@dataclass
+class AuditKeyRotatedPayload:
+    """RFC-0001 §11.5 — An HMAC signing key was rotated.
+
+    ``key_algorithm`` defaults to ``"HMAC-SHA256"`` (the only algorithm
+    mandated by the RFC).  ``effective_from_event_id`` is the ULID of the
+    first event signed with the new key.
+    """
+
+    key_id: str
+    previous_key_id: str
+    rotated_at: str  # ISO 8601 timestamp with exactly 6 decimal places
+    rotated_by: str
+    rotation_reason: str | None = None
+    key_algorithm: str = "HMAC-SHA256"
+    effective_from_event_id: str | None = None  # ULID
+
+    def __post_init__(self) -> None:
+        if not self.key_id:
+            raise ValueError("AuditKeyRotatedPayload.key_id must be non-empty")
+        if not self.previous_key_id:
+            raise ValueError("AuditKeyRotatedPayload.previous_key_id must be non-empty")
+        if not self.rotated_at:
+            raise ValueError("AuditKeyRotatedPayload.rotated_at must be non-empty")
+        if not self.rotated_by:
+            raise ValueError("AuditKeyRotatedPayload.rotated_by must be non-empty")
+        if self.rotation_reason is not None and self.rotation_reason not in _VALID_ROTATION_REASONS:
+            raise ValueError(
+                f"AuditKeyRotatedPayload.rotation_reason must be one of {sorted(_VALID_ROTATION_REASONS)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "key_id": self.key_id,
+            "previous_key_id": self.previous_key_id,
+            "rotated_at": self.rotated_at,
+            "rotated_by": self.rotated_by,
+            "key_algorithm": self.key_algorithm,
+        }
+        if self.rotation_reason is not None:
+            d["rotation_reason"] = self.rotation_reason
+        if self.effective_from_event_id is not None:
+            d["effective_from_event_id"] = self.effective_from_event_id
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditKeyRotatedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_id=data["key_id"],
+            previous_key_id=data["previous_key_id"],
+            rotated_at=data["rotated_at"],
+            rotated_by=data["rotated_by"],
+            rotation_reason=data.get("rotation_reason"),
+            key_algorithm=data.get("key_algorithm", "HMAC-SHA256"),
+            effective_from_event_id=data.get("effective_from_event_id"),
+        )
+
+
+@dataclass
+class AuditChainVerifiedPayload:
+    """RFC-0001 §11 — An audit chain segment was verified intact."""
+
+    verified_from_event_id: str
+    verified_to_event_id: str
+    event_count: int
+    verified_at: str
+    verified_by: str
+
+    def __post_init__(self) -> None:
+        if not self.verified_from_event_id:
+            raise ValueError("AuditChainVerifiedPayload.verified_from_event_id must be non-empty")
+        if not self.verified_to_event_id:
+            raise ValueError("AuditChainVerifiedPayload.verified_to_event_id must be non-empty")
+        if not isinstance(self.event_count, int) or self.event_count < 0:
+            raise ValueError("AuditChainVerifiedPayload.event_count must be a non-negative int")
+        if not self.verified_at:
+            raise ValueError("AuditChainVerifiedPayload.verified_at must be non-empty")
+        if not self.verified_by:
+            raise ValueError("AuditChainVerifiedPayload.verified_by must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        return {
+            "verified_from_event_id": self.verified_from_event_id,
+            "verified_to_event_id": self.verified_to_event_id,
+            "event_count": self.event_count,
+            "verified_at": self.verified_at,
+            "verified_by": self.verified_by,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditChainVerifiedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            verified_from_event_id=data["verified_from_event_id"],
+            verified_to_event_id=data["verified_to_event_id"],
+            event_count=int(data["event_count"]),
+            verified_at=data["verified_at"],
+            verified_by=data["verified_by"],
+        )
+
+
+@dataclass
+class AuditChainTamperedPayload:
+    """RFC-0001 §11 — Tampering or a gap was detected in the audit chain."""
+
+    first_tampered_event_id: str
+    tampered_count: int
+    detected_at: str
+    detected_by: str
+    gap_count: int | None = None
+    gap_prev_ids: list[str] = field(default_factory=list)
+    severity: str | None = None  # "low"|"medium"|"high"|"critical"
+
+    def __post_init__(self) -> None:
+        if not self.first_tampered_event_id:
+            raise ValueError("AuditChainTamperedPayload.first_tampered_event_id must be non-empty")
+        if not isinstance(self.tampered_count, int) or self.tampered_count < 0:
+            raise ValueError("AuditChainTamperedPayload.tampered_count must be a non-negative int")
+        if not self.detected_at:
+            raise ValueError("AuditChainTamperedPayload.detected_at must be non-empty")
+        if not self.detected_by:
+            raise ValueError("AuditChainTamperedPayload.detected_by must be non-empty")
+        if self.severity is not None and self.severity not in _VALID_SEVERITIES:
+            raise ValueError(
+                f"AuditChainTamperedPayload.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] = {
+            "first_tampered_event_id": self.first_tampered_event_id,
+            "tampered_count": self.tampered_count,
+            "detected_at": self.detected_at,
+            "detected_by": self.detected_by,
+        }
+        if self.gap_count is not None:
+            d["gap_count"] = self.gap_count
+        if self.gap_prev_ids:
+            d["gap_prev_ids"] = list(self.gap_prev_ids)
+        if self.severity is not None:
+            d["severity"] = self.severity
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditChainTamperedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            first_tampered_event_id=data["first_tampered_event_id"],
+            tampered_count=int(data["tampered_count"]),
+            detected_at=data["detected_at"],
+            detected_by=data["detected_by"],
+            gap_count=int(data["gap_count"]) if "gap_count" in data else None,
+            gap_prev_ids=list(data.get("gap_prev_ids", [])),
+            severity=data.get("severity"),
+        )
+
+
+@dataclass
+class AuditChainPayload:
+    """RFC-0001 SPANFORGE — tamper-evident cross-reference audit chain event.
+
+    Every event emitted in the 10 RFC-0001 SPANFORGE namespaces is cross-
+    referenced into this immutable audit chain.  Each entry holds the HMAC
+    of the referenced event and the chained HMAC of all prior chain entries,
+    making any post-emission mutation detectable.
+
+    Events:
+        audit.event_signed      — a new event was appended to the chain
+        audit.chain_verified    — a chain segment was verified intact
+        audit.tamper_detected   — a break in the HMAC sequence was detected
+    """
+
+    event_id: str  # ULID of the referenced event
+    event_type: str  # wire event type string of the referenced event
+    event_hmac: str  # HMAC-SHA256 of the referenced event canonical JSON
+    chain_position: int  # monotonically increasing position in the chain
+    signer_id: str  # identity of the signing service / key ID
+    signed_at: str  # ISO 8601 timestamp with 6 decimal places
+    prev_chain_hmac: str | None = None  # HMAC of the previous chain entry; None for entry 0
+
+    def __post_init__(self) -> None:
+        if not self.event_id:
+            raise ValueError("AuditChainPayload.event_id must be non-empty")
+        if not self.event_type:
+            raise ValueError("AuditChainPayload.event_type must be non-empty")
+        if not self.event_hmac:
+            raise ValueError("AuditChainPayload.event_hmac must be non-empty")
+        if not isinstance(self.chain_position, int) or self.chain_position < 0:
+            raise ValueError("AuditChainPayload.chain_position must be a non-negative int")
+        if not self.signer_id:
+            raise ValueError("AuditChainPayload.signer_id must be non-empty")
+        if not self.signed_at:
+            raise ValueError("AuditChainPayload.signed_at must be non-empty")
+        if self.chain_position > 0 and not self.prev_chain_hmac:
+            raise ValueError(
+                "AuditChainPayload.prev_chain_hmac is required when chain_position > 0"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "event_id": self.event_id,
+            "event_type": self.event_type,
+            "event_hmac": self.event_hmac,
+            "chain_position": self.chain_position,
+            "signer_id": self.signer_id,
+            "signed_at": self.signed_at,
+        }
+        if self.prev_chain_hmac is not None:
+            d["prev_chain_hmac"] = self.prev_chain_hmac
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AuditChainPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            event_id=data["event_id"],
+            event_type=data["event_type"],
+            event_hmac=data["event_hmac"],
+            chain_position=int(data["chain_position"]),
+            signer_id=data["signer_id"],
+            signed_at=data["signed_at"],
+            prev_chain_hmac=data.get("prev_chain_hmac"),
+        )

spanforge/namespaces/cache.py

@@ -0,0 +1,237 @@
+"""spanforge.namespaces.cache — Cache payload types (RFC-0001).
+
+Classes
+-------
+CacheHitPayload     llm.cache.hit
+CacheMissPayload    llm.cache.miss
+CacheEvictedPayload llm.cache.evicted
+CacheWrittenPayload llm.cache.written
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from spanforge.namespaces.trace import CostBreakdown, ModelInfo, TokenUsage
+
+__all__ = [
+    "CacheEvictedPayload",
+    "CacheHitPayload",
+    "CacheMissPayload",
+    "CacheWrittenPayload",
+]
+
+_VALID_EVICTION_REASONS = frozenset(
+    {
+        "ttl_expired",
+        "lru_eviction",
+        "manual_invalidation",
+        "capacity_exceeded",
+        "schema_upgrade",
+    }
+)
+
+
+@dataclass
+class CacheHitPayload:
+    """Payload for llm.cache.hit — semantic cache lookup succeeded."""
+
+    key_hash: str
+    namespace: str
+    similarity_score: float
+    ttl_remaining_seconds: int | None = None
+    cached_model: ModelInfo | None = None
+    cost_saved: CostBreakdown | None = None
+    tokens_saved: TokenUsage | None = None
+    lookup_duration_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.key_hash:
+            raise ValueError("CacheHitPayload.key_hash must be non-empty")
+        if not self.namespace:
+            raise ValueError("CacheHitPayload.namespace must be non-empty")
+        if not (0.0 <= self.similarity_score <= 1.0):
+            raise ValueError("CacheHitPayload.similarity_score must be in [0,1]")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "key_hash": self.key_hash,
+            "namespace": self.namespace,
+            "similarity_score": self.similarity_score,
+        }
+        if self.ttl_remaining_seconds is not None:
+            d["ttl_remaining_seconds"] = self.ttl_remaining_seconds
+        if self.cached_model is not None:
+            d["cached_model"] = self.cached_model.to_dict()
+        if self.cost_saved is not None:
+            d["cost_saved"] = self.cost_saved.to_dict()
+        if self.tokens_saved is not None:
+            d["tokens_saved"] = self.tokens_saved.to_dict()
+        if self.lookup_duration_ms is not None:
+            d["lookup_duration_ms"] = self.lookup_duration_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CacheHitPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_hash=data["key_hash"],
+            namespace=data["namespace"],
+            similarity_score=float(data["similarity_score"]),
+            ttl_remaining_seconds=int(data["ttl_remaining_seconds"])
+            if "ttl_remaining_seconds" in data
+            else None,
+            cached_model=ModelInfo.from_dict(data["cached_model"])
+            if "cached_model" in data
+            else None,
+            cost_saved=CostBreakdown.from_dict(data["cost_saved"])
+            if "cost_saved" in data
+            else None,
+            tokens_saved=TokenUsage.from_dict(data["tokens_saved"])
+            if "tokens_saved" in data
+            else None,
+            lookup_duration_ms=float(data["lookup_duration_ms"])
+            if "lookup_duration_ms" in data
+            else None,
+        )
+
+
+@dataclass
+class CacheMissPayload:
+    """Payload for llm.cache.miss — semantic cache lookup failed."""
+
+    key_hash: str
+    namespace: str
+    best_similarity_score: float | None = None
+    similarity_threshold: float | None = None
+    lookup_duration_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.key_hash:
+            raise ValueError("CacheMissPayload.key_hash must be non-empty")
+        if not self.namespace:
+            raise ValueError("CacheMissPayload.namespace must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {"key_hash": self.key_hash, "namespace": self.namespace}
+        if self.best_similarity_score is not None:
+            d["best_similarity_score"] = self.best_similarity_score
+        if self.similarity_threshold is not None:
+            d["similarity_threshold"] = self.similarity_threshold
+        if self.lookup_duration_ms is not None:
+            d["lookup_duration_ms"] = self.lookup_duration_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CacheMissPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_hash=data["key_hash"],
+            namespace=data["namespace"],
+            best_similarity_score=float(data["best_similarity_score"])
+            if "best_similarity_score" in data
+            else None,
+            similarity_threshold=float(data["similarity_threshold"])
+            if "similarity_threshold" in data
+            else None,
+            lookup_duration_ms=float(data["lookup_duration_ms"])
+            if "lookup_duration_ms" in data
+            else None,
+        )
+
+
+@dataclass
+class CacheEvictedPayload:
+    """Payload for llm.cache.evicted — a cache entry was removed."""
+
+    key_hash: str
+    namespace: str
+    eviction_reason: str
+    entry_age_seconds: int | None = None
+
+    def __post_init__(self) -> None:
+        if not self.key_hash:
+            raise ValueError("CacheEvictedPayload.key_hash must be non-empty")
+        if not self.namespace:
+            raise ValueError("CacheEvictedPayload.namespace must be non-empty")
+        if self.eviction_reason not in _VALID_EVICTION_REASONS:
+            raise ValueError(
+                f"CacheEvictedPayload.eviction_reason must be one of {sorted(_VALID_EVICTION_REASONS)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "key_hash": self.key_hash,
+            "namespace": self.namespace,
+            "eviction_reason": self.eviction_reason,
+        }
+        if self.entry_age_seconds is not None:
+            d["entry_age_seconds"] = self.entry_age_seconds
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CacheEvictedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_hash=data["key_hash"],
+            namespace=data["namespace"],
+            eviction_reason=data["eviction_reason"],
+            entry_age_seconds=int(data["entry_age_seconds"])
+            if "entry_age_seconds" in data
+            else None,
+        )
+
+
+@dataclass
+class CacheWrittenPayload:
+    """Payload for llm.cache.written — a response was written to cache."""
+
+    key_hash: str
+    namespace: str
+    ttl_seconds: int
+    model: ModelInfo | None = None
+    response_token_count: int | None = None
+    write_duration_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.key_hash:
+            raise ValueError("CacheWrittenPayload.key_hash must be non-empty")
+        if not self.namespace:
+            raise ValueError("CacheWrittenPayload.namespace must be non-empty")
+        if not isinstance(self.ttl_seconds, int) or self.ttl_seconds < 0:
+            raise ValueError("CacheWrittenPayload.ttl_seconds must be a non-negative int")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "key_hash": self.key_hash,
+            "namespace": self.namespace,
+            "ttl_seconds": self.ttl_seconds,
+        }
+        if self.model is not None:
+            d["model"] = self.model.to_dict()
+        if self.response_token_count is not None:
+            d["response_token_count"] = self.response_token_count
+        if self.write_duration_ms is not None:
+            d["write_duration_ms"] = self.write_duration_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CacheWrittenPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            key_hash=data["key_hash"],
+            namespace=data["namespace"],
+            ttl_seconds=int(data["ttl_seconds"]),
+            model=ModelInfo.from_dict(data["model"]) if "model" in data else None,
+            response_token_count=int(data["response_token_count"])
+            if "response_token_count" in data
+            else None,
+            write_duration_ms=float(data["write_duration_ms"])
+            if "write_duration_ms" in data
+            else None,
+        )

spanforge/namespaces/chain.py

@@ -0,0 +1,77 @@
+"""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]:
+        """Serialise to a plain dict."""
+        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:
+        """Deserialise from a plain dict."""
+        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,72 @@
+"""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]:
+        """Serialise to a plain dict."""
+        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:
+        """Deserialise from a plain dict."""
+        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"),
+        )