spanforge 1.0.0__py3-none-any.whl

spanforge/governance.py

@@ -0,0 +1,181 @@
+"""spanforge.governance — Policy-based event governance.
+
+Block prohibited event types, warn on deprecated usage, and enforce custom
+domain rules before events are emitted.
+
+Public API
+----------
+EventGovernancePolicy     Mutable policy dataclass.
+GovernanceViolationError  Raised when a policy blocks an event.
+GovernanceWarning         Warning issued for deprecated event types.
+get_global_policy()       Return the global policy singleton.
+set_global_policy()       Replace (or reset) the global policy.
+check_event()             Apply the global policy to an event.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from spanforge.event import Event
+
+__all__ = [
+    "EventGovernancePolicy",
+    "GovernanceViolationError",
+    "GovernanceWarning",
+    "check_event",
+    "get_global_policy",
+    "set_global_policy",
+]
+
+
+# ---------------------------------------------------------------------------
+# Exceptions / Warnings
+# ---------------------------------------------------------------------------
+
+
+class GovernanceViolationError(Exception):
+    """Raised when an event is blocked by a governance policy.
+
+    Attributes:
+        event_type: The ``event_type`` string of the blocked event.
+        reason:     Human-readable description of why the event was blocked.
+    """
+
+    def __init__(self, event_type: str, reason: str) -> None:
+        super().__init__(f"Event '{event_type}' blocked: {reason}")
+        self.event_type = event_type
+        self.reason = reason
+
+
+class GovernanceWarning(UserWarning):
+    """Warning issued via :func:`warnings.warn` when a deprecated event type is seen.
+
+    In pytest with ``filterwarnings = ["error"]`` this is automatically promoted
+    to an exception.  Use ``pytest.warns(GovernanceWarning)`` to assert on it.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Policy dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class EventGovernancePolicy:
+    """Mutable policy controlling which events are blocked or warned about.
+
+    Attributes:
+        blocked_types:   Event type strings rejected unconditionally.
+        warn_deprecated: Event type strings that emit a :class:`GovernanceWarning`.
+        custom_rules:    Callables ``rule(event) -> str | None``; returning a
+                         non-empty string blocks the event with that reason.
+        strict_unknown:  When ``True``, any event whose type is not a registered
+                         ``EventType`` value is blocked.
+    """
+
+    blocked_types: set[str] = field(default_factory=set)
+    warn_deprecated: set[str] = field(default_factory=set)
+    custom_rules: list[Callable[[Event], str | None]] = field(default_factory=list)
+    strict_unknown: bool = False
+
+    def check_event(self, event: Event) -> None:
+        """Evaluate all rules in this policy against *event*.
+
+        Evaluation order:
+
+        1. **blocked_types** — raises :class:`GovernanceViolationError` immediately.
+        2. **warn_deprecated** — issues :class:`GovernanceWarning`.
+        3. **custom_rules** — first non-empty return value raises
+           :class:`GovernanceViolationError`.
+        4. **strict_unknown** — blocks event types not in ``EventType`` registry.
+
+        Args:
+            event: The event to evaluate.
+
+        Raises:
+            GovernanceViolationError: If the event is blocked.
+        """
+        event_type: str = getattr(event, "event_type", "")
+
+        # Step 1 — explicit block list
+        if event_type in self.blocked_types:
+            raise GovernanceViolationError(
+                event_type,
+                f"event type '{event_type}' is in the blocked_types list",
+            )
+
+        # Step 2 — deprecated warning
+        if event_type in self.warn_deprecated:
+            warnings.warn(
+                f"Event type '{event_type}' is deprecated. Update your instrumentation.",
+                GovernanceWarning,
+                stacklevel=3,
+            )
+
+        # Step 3 — custom rules
+        for rule in self.custom_rules:
+            reason = rule(event)
+            if reason:
+                raise GovernanceViolationError(event_type, reason)
+
+        # Step 4 — strict unknown check
+        if self.strict_unknown:
+            try:
+                from spanforge.types import EventType as _EventType
+
+                # EventType members are string values
+                valid_values = {m.value for m in _EventType}
+                if event_type not in valid_values:
+                    raise GovernanceViolationError(
+                        event_type,
+                        f"strict_unknown=True and '{event_type}' is not a registered EventType",
+                    )
+            except ImportError:
+                pass  # If types module unavailable, skip strict check
+
+
+# ---------------------------------------------------------------------------
+# Global singleton
+# ---------------------------------------------------------------------------
+
+_global_policy: EventGovernancePolicy = EventGovernancePolicy()
+
+
+def get_global_policy() -> EventGovernancePolicy:
+    """Return the global :class:`EventGovernancePolicy` singleton.
+
+    The default policy has no blocked types, no deprecated types, no custom
+    rules, and ``strict_unknown=False``.
+    """
+    return _global_policy
+
+
+def set_global_policy(policy: EventGovernancePolicy | None) -> None:
+    """Replace the global policy.  Pass ``None`` to reset to the default.
+
+    Args:
+        policy: New policy, or ``None`` to restore defaults.
+    """
+    global _global_policy
+    _global_policy = policy if policy is not None else EventGovernancePolicy()
+
+
+def check_event(event: Event) -> None:
+    """Apply the global policy to *event*.
+
+    Equivalent to ``get_global_policy().check_event(event)``.
+
+    Args:
+        event: The event to check against the global policy.
+
+    Raises:
+        GovernanceViolationError: If the event is blocked.
+        GovernanceWarning: (via warnings) if the event type is deprecated.
+    """
+    _global_policy.check_event(event)

spanforge/hitl.py

@@ -0,0 +1,295 @@
+"""Human-in-the-Loop (HITL) review queue for SpanForge compliance pipeline.
+
+Provides a runtime mechanism to intercept low-confidence or high-risk
+agent decisions, queue them for human review, and track approval/rejection
+outcomes in the HMAC audit chain.
+
+Required for EU AI Act high-risk mandatory human oversight (Art. 14).
+
+Configuration
+-------------
+* ``hitl_enabled=True`` activates the HITL queue.
+* ``hitl_confidence_threshold`` — decisions below this confidence are auto-queued.
+* ``hitl_risk_tiers`` — set of risk tiers that always require review.
+* ``hitl_sla_seconds`` — SLA timeout for pending reviews.
+
+Emits ``hitl.queued``, ``hitl.reviewed``, ``hitl.escalated``, ``hitl.timeout``
+events into the HMAC audit chain via :func:`emit_rfc_event`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import threading
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from spanforge.namespaces.hitl import HITLPayload
+
+__all__ = [
+    "HITLItem",
+    "HITLQueue",
+    "list_pending",
+    "queue_for_review",
+    "review_item",
+]
+
+
+@dataclass
+class HITLItem:
+    """A single item pending human review."""
+
+    decision_id: str
+    agent_id: str
+    risk_tier: Literal["low", "medium", "high", "critical"]
+    reason: str
+    confidence: float | None = None
+    sla_seconds: int = 3600
+    queued_at: str | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+    status: Literal["queued", "approved", "rejected", "escalated", "timeout"] = "queued"
+    reviewer: str | None = None
+    resolved_at: str | None = None
+    escalation_tier: int = 0
+
+
+class HITLQueue:
+    """Thread-safe human-in-the-loop review queue.
+
+    Intercepts agent decisions matching configurable risk criteria
+    (confidence below threshold, high-risk event type) and holds them
+    pending a named reviewer's approval.
+    """
+
+    def __init__(
+        self,
+        *,
+        confidence_threshold: float = 0.7,
+        risk_tiers: frozenset[str] | None = None,
+        sla_seconds: int = 3600,
+        auto_emit: bool = True,
+    ) -> None:
+        self._lock = threading.Lock()
+        self._items: dict[str, HITLItem] = {}
+        self._confidence_threshold = confidence_threshold
+        self._risk_tiers: frozenset[str] = risk_tiers or frozenset({"high", "critical"})
+        self._sla_seconds = sla_seconds
+        self._auto_emit = auto_emit
+
+    @property
+    def confidence_threshold(self) -> float:
+        """Minimum confidence below which a decision triggers review."""
+        return self._confidence_threshold
+
+    @property
+    def sla_seconds(self) -> int:
+        """Maximum seconds allowed for a review decision."""
+        return self._sla_seconds
+
+    def should_review(
+        self,
+        *,
+        confidence: float | None = None,
+        risk_tier: str = "low",
+    ) -> bool:
+        """Determine if a decision should be queued for human review."""
+        if risk_tier in self._risk_tiers:
+            return True
+        return bool(confidence is not None and confidence < self._confidence_threshold)
+
+    def enqueue(
+        self,
+        decision_id: str,
+        agent_id: str,
+        risk_tier: Literal["low", "medium", "high", "critical"],
+        reason: str,
+        *,
+        confidence: float | None = None,
+        queued_at: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> HITLItem:
+        """Add a decision to the review queue and emit ``hitl.queued``."""
+        if not decision_id:
+            raise ValueError("decision_id must be non-empty")
+        if not agent_id:
+            raise ValueError("agent_id must be non-empty")
+        if not reason:
+            raise ValueError("reason must be non-empty")
+
+        if queued_at is None:
+            import datetime
+
+            queued_at = datetime.datetime.now(datetime.timezone.utc).strftime(
+                "%Y-%m-%dT%H:%M:%S.%fZ"
+            )
+
+        item = HITLItem(
+            decision_id=decision_id,
+            agent_id=agent_id,
+            risk_tier=risk_tier,
+            reason=reason,
+            confidence=confidence,
+            sla_seconds=self._sla_seconds,
+            queued_at=queued_at,
+            payload=payload or {},
+            status="queued",
+        )
+        with self._lock:
+            self._items[decision_id] = item
+
+        if self._auto_emit:
+            self._emit_event(item, "queued")
+        return item
+
+    def review(
+        self,
+        decision_id: str,
+        reviewer: str,
+        outcome: Literal["approved", "rejected"],
+        *,
+        reason: str | None = None,
+    ) -> HITLItem | None:
+        """Record a reviewer's decision and emit ``hitl.reviewed``."""
+        if not reviewer:
+            raise ValueError("reviewer must be non-empty")
+
+        import datetime
+
+        now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+        with self._lock:
+            item = self._items.get(decision_id)
+            if item is None:
+                return None
+            item.status = outcome
+            item.reviewer = reviewer
+            item.resolved_at = now
+            if reason:
+                item.reason = reason
+
+        if self._auto_emit:
+            self._emit_event(item, "reviewed")
+        return item
+
+    def escalate(
+        self,
+        decision_id: str,
+        *,
+        reason: str = "SLA breach or reviewer escalation",
+    ) -> HITLItem | None:
+        """Escalate an item to the next reviewer tier."""
+        with self._lock:
+            item = self._items.get(decision_id)
+            if item is None:
+                return None
+            item.status = "escalated"
+            item.escalation_tier += 1
+            item.reason = reason
+
+        if self._auto_emit:
+            self._emit_event(item, "escalated")
+        return item
+
+    def timeout(self, decision_id: str) -> HITLItem | None:
+        """Mark an item as timed out (SLA expired)."""
+        import datetime
+
+        now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+        with self._lock:
+            item = self._items.get(decision_id)
+            if item is None:
+                return None
+            item.status = "timeout"
+            item.resolved_at = now
+
+        if self._auto_emit:
+            self._emit_event(item, "timeout")
+        return item
+
+    def get(self, decision_id: str) -> HITLItem | None:
+        """Look up an item by decision_id."""
+        with self._lock:
+            return self._items.get(decision_id)
+
+    def list_pending(self) -> list[HITLItem]:
+        """Return all items still in ``queued`` status."""
+        with self._lock:
+            return [i for i in self._items.values() if i.status == "queued"]
+
+    def list_all(self) -> list[HITLItem]:
+        """Return all items regardless of status."""
+        with self._lock:
+            return list(self._items.values())
+
+    def clear(self) -> None:
+        """Remove all items (for testing)."""
+        with self._lock:
+            self._items.clear()
+
+    @staticmethod
+    def _emit_event(item: HITLItem, action: str) -> None:
+        """Emit an HITL event into the HMAC audit chain."""
+        try:
+            from spanforge._stream import emit_rfc_event
+            from spanforge.types import EventType
+
+            _action_to_event = {
+                "queued": EventType.HITL_QUEUED,
+                "reviewed": EventType.HITL_REVIEWED,
+                "escalated": EventType.HITL_ESCALATED,
+                "timeout": EventType.HITL_TIMEOUT,
+            }
+            et = _action_to_event.get(action)
+            if et is None:
+                return
+            payload = HITLPayload(
+                decision_id=item.decision_id,
+                agent_id=item.agent_id,
+                risk_tier=item.risk_tier,
+                status=item.status,
+                reason=item.reason,
+                reviewer=item.reviewer,
+                sla_seconds=item.sla_seconds,
+                queued_at=item.queued_at,
+                resolved_at=item.resolved_at,
+                escalation_tier=item.escalation_tier,
+                confidence=item.confidence,
+            )
+            with contextlib.suppress(Exception):
+                emit_rfc_event(et, payload.to_dict())
+        except ImportError:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton & convenience functions
+# ---------------------------------------------------------------------------
+
+_queue = HITLQueue()
+
+
+def queue_for_review(
+    decision_id: str,
+    agent_id: str,
+    risk_tier: Literal["low", "medium", "high", "critical"],
+    reason: str,
+    **kwargs: Any,
+) -> HITLItem:
+    """Enqueue a decision via the module-level :class:`HITLQueue`."""
+    return _queue.enqueue(decision_id, agent_id, risk_tier, reason, **kwargs)
+
+
+def review_item(
+    decision_id: str,
+    reviewer: str,
+    outcome: Literal["approved", "rejected"],
+    **kwargs: Any,
+) -> HITLItem | None:
+    """Record a review via the module-level :class:`HITLQueue`."""
+    return _queue.review(decision_id, reviewer, outcome, **kwargs)
+
+
+def list_pending() -> list[HITLItem]:
+    """List pending items via the module-level :class:`HITLQueue`."""
+    return _queue.list_pending()

spanforge/http.py

@@ -0,0 +1,187 @@
+"""spanforge.http — OpenAI-compatible HTTP client with retry and backoff.
+
+Provides a single high-level function :func:`chat_completion` that calls any
+OpenAI-compatible ``/chat/completions`` endpoint, with configurable retry,
+exponential backoff, timeout, and usage extraction.  Uses only the standard
+library (``urllib``) so it adds zero dependencies to the framework.
+
+Usage::
+
+    from spanforge.http import chat_completion
+
+    resp = chat_completion(
+        endpoint="https://api.openai.com/v1",
+        model="gpt-4o",
+        messages=[{"role": "user", "content": "Hello!"}],
+        api_key="sk-...",
+        max_retries=2,
+    )
+    if resp.error:
+        print("Error:", resp.error)
+    else:
+        print(resp.text)
+        print(f"Tokens used: {resp.total_tokens}")
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = [
+    "ChatCompletionResponse",
+    "chat_completion",
+]
+
+# HTTP status codes that are safe to retry.
+_RETRYABLE_CODES = frozenset({429, 500, 502, 503, 504})
+
+
+@dataclass(frozen=True)
+class ChatCompletionResponse:
+    """Result of a single ``/chat/completions`` call.
+
+    Attributes:
+        text:               The assistant message content, or ``""`` on error.
+        latency_ms:         Round-trip time in milliseconds.
+        error:              Human-readable error string, or ``None`` on success.
+        prompt_tokens:      Tokens consumed by the prompt (0 when unavailable).
+        completion_tokens:  Tokens in the completion (0 when unavailable).
+        total_tokens:       Total tokens for the request (0 when unavailable).
+
+    Example::
+
+        resp = chat_completion(endpoint=..., model=..., messages=...)
+        if resp.error is None:
+            print(resp.text)
+    """
+
+    text: str
+    latency_ms: float
+    error: str | None = None
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    total_tokens: int = 0
+
+    @property
+    def ok(self) -> bool:
+        """``True`` when the call succeeded (``error is None``)."""
+        return self.error is None
+
+
+def chat_completion(
+    endpoint: str,
+    model: str,
+    messages: list[dict[str, str]],
+    *,
+    api_key: str = "",
+    timeout: int = 30,
+    max_retries: int = 0,
+    extra_body: dict[str, Any] | None = None,
+) -> ChatCompletionResponse:
+    """Call an OpenAI-compatible ``/chat/completions`` endpoint.
+
+    On transient HTTP errors (429, 5xx) and network errors the call is retried
+    up to *max_retries* times with exponential back-off (``min(2**attempt, 8)``
+    seconds between attempts).
+
+    Args:
+        endpoint:     Base URL of the API (e.g. ``"https://api.openai.com/v1"``).
+                      The path ``/chat/completions`` is appended automatically.
+        model:        Model identifier to pass in the request body.
+        messages:     List of ``{"role": ..., "content": ...}`` dicts.
+        api_key:      Bearer token.  Falls back to ``$OPENAI_API_KEY`` when empty.
+        timeout:      Per-attempt timeout in seconds (default 30).
+        max_retries:  Number of additional attempts after the first failure
+                      (default 0 = no retries).
+        extra_body:   Additional top-level keys to merge into the request body
+                      (e.g. ``{"temperature": 0.0}``).
+
+    Returns:
+        A :class:`ChatCompletionResponse` describing the result.  Check
+        :attr:`~ChatCompletionResponse.ok` or
+        :attr:`~ChatCompletionResponse.error` before using
+        :attr:`~ChatCompletionResponse.text`.
+
+    Example::
+
+        from spanforge.http import chat_completion
+
+        resp = chat_completion(
+            endpoint="https://api.openai.com/v1",
+            model="gpt-4o",
+            messages=[{"role": "user", "content": "Say hello."}],
+            api_key="sk-...",
+            max_retries=2,
+        )
+        assert resp.ok
+        print(resp.text)
+    """
+    import os
+
+    resolved_key = api_key or os.environ.get("OPENAI_API_KEY", "")
+    url = endpoint.rstrip("/") + "/chat/completions"
+
+    payload: dict[str, Any] = {"model": model, "messages": messages}
+    if extra_body:
+        payload.update(extra_body)
+    data = json.dumps(payload).encode("utf-8")
+
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {resolved_key}",
+    }
+
+    last_error = ""
+    for attempt in range(max(0, max_retries) + 1):
+        req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+        t0 = time.perf_counter()
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # nosec B310
+                body: dict[str, Any] = json.loads(resp.read().decode("utf-8"))
+            latency_ms = (time.perf_counter() - t0) * 1000.0
+        except urllib.error.HTTPError as exc:
+            latency_ms = (time.perf_counter() - t0) * 1000.0
+            try:
+                detail = exc.read(8192).decode("utf-8", errors="replace")
+            except Exception:
+                detail = str(exc)
+            last_error = f"HTTP {exc.code}: {detail[:300]}"
+            if exc.code in _RETRYABLE_CODES and attempt < max_retries:
+                time.sleep(min(2**attempt, 8))
+                continue
+            return ChatCompletionResponse(text="", latency_ms=latency_ms, error=last_error)
+        except (OSError, urllib.error.URLError) as exc:
+            latency_ms = (time.perf_counter() - t0) * 1000.0
+            last_error = str(exc)
+            if attempt < max_retries:
+                time.sleep(min(2**attempt, 8))
+                continue
+            return ChatCompletionResponse(text="", latency_ms=latency_ms, error=last_error)
+
+        usage = body.get("usage") or {}
+        try:
+            text: str = body["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError) as exc:
+            return ChatCompletionResponse(
+                text="",
+                latency_ms=latency_ms,
+                error=f"unexpected response shape: {exc}",
+            )
+
+        return ChatCompletionResponse(
+            text=text,
+            latency_ms=latency_ms,
+            error=None,
+            prompt_tokens=int(usage.get("prompt_tokens", 0)),
+            completion_tokens=int(usage.get("completion_tokens", 0)),
+            total_tokens=int(usage.get("total_tokens", 0)),
+        )
+
+    # Exhausted retries without returning (defensive; loop always returns or
+    # hits a 'continue' that leads back here)
+    return ChatCompletionResponse(text="", latency_ms=0.0, error=last_error)  # pragma: no cover