spanforge 1.0.0__py3-none-any.whl

spanforge/namespaces/guard.py

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

spanforge/namespaces/latency.py

@@ -0,0 +1,72 @@
+"""spanforge.namespaces.latency \u2014 Latency namespace payload types (RFC-0001 SPANFORGE).
+
+Classes
+-------
+LatencyPayload  latency.sample / latency.sla_breach
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ["LatencyPayload"]
+
+
+@dataclass
+class LatencyPayload:
+    """RFC-0001 SPANFORGE \u2014 payload for latency.* events.
+
+    Captures end-to-end response time, per-step breakdown, and SLA compliance
+    tracking (T \u2014 Traceability / S \u2014 Safety Guardrails).
+    """
+
+    agent_id: str
+    operation: str
+    latency_ms: float
+    sla_target_ms: float
+    sla_met: bool
+    p50_ms: float | None = None
+    p95_ms: float | None = None
+    p99_ms: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.agent_id:
+            raise ValueError("LatencyPayload.agent_id must be non-empty")
+        if not self.operation:
+            raise ValueError("LatencyPayload.operation must be non-empty")
+        if self.latency_ms < 0:
+            raise ValueError("LatencyPayload.latency_ms must be >= 0")
+        if self.sla_target_ms <= 0:
+            raise ValueError("LatencyPayload.sla_target_ms must be > 0")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a plain dict."""
+        d: dict[str, Any] = {
+            "agent_id": self.agent_id,
+            "operation": self.operation,
+            "latency_ms": self.latency_ms,
+            "sla_target_ms": self.sla_target_ms,
+            "sla_met": self.sla_met,
+        }
+        if self.p50_ms is not None:
+            d["p50_ms"] = self.p50_ms
+        if self.p95_ms is not None:
+            d["p95_ms"] = self.p95_ms
+        if self.p99_ms is not None:
+            d["p99_ms"] = self.p99_ms
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> LatencyPayload:
+        """Deserialise from a plain dict."""
+        return cls(
+            agent_id=data["agent_id"],
+            operation=data["operation"],
+            latency_ms=float(data["latency_ms"]),
+            sla_target_ms=float(data["sla_target_ms"]),
+            sla_met=bool(data["sla_met"]),
+            p50_ms=data.get("p50_ms"),
+            p95_ms=data.get("p95_ms"),
+            p99_ms=data.get("p99_ms"),
+        )

spanforge/namespaces/prompt.py

@@ -0,0 +1,190 @@
+"""spanforge.namespaces.prompt — Prompt payload types (RFC-0001).
+
+Classes
+-------
+PromptRenderedPayload       llm.prompt.rendered
+PromptTemplateLoadedPayload llm.prompt.template.loaded
+PromptVersionChangedPayload llm.prompt.version.changed
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "PromptRenderedPayload",
+    "PromptTemplateLoadedPayload",
+    "PromptVersionChangedPayload",
+]
+
+_VALID_SOURCES = frozenset({"registry", "file", "database", "remote_url", "inline"})
+_SHA256_HEX_LEN = 64  # SHA-256 hex digest length (characters)
+
+
+@dataclass
+class PromptRenderedPayload:
+    """RFC-0001 — A prompt template was rendered with variables.
+
+    ``rendered_hash`` is the SHA-256 of the fully-rendered prompt text.
+    The rendered text MUST NOT be stored.
+    """
+
+    template_id: str
+    version: str
+    rendered_hash: str  # 64 lowercase hex chars, SHA-256 of rendered text
+    variable_count: int | None = None
+    variable_names: list[str] = field(default_factory=list)
+    char_count: int | None = None
+    token_estimate: int | None = None
+    language: str | None = None
+    span_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.template_id:
+            raise ValueError("PromptRenderedPayload.template_id must be non-empty")
+        if not self.version:
+            raise ValueError("PromptRenderedPayload.version must be non-empty")
+        if not self.rendered_hash or len(self.rendered_hash) != _SHA256_HEX_LEN:
+            raise ValueError("PromptRenderedPayload.rendered_hash must be 64 hex chars (SHA-256)")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "template_id": self.template_id,
+            "version": self.version,
+            "rendered_hash": self.rendered_hash,
+        }
+        if self.variable_count is not None:
+            d["variable_count"] = self.variable_count
+        if self.variable_names:
+            d["variable_names"] = list(self.variable_names)
+        if self.char_count is not None:
+            d["char_count"] = self.char_count
+        if self.token_estimate is not None:
+            d["token_estimate"] = self.token_estimate
+        if self.language is not None:
+            d["language"] = self.language
+        if self.span_id is not None:
+            d["span_id"] = self.span_id
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PromptRenderedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            template_id=data["template_id"],
+            version=data["version"],
+            rendered_hash=data["rendered_hash"],
+            variable_count=int(data["variable_count"]) if "variable_count" in data else None,
+            variable_names=list(data.get("variable_names", [])),
+            char_count=int(data["char_count"]) if "char_count" in data else None,
+            token_estimate=int(data["token_estimate"]) if "token_estimate" in data else None,
+            language=data.get("language"),
+            span_id=data.get("span_id"),
+        )
+
+
+@dataclass
+class PromptTemplateLoadedPayload:
+    """RFC-0001 — A prompt template was loaded from a source."""
+
+    template_id: str
+    version: str
+    source: str  # "registry"|"file"|"database"|"remote_url"|"inline"
+    template_hash: str | None = None  # 64 hex chars
+    load_duration_ms: float | None = None
+    cache_hit: bool | None = None
+
+    def __post_init__(self) -> None:
+        if not self.template_id:
+            raise ValueError("PromptTemplateLoadedPayload.template_id must be non-empty")
+        if not self.version:
+            raise ValueError("PromptTemplateLoadedPayload.version must be non-empty")
+        if self.source not in _VALID_SOURCES:
+            raise ValueError(
+                f"PromptTemplateLoadedPayload.source must be one of {sorted(_VALID_SOURCES)}"
+            )
+        if self.template_hash is not None and len(self.template_hash) != _SHA256_HEX_LEN:
+            raise ValueError("PromptTemplateLoadedPayload.template_hash must be 64 hex chars")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "template_id": self.template_id,
+            "version": self.version,
+            "source": self.source,
+        }
+        if self.template_hash is not None:
+            d["template_hash"] = self.template_hash
+        if self.load_duration_ms is not None:
+            d["load_duration_ms"] = self.load_duration_ms
+        if self.cache_hit is not None:
+            d["cache_hit"] = self.cache_hit
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PromptTemplateLoadedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            template_id=data["template_id"],
+            version=data["version"],
+            source=data["source"],
+            template_hash=data.get("template_hash"),
+            load_duration_ms=float(data["load_duration_ms"])
+            if "load_duration_ms" in data
+            else None,
+            cache_hit=bool(data["cache_hit"]) if "cache_hit" in data else None,
+        )
+
+
+@dataclass
+class PromptVersionChangedPayload:
+    """RFC-0001 — A prompt template was promoted to a new version."""
+
+    template_id: str
+    previous_version: str
+    new_version: str
+    change_reason: str
+    changed_by: str | None = None
+    previous_hash: str | None = None  # 64 hex chars
+    new_hash: str | None = None  # 64 hex chars
+
+    def __post_init__(self) -> None:
+        if not self.template_id:
+            raise ValueError("PromptVersionChangedPayload.template_id must be non-empty")
+        if not self.previous_version:
+            raise ValueError("PromptVersionChangedPayload.previous_version must be non-empty")
+        if not self.new_version:
+            raise ValueError("PromptVersionChangedPayload.new_version must be non-empty")
+        if not self.change_reason:
+            raise ValueError("PromptVersionChangedPayload.change_reason must be non-empty")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "template_id": self.template_id,
+            "previous_version": self.previous_version,
+            "new_version": self.new_version,
+            "change_reason": self.change_reason,
+        }
+        if self.changed_by is not None:
+            d["changed_by"] = self.changed_by
+        if self.previous_hash is not None:
+            d["previous_hash"] = self.previous_hash
+        if self.new_hash is not None:
+            d["new_hash"] = self.new_hash
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PromptVersionChangedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            template_id=data["template_id"],
+            previous_version=data["previous_version"],
+            new_version=data["new_version"],
+            change_reason=data["change_reason"],
+            changed_by=data.get("changed_by"),
+            previous_hash=data.get("previous_hash"),
+            new_hash=data.get("new_hash"),
+        )

spanforge/namespaces/redact.py

@@ -0,0 +1,173 @@
+"""spanforge.namespaces.redact — Redaction payload types (RFC-0001).
+
+Classes
+-------
+RedactPiiDetectedPayload    llm.redact.pii.detected
+RedactPhiDetectedPayload    llm.redact.phi.detected
+RedactAppliedPayload        llm.redact.applied
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "RedactAppliedPayload",
+    "RedactPhiDetectedPayload",
+    "RedactPiiDetectedPayload",
+]
+
+_VALID_SENSITIVITY_LEVELS = frozenset({"LOW", "MEDIUM", "HIGH", "PII", "PHI"})
+
+
+@dataclass
+class RedactPiiDetectedPayload:
+    """RFC-0001 — PII was detected in an LLM input or output field."""
+
+    detected_categories: list[str]  # minItems=1 — e.g. ["email", "phone"]
+    field_names: list[str]  # minItems=1 — field paths where PII found
+    sensitivity_level: str  # "LOW"|"MEDIUM"|"HIGH"|"PII"|"PHI"
+    detection_count: int | None = None
+    detector: str | None = None
+    subject_event_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.detected_categories:
+            raise ValueError("RedactPiiDetectedPayload.detected_categories must be non-empty")
+        if not self.field_names:
+            raise ValueError("RedactPiiDetectedPayload.field_names must be non-empty")
+        if self.sensitivity_level not in _VALID_SENSITIVITY_LEVELS:
+            raise ValueError(
+                f"RedactPiiDetectedPayload.sensitivity_level must be one of {sorted(_VALID_SENSITIVITY_LEVELS)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "detected_categories": list(self.detected_categories),
+            "field_names": list(self.field_names),
+            "sensitivity_level": self.sensitivity_level,
+        }
+        if self.detection_count is not None:
+            d["detection_count"] = self.detection_count
+        if self.detector is not None:
+            d["detector"] = self.detector
+        if self.subject_event_id is not None:
+            d["subject_event_id"] = self.subject_event_id
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RedactPiiDetectedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            detected_categories=list(data["detected_categories"]),
+            field_names=list(data["field_names"]),
+            sensitivity_level=data["sensitivity_level"],
+            detection_count=int(data["detection_count"]) if "detection_count" in data else None,
+            detector=data.get("detector"),
+            subject_event_id=data.get("subject_event_id"),
+        )
+
+
+@dataclass
+class RedactPhiDetectedPayload:
+    """RFC-0001 — PHI was detected (HIPAA-covered health information).
+
+    ``sensitivity_level`` MUST always be ``"PHI"`` for this payload type.
+    """
+
+    detected_categories: list[str]
+    field_names: list[str]
+    sensitivity_level: str = "PHI"  # MUST be "PHI"
+    detection_count: int | None = None
+    detector: str | None = None
+    subject_event_id: str | None = None
+    hipaa_covered: bool | None = None
+
+    def __post_init__(self) -> None:
+        if not self.detected_categories:
+            raise ValueError("RedactPhiDetectedPayload.detected_categories must be non-empty")
+        if not self.field_names:
+            raise ValueError("RedactPhiDetectedPayload.field_names must be non-empty")
+        if self.sensitivity_level != "PHI":
+            raise ValueError("RedactPhiDetectedPayload.sensitivity_level MUST be 'PHI'")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "detected_categories": list(self.detected_categories),
+            "field_names": list(self.field_names),
+            "sensitivity_level": self.sensitivity_level,
+        }
+        if self.detection_count is not None:
+            d["detection_count"] = self.detection_count
+        if self.detector is not None:
+            d["detector"] = self.detector
+        if self.subject_event_id is not None:
+            d["subject_event_id"] = self.subject_event_id
+        if self.hipaa_covered is not None:
+            d["hipaa_covered"] = self.hipaa_covered
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RedactPhiDetectedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            detected_categories=list(data["detected_categories"]),
+            field_names=list(data["field_names"]),
+            sensitivity_level=data.get("sensitivity_level", "PHI"),
+            detection_count=int(data["detection_count"]) if "detection_count" in data else None,
+            detector=data.get("detector"),
+            subject_event_id=data.get("subject_event_id"),
+            hipaa_covered=bool(data["hipaa_covered"]) if "hipaa_covered" in data else None,
+        )
+
+
+@dataclass
+class RedactAppliedPayload:
+    """RFC-0001 — A redaction policy was applied to one or more fields."""
+
+    policy_min_sensitivity: str  # "LOW"|"MEDIUM"|"HIGH"|"PII"|"PHI"
+    redacted_by: str
+    redacted_count: int
+    redacted_field_names: list[str] = field(default_factory=list)
+    subject_event_id: str | None = None
+    verified: bool | None = None
+
+    def __post_init__(self) -> None:
+        if self.policy_min_sensitivity not in _VALID_SENSITIVITY_LEVELS:
+            raise ValueError(
+                f"RedactAppliedPayload.policy_min_sensitivity must be one of {sorted(_VALID_SENSITIVITY_LEVELS)}"
+            )
+        if not isinstance(self.redacted_by, str) or not self.redacted_by:
+            raise ValueError("RedactAppliedPayload.redacted_by must be non-empty")
+        if not isinstance(self.redacted_count, int) or self.redacted_count < 0:
+            raise ValueError("RedactAppliedPayload.redacted_count must be a non-negative int")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise the payload to a plain ``dict``."""
+        d: dict[str, Any] = {
+            "policy_min_sensitivity": self.policy_min_sensitivity,
+            "redacted_by": self.redacted_by,
+            "redacted_count": self.redacted_count,
+        }
+        if self.redacted_field_names:
+            d["redacted_field_names"] = list(self.redacted_field_names)
+        if self.subject_event_id is not None:
+            d["subject_event_id"] = self.subject_event_id
+        if self.verified is not None:
+            d["verified"] = self.verified
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RedactAppliedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            policy_min_sensitivity=data["policy_min_sensitivity"],
+            redacted_by=data["redacted_by"],
+            redacted_count=int(data["redacted_count"]),
+            redacted_field_names=list(data.get("redacted_field_names", [])),
+            subject_event_id=data.get("subject_event_id"),
+            verified=bool(data["verified"]) if "verified" in data else None,
+        )