spanforge 2.0.0__py3-none-any.whl

spanforge/exporters/jsonl.py

@@ -0,0 +1,144 @@
+"""spanforge.exporters.jsonl — Synchronous JSONL file exporter.
+
+Appends one canonical JSON line per event to a file on disk.  Zero external
+dependencies (stdlib only).
+
+Usage::
+
+    from spanforge import configure
+    configure(exporter="jsonl", endpoint="./events.jsonl")
+
+    # Now all tracer.span() / agent_run() / agent_step() calls write to
+    # events.jsonl automatically.
+
+You can also instantiate directly for testing::
+
+    from spanforge.exporters.jsonl import SyncJSONLExporter
+    from spanforge.event import Event, EventType, Tags
+
+    exporter = SyncJSONLExporter("/tmp/test.jsonl")  # noqa: S108  # NOSONAR
+    exporter.export(my_event)
+    exporter.close()
+"""
+
+from __future__ import annotations
+
+import sys
+import threading
+from pathlib import Path
+from typing import IO, TYPE_CHECKING, Union
+
+if TYPE_CHECKING:
+    from spanforge.event import Event
+
+__all__ = ["SyncJSONLExporter"]
+
+_PathLike = Union[str, Path]
+
+
+class SyncJSONLExporter:
+    """Synchronous exporter that appends events as newline-delimited JSON.
+
+    Thread-safe: a :class:`threading.Lock` serialises concurrent writes so
+    the output file is never corrupted when multiple threads share one
+    instance.
+
+    Args:
+        path:     File path, :class:`pathlib.Path`, or ``"-"`` for stdout.
+        mode:     File open mode — ``"a"`` (append, default) or ``"w"``
+                  (overwrite / truncate on first write).
+        encoding: File encoding (default ``"utf-8"``).
+
+    Raises:
+        OSError: If the file cannot be opened or written.
+    """
+
+    def __init__(
+        self,
+        path: _PathLike | str = "spanforge_events.jsonl",
+        mode: str = "a",
+        encoding: str = "utf-8",
+    ) -> None:
+        if mode not in ("a", "w"):
+            raise ValueError("mode must be 'a' or 'w'")
+        self._path_str = str(path)
+        self._mode = mode
+        self._encoding = encoding
+        self._file: IO[str] | None = None
+        self._lock = threading.Lock()
+        self._closed = False
+
+    # ------------------------------------------------------------------
+    # Internal file management
+    # ------------------------------------------------------------------
+
+    def _ensure_open(self) -> IO[str]:
+        """Open the file lazily on first write."""
+        if self._file is not None and not self._file.closed:
+            return self._file
+        if self._path_str == "-":
+            self._file = sys.stdout
+            return self._file
+        # Create parent directories if they don't exist.
+        p = Path(self._path_str)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        self._file = p.open(self._mode, encoding=self._encoding)
+        # After first open, always append.
+        self._mode = "a"
+        return self._file
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def export(self, event: Event) -> None:
+        """Write *event* as a single JSON line.
+
+        Args:
+            event: A fully-formed :class:`~spanforge.event.Event` instance.
+
+        Raises:
+            RuntimeError: If :meth:`close` has already been called.
+            OSError:       If the file write fails.
+        """
+        if self._closed:
+            raise RuntimeError("SyncJSONLExporter is closed")
+        line = event.to_json() + "\n"
+        with self._lock:
+            fh = self._ensure_open()
+            fh.write(line)
+            fh.flush()
+
+    def flush(self) -> None:
+        """Flush any buffered data to disk."""
+        with self._lock:
+            if self._file is not None and not self._file.closed:
+                self._file.flush()
+
+    def close(self) -> None:
+        """Flush and close the output file.  Safe to call multiple times."""
+        with self._lock:
+            if not self._closed:
+                if self._file is not None and self._file is not sys.stdout:
+                    try:
+                        self._file.flush()
+                        self._file.close()
+                    except OSError:
+                        pass
+                    self._file = None
+                self._closed = True
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> SyncJSONLExporter:
+        return self
+
+    def __exit__(self, *_: object) -> bool:
+        self.close()
+        return False
+
+    def __repr__(self) -> str:
+        state = "closed" if self._closed else "open"
+        return f"SyncJSONLExporter(path={self._path_str!r}, state={state})"

spanforge/hitl.py

@@ -0,0 +1,297 @@
+"""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 threading
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from spanforge.namespaces.hitl import HITLPayload
+
+__all__ = [
+    "HITLQueue",
+    "HITLItem",
+    "queue_for_review",
+    "review_item",
+    "list_pending",
+]
+
+
+@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:
+        return self._confidence_threshold
+
+    @property
+    def sla_seconds(self) -> int:
+        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
+        if confidence is not None and confidence < self._confidence_threshold:
+            return True
+        return False
+
+    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  # noqa: PLC0415
+            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  # noqa: PLC0415
+        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  # noqa: PLC0415
+        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  # noqa: PLC0415
+            from spanforge.types import EventType  # noqa: PLC0415
+
+            _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,
+            )
+            try:
+                emit_rfc_event(et, payload.to_dict())
+            except Exception:  # noqa: BLE001
+                pass
+        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()