spanforge 2.0.0__py3-none-any.whl

spanforge/exceptions.py

@@ -0,0 +1,246 @@
+"""Typed exception hierarchy for spanforge.
+
+All exceptions raised by spanforge inherit from :class:`LLMSchemaError` so
+callers can catch the whole family with a single ``except LLMSchemaError``.
+
+Design rules
+------------
+* Exceptions carry enough context to be actionable — field name, received value,
+  and an explanation of what was expected.
+* HMAC keys and PII-tagged content are **never** embedded in exception messages
+  or ``__cause__`` chains.
+* No bare ``raise`` — every raise site uses a typed subclass.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "AuditStorageError",
+    "DeserializationError",
+    "EgressViolationError",
+    "EventTypeError",
+    "ExportError",
+    "LLMSchemaError",
+    "SchemaValidationError",
+    "SchemaVersionError",
+    "SerializationError",
+    "SigningError",
+    "ULIDError",
+    "VerificationError",
+]
+
+
+class LLMSchemaError(Exception):
+    """Base class for all spanforge exceptions.
+
+    All public-facing exceptions derive from this class, enabling callers to
+    write a single broad ``except LLMSchemaError`` guard as a safety net while
+    still being able to catch specific sub-types for targeted handling.
+    """
+
+
+class SchemaValidationError(LLMSchemaError):
+    """Raised when an :class:`~spanforge.event.Event` fails validation.
+
+    Attributes:
+        field: The dotted field path that failed (e.g. ``"event_id"``).
+        received: The actual value that was provided (redacted if sensitive).
+        reason: Human-readable explanation of the constraint that was violated.
+
+    Example::
+
+        try:
+            event.validate()
+        except SchemaValidationError as exc:
+            logger.error("Invalid event field=%s reason=%s", exc.field, exc.reason)
+    """
+
+    def __init__(self, field: str, received: object, reason: str) -> None:
+        self.field = field
+        self.received = received
+        self.reason = reason
+        super().__init__(
+            f"Validation failed for field '{field}': {reason} "
+            f"(received type={type(received).__name__!r})"
+        )
+
+
+class ULIDError(LLMSchemaError):
+    """Raised when ULID generation or parsing fails.
+
+    Attributes:
+        detail: Human-readable description of the failure.
+
+    This exception is intentionally opaque about internal state to avoid
+    leaking timing information that could aid side-channel attacks.
+    """
+
+    def __init__(self, detail: str) -> None:
+        self.detail = detail
+        super().__init__(f"ULID error: {detail}")
+
+
+class SerializationError(LLMSchemaError):
+    """Raised when an :class:`~spanforge.event.Event` cannot be serialized.
+
+    Attributes:
+        event_id: The ULID of the event that failed (safe to log).
+        reason: Human-readable description of the failure.
+    """
+
+    def __init__(self, event_id: str, reason: str) -> None:
+        self.event_id = event_id
+        self.reason = reason
+        super().__init__(
+            f"Serialization failed for event '{event_id}': {reason}"
+        )
+
+
+class DeserializationError(LLMSchemaError):
+    """Raised when a JSON blob cannot be deserialized into an Event.
+
+    Attributes:
+        reason: Human-readable description of the failure.
+        source_hint: A short, non-PII hint about the source (e.g. filename).
+    """
+
+    def __init__(self, reason: str, source_hint: str = "<unknown>") -> None:
+        self.reason = reason
+        self.source_hint = source_hint
+        super().__init__(
+            f"Deserialization failed (source={source_hint!r}): {reason}"
+        )
+
+
+class EventTypeError(LLMSchemaError):
+    """Raised when an unknown or malformed event type string is encountered.
+
+    Attributes:
+        event_type: The offending event type string.
+        reason: Human-readable description of the failure.
+    """
+
+    def __init__(self, event_type: str, reason: str) -> None:
+        self.event_type = event_type
+        self.reason = reason
+        super().__init__(
+            f"Invalid event type '{event_type}': {reason}"
+        )
+
+
+class SigningError(LLMSchemaError):
+    """Raised when HMAC event signing fails.
+
+    Security: the ``org_secret`` value is **never** included in the message.
+
+    Attributes:
+        reason: Human-readable description of why signing failed.
+    """
+
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"Signing failed: {reason}")
+
+
+class VerificationError(LLMSchemaError):
+    """Raised when an event fails cryptographic verification.
+
+    Raised by :func:`~spanforge.signing.assert_verified` on verification failure.
+
+    Attributes:
+        event_id: The ULID of the event that failed (safe to log).
+    """
+
+    def __init__(self, event_id: str) -> None:
+        self.event_id = event_id
+        super().__init__(
+            f"Event '{event_id}' failed cryptographic verification. "
+            "The event may have been tampered with or the wrong key was used."
+        )
+
+
+class ExportError(LLMSchemaError):
+    """Raised when exporting events to an external backend fails.
+
+    Attributes:
+        backend:  Short identifier for the backend (e.g. ``"otlp"``,
+                  ``"webhook"``, ``"jsonl"``).
+        reason:   Human-readable description of the failure.
+        event_id: The ULID of the event that failed, or ``""`` for batch
+                  failures where no single event is responsible.
+
+    Security: HMAC secrets and PII-tagged payloads are **never** embedded in
+    the message or ``__cause__``.
+
+    Example::
+
+        try:
+            await exporter.export(event)
+        except ExportError as exc:
+            logger.error("backend=%s reason=%s", exc.backend, exc.reason)
+    """
+
+    def __init__(self, backend: str, reason: str, event_id: str = "") -> None:
+        self.backend = backend
+        self.reason = reason
+        self.event_id = event_id
+        msg = f"Export to '{backend}' failed: {reason}"
+        if event_id:
+            msg += f" (event_id={event_id!r})"
+        super().__init__(msg)
+
+
+class SchemaVersionError(LLMSchemaError):
+    """Raised when an event carries an unsupported ``schema_version`` value.
+
+    RFC-0001 §15.5 specifies that v2.0 consumers MUST accept events with
+    ``schema_version`` ``"1.0"`` or ``"2.0"`` and MUST raise this error
+    for any other value.
+
+    Attributes:
+        version: The unsupported schema version string that was encountered.
+
+    Example::
+
+        try:
+            consumer.ingest(event)
+        except SchemaVersionError as exc:
+            logger.warning("Skipping event with unknown version %s", exc.version)
+    """
+
+    def __init__(self, version: str) -> None:
+        self.version = version
+        super().__init__(
+            f"Unsupported schema_version {version!r}. "
+            "Accepted values: '1.0', '2.0' (RFC-0001 §15.5)."
+        )
+
+
+class EgressViolationError(LLMSchemaError):
+    """Raised when an exporter attempts a network call in no-egress mode.
+
+    Attributes:
+        backend: Short identifier for the backend that violated the policy.
+        endpoint: The endpoint URL that was blocked (may be ``""`` if unknown).
+    """
+
+    def __init__(self, backend: str, endpoint: str = "") -> None:
+        self.backend = backend
+        self.endpoint = endpoint
+        msg = f"Egress violation: exporter '{backend}' attempted a network call"
+        if endpoint:
+            msg += f" to {endpoint!r}"
+        msg += " but no_egress mode is active"
+        super().__init__(msg)
+
+
+class AuditStorageError(LLMSchemaError):
+    """Raised when the audit log storage layer detects a violation.
+
+    Attributes:
+        reason: Human-readable description of the storage violation.
+    """
+
+    def __init__(self, reason: str) -> None:
+        self.reason = reason
+        super().__init__(f"Audit storage error: {reason}")

spanforge/explain.py

@@ -0,0 +1,181 @@
+"""spanforge.explain — Explainability record generation for AI compliance.
+
+Aggregates decision drivers from span payloads into human-readable
+explanations compliant with EU AI Act transparency requirements
+(Articles 13-14) and the T.R.U.S.T. Framework Transparency pillar.
+
+Emits ``explanation.generated`` events into the HMAC audit chain.
+
+Usage::
+
+    from spanforge.explain import ExplainabilityRecord
+
+    record = ExplainabilityRecord(
+        trace_id="01HQZF...",
+        agent_id="support-agent@1.0",
+        decision_id="01HQZF...",
+        factors=[
+            {"factor_name": "user_intent", "weight": 0.6,
+             "contribution": 0.42, "evidence": "keyword match",
+             "confidence": 0.85},
+        ],
+        summary="Routed to billing team based on keyword match.",
+    )
+    print(record.to_text())
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "ExplainabilityRecord",
+    "generate_explanation",
+]
+
+
+@dataclass
+class ExplainabilityRecord:
+    """A human-readable explanation of one or more AI decisions.
+
+    Designed to satisfy EU AI Act Art. 13 transparency obligations.
+    Each record can be serialised to plain text, JSON, or dict for
+    audit trail inclusion.
+    """
+
+    trace_id: str
+    agent_id: str
+    decision_id: str
+    factors: list[dict[str, Any]]
+    summary: str
+    model_id: str | None = None
+    confidence: float | None = None
+    risk_tier: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.trace_id:
+            raise ValueError("ExplainabilityRecord.trace_id must be non-empty")
+        if not self.agent_id:
+            raise ValueError("ExplainabilityRecord.agent_id must be non-empty")
+        if not self.decision_id:
+            raise ValueError("ExplainabilityRecord.decision_id must be non-empty")
+        if not self.summary:
+            raise ValueError("ExplainabilityRecord.summary must be non-empty")
+        if self.confidence is not None and not (0.0 <= self.confidence <= 1.0):
+            raise ValueError(
+                "ExplainabilityRecord.confidence must be in [0.0, 1.0]"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a plain dict."""
+        d: dict[str, Any] = {
+            "trace_id": self.trace_id,
+            "agent_id": self.agent_id,
+            "decision_id": self.decision_id,
+            "factors": self.factors,
+            "summary": self.summary,
+        }
+        if self.model_id is not None:
+            d["model_id"] = self.model_id
+        if self.confidence is not None:
+            d["confidence"] = self.confidence
+        if self.risk_tier is not None:
+            d["risk_tier"] = self.risk_tier
+        if self.metadata:
+            d["metadata"] = self.metadata
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ExplainabilityRecord:
+        """Reconstruct from a plain dict."""
+        return cls(
+            trace_id=data["trace_id"],
+            agent_id=data["agent_id"],
+            decision_id=data["decision_id"],
+            factors=data.get("factors", []),
+            summary=data["summary"],
+            model_id=data.get("model_id"),
+            confidence=data.get("confidence"),
+            risk_tier=data.get("risk_tier"),
+            metadata=data.get("metadata", {}),
+        )
+
+    def to_json(self) -> str:
+        """Serialise to JSON string."""
+        return json.dumps(self.to_dict(), default=str)
+
+    def to_text(self) -> str:
+        """Generate a human-readable explanation text.
+
+        Returns a multi-line string suitable for end-user display or
+        compliance documentation.
+        """
+        lines: list[str] = []
+        lines.append(f"Explanation for decision {self.decision_id}")
+        lines.append(f"  Agent: {self.agent_id}")
+        lines.append(f"  Trace: {self.trace_id}")
+        if self.model_id:
+            lines.append(f"  Model: {self.model_id}")
+        if self.confidence is not None:
+            lines.append(f"  Confidence: {self.confidence:.2%}")
+        if self.risk_tier:
+            lines.append(f"  Risk tier: {self.risk_tier}")
+        lines.append(f"  Summary: {self.summary}")
+        if self.factors:
+            lines.append("  Contributing factors:")
+            for f in self.factors:
+                name = f.get("factor_name", "unknown")
+                weight = f.get("weight", 0)
+                evidence = f.get("evidence", "")
+                lines.append(f"    - {name} (weight={weight:.2f}): {evidence}")
+        return "\n".join(lines)
+
+
+def generate_explanation(
+    trace_id: str,
+    agent_id: str,
+    decision_id: str,
+    factors: list[dict[str, Any]],
+    summary: str,
+    *,
+    model_id: str | None = None,
+    confidence: float | None = None,
+    risk_tier: str | None = None,
+    auto_emit: bool = True,
+    metadata: dict[str, Any] | None = None,
+) -> ExplainabilityRecord:
+    """Create an :class:`ExplainabilityRecord` and optionally emit an event.
+
+    This is the primary convenience function for the explainability module.
+    """
+    record = ExplainabilityRecord(
+        trace_id=trace_id,
+        agent_id=agent_id,
+        decision_id=decision_id,
+        factors=factors,
+        summary=summary,
+        model_id=model_id,
+        confidence=confidence,
+        risk_tier=risk_tier,
+        metadata=metadata or {},
+    )
+    if auto_emit:
+        _emit_explanation(record)
+    return record
+
+
+def _emit_explanation(record: ExplainabilityRecord) -> None:
+    """Emit an explanation.generated event into the HMAC audit chain."""
+    try:
+        from spanforge._stream import emit_rfc_event  # noqa: PLC0415
+        from spanforge.types import EventType  # noqa: PLC0415
+
+        try:
+            emit_rfc_event(EventType.EXPLANATION_GENERATED, record.to_dict())
+        except Exception:  # noqa: BLE001
+            pass
+    except ImportError:
+        pass

spanforge/export/__init__.py

@@ -0,0 +1,50 @@
+"""RFC-0001 export backends for spanforge SDK events.
+
+All exporters are **opt-in** — importing this package does not open any network
+connections or file handles.  Instantiate an exporter explicitly to activate it.
+
+Core exporters (RFC-0001 §14)
+------------------------------
+* :class:`~spanforge.export.otlp.OTLPExporter` — OTLP/JSON HTTP exporter
+  (zero dependencies; builds OTLP wire format from stdlib).
+* :class:`~spanforge.export.otel_bridge.OTelBridgeExporter` — OTel SDK bridge
+  that emits real OTel spans via a configured ``TracerProvider``.
+  Requires ``pip install "spanforge[otel]"``.
+* :class:`~spanforge.export.webhook.WebhookExporter` — HTTP webhook with
+  HMAC-SHA256 request signing.
+* :class:`~spanforge.export.jsonl.JSONLExporter` — NDJSON for local development
+  and audit trail persistence.
+"""
+
+from __future__ import annotations
+
+from spanforge.export.append_only import (
+    AppendOnlyJSONLExporter,
+    WORMBackend,
+    WORMUploadResult,
+)
+from spanforge.export.datadog import DatadogExporter, DatadogResourceAttributes
+from spanforge.export.grafana import GrafanaLokiExporter
+from spanforge.export.jsonl import JSONLExporter
+from spanforge.export.otlp import OTLPExporter, ResourceAttributes
+from spanforge.export.webhook import WebhookExporter
+
+# OTelBridgeExporter is an optional import — requires opentelemetry-sdk
+try:
+    from spanforge.export.otel_bridge import OTelBridgeExporter
+except ImportError:
+    OTelBridgeExporter = None  # type: ignore[assignment,misc]
+
+__all__ = [
+    "AppendOnlyJSONLExporter",
+    "DatadogExporter",
+    "DatadogResourceAttributes",
+    "GrafanaLokiExporter",
+    "JSONLExporter",
+    "OTLPExporter",
+    "OTelBridgeExporter",
+    "ResourceAttributes",
+    "WORMBackend",
+    "WORMUploadResult",
+    "WebhookExporter",
+]