spanforge 2.0.0__py3-none-any.whl

spanforge/namespaces/latency.py

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

spanforge/namespaces/template.py

@@ -0,0 +1,197 @@
+"""spanforge.namespaces.template — Template payload types (RFC-0001).
+
+Classes
+-------
+TemplateRegisteredPayload       llm.template.registered
+TemplateVariableBoundPayload    llm.template.variable.bound
+TemplateValidationFailedPayload llm.template.validation.failed
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "TemplateRegisteredPayload",
+    "TemplateValidationFailedPayload",
+    "TemplateVariableBoundPayload",
+]
+
+_VALID_VALUE_TYPES = frozenset({
+    "string", "integer", "float", "boolean", "array", "object", "null"
+})
+_VALID_FAILURE_TYPES = frozenset({
+    "missing_variable", "type_mismatch", "hash_mismatch",
+    "version_not_found", "syntax_error", "schema_violation"
+})
+
+_SHA256_HEX_LEN = 64  # SHA-256 hex digest length (characters)
+
+
+@dataclass
+class TemplateRegisteredPayload:
+    """RFC-0001 — A prompt template was registered in the registry."""
+
+    template_id: str
+    version: str
+    template_hash: str  # 64 lowercase hex chars, SHA-256 of template source
+    variable_names: list[str] = field(default_factory=list)
+    variable_count: int | None = None
+    language: str | None = None
+    char_count: int | None = None
+    registered_by: str | None = None
+    is_active: bool | None = None
+    tags: dict[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.template_id:
+            raise ValueError("TemplateRegisteredPayload.template_id must be non-empty")
+        if not self.version:
+            raise ValueError("TemplateRegisteredPayload.version must be non-empty")
+        if not self.template_hash or len(self.template_hash) != _SHA256_HEX_LEN:
+            raise ValueError("TemplateRegisteredPayload.template_hash must be 64 hex chars (SHA-256)")  # noqa: E501
+
+    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,
+            "template_hash": self.template_hash,
+        }
+        if self.variable_names:
+            d["variable_names"] = list(self.variable_names)
+        if self.variable_count is not None:
+            d["variable_count"] = self.variable_count
+        if self.language is not None:
+            d["language"] = self.language
+        if self.char_count is not None:
+            d["char_count"] = self.char_count
+        if self.registered_by is not None:
+            d["registered_by"] = self.registered_by
+        if self.is_active is not None:
+            d["is_active"] = self.is_active
+        if self.tags is not None:
+            d["tags"] = dict(self.tags)
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TemplateRegisteredPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            template_id=data["template_id"],
+            version=data["version"],
+            template_hash=data["template_hash"],
+            variable_names=list(data.get("variable_names", [])),
+            variable_count=int(data["variable_count"]) if "variable_count" in data else None,
+            language=data.get("language"),
+            char_count=int(data["char_count"]) if "char_count" in data else None,
+            registered_by=data.get("registered_by"),
+            is_active=bool(data["is_active"]) if "is_active" in data else None,
+            tags=dict(data["tags"]) if "tags" in data else None,
+        )
+
+
+@dataclass
+class TemplateVariableBoundPayload:
+    """RFC-0001 — A variable was bound to a value for template rendering.
+
+    ``value_hash`` stores a SHA-256 hash of the value. For sensitive variables,
+    the raw value MUST NOT be stored.
+    """
+
+    template_id: str
+    version: str
+    variable_name: str
+    value_type: str | None = None  # "string"|"integer"|"float"|"boolean"|"array"|"object"|"null"
+    value_length: int | None = None
+    value_hash: str | None = None  # 64 hex chars, SHA-256
+    is_sensitive: bool | None = None
+    span_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.template_id:
+            raise ValueError("TemplateVariableBoundPayload.template_id must be non-empty")
+        if not self.version:
+            raise ValueError("TemplateVariableBoundPayload.version must be non-empty")
+        if not self.variable_name:
+            raise ValueError("TemplateVariableBoundPayload.variable_name must be non-empty")
+        if self.value_type is not None and self.value_type not in _VALID_VALUE_TYPES:
+            raise ValueError(f"TemplateVariableBoundPayload.value_type must be one of {sorted(_VALID_VALUE_TYPES)}")  # noqa: E501
+        if self.value_hash is not None and len(self.value_hash) != _SHA256_HEX_LEN:
+            raise ValueError("TemplateVariableBoundPayload.value_hash must be 64 hex chars (SHA-256)")  # noqa: E501
+
+    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,
+            "variable_name": self.variable_name,
+        }
+        if self.value_type is not None:
+            d["value_type"] = self.value_type
+        if self.value_length is not None:
+            d["value_length"] = self.value_length
+        if self.value_hash is not None:
+            d["value_hash"] = self.value_hash
+        if self.is_sensitive is not None:
+            d["is_sensitive"] = self.is_sensitive
+        if self.span_id is not None:
+            d["span_id"] = self.span_id
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TemplateVariableBoundPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            template_id=data["template_id"],
+            version=data["version"],
+            variable_name=data["variable_name"],
+            value_type=data.get("value_type"),
+            value_length=int(data["value_length"]) if "value_length" in data else None,
+            value_hash=data.get("value_hash"),
+            is_sensitive=bool(data["is_sensitive"]) if "is_sensitive" in data else None,
+            span_id=data.get("span_id"),
+        )
+
+
+@dataclass
+class TemplateValidationFailedPayload:
+    """RFC-0001 — Template validation failed during rendering or registration."""
+
+    template_id: str
+    version: str
+    failure_reason: str
+    failure_type: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.template_id:
+            raise ValueError("TemplateValidationFailedPayload.template_id must be non-empty")
+        if not self.version:
+            raise ValueError("TemplateValidationFailedPayload.version must be non-empty")
+        if not self.failure_reason:
+            raise ValueError("TemplateValidationFailedPayload.failure_reason must be non-empty")
+        if self.failure_type is not None and self.failure_type not in _VALID_FAILURE_TYPES:
+            raise ValueError(
+                f"TemplateValidationFailedPayload.failure_type must be one of {sorted(_VALID_FAILURE_TYPES)}"  # noqa: E501
+            )
+
+    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,
+            "failure_reason": self.failure_reason,
+        }
+        if self.failure_type is not None:
+            d["failure_type"] = self.failure_type
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TemplateValidationFailedPayload:
+        """Deserialise from a plain ``dict``."""
+        return cls(
+            template_id=data["template_id"],
+            version=data["version"],
+            failure_reason=data["failure_reason"],
+            failure_type=data.get("failure_type"),
+        )