blocklog 0.2.0__py3-none-any.whl

blocklog/api/replay.py

@@ -0,0 +1,285 @@
+"""
+blocklog.api.replay
+~~~~~~~~~~~~~~~~~~~
+Layer 2 client for forensic replay sessions.
+
+Available via ``client.replay.*``.
+
+Backend endpoints
+-----------------
+- POST  /api/v1/forensics/replays
+- GET   /api/v1/forensics/replays/{id}
+- GET   /api/v1/forensics/replays/{id}/timeline
+- GET   /api/v1/forensics/replays/{id}/root-cause
+- GET   /api/v1/forensics/replays/{id}/causal-graph
+- GET   /api/v1/forensics/replays/{id}/staleness
+- GET   /api/v1/forensics/replays/{id}/divergence
+- POST  /api/v1/forensics/replays/{id}/counterfactuals
+- POST  /api/v1/forensics/compare
+- GET   /api/v1/forensics/compare/{id}
+- POST  /api/v1/replay/sessions  (simple replay)
+- GET   /api/v1/replay/sessions/{id}
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from blocklog.client import BlocklogClient
+
+
+class ReplaySession:
+    """A forensic replay session.
+
+    Wraps a backend replay session and provides lazy-loaded access to
+    all sub-resources: timeline, root cause, causal graph, staleness
+    heatmap, divergences, and counterfactuals.
+
+    Obtained from ``client.replay.create()`` or ``blocklog.replay()``.
+
+    Examples
+    --------
+    >>> session = client.replay.create(trace_id="trace-abc")
+    >>> session.timeline()
+    >>> session.root_cause()
+    >>> session.compare(other_trace_id="trace-def")
+    """
+
+    def __init__(self, data: dict[str, Any], client: "ReplayClient") -> None:
+        self._data = data
+        self._client = client
+        self.id: str = str(data.get("id", data.get("replay_session_id", "")))
+
+    # -- Raw data --
+
+    @property
+    def raw(self) -> dict[str, Any]:
+        """The full raw session data from the backend."""
+        return self._data
+
+    # -- Sub-resource accessors --
+
+    def timeline(self) -> list[dict[str, Any]]:
+        """Return the chronological event timeline for this replay.
+
+        Returns
+        -------
+        list[dict]
+            Ordered list of timeline items.
+        """
+        return self._client.timeline(self.id)
+
+    def root_cause(self) -> dict[str, Any]:
+        """Perform root-cause analysis on this replay.
+
+        The backend applies heuristics to detect:
+        - Stale context / data freshness violations
+        - Policy violations (authorization denied)
+        - Integrity failures (receipt status anomalies)
+
+        Returns
+        -------
+        dict
+            Keys: ``detected``, ``root_cause_type``, ``description``,
+            ``confidence``, ``remediation``.
+        """
+        return self._client.root_cause(self.id)
+
+    def causal_graph(self) -> dict[str, Any]:
+        """Return the causal graph (nodes + edges) for this replay.
+
+        Useful for visualising the chain of causality across agents,
+        tools, decisions, and execution receipts.
+
+        Returns
+        -------
+        dict
+            Keys: ``nodes``, ``edges``.
+        """
+        return self._client.causal_graph(self.id)
+
+    def staleness(self) -> dict[str, Any]:
+        """Return the staleness heatmap for data sources used in this replay.
+
+        Returns
+        -------
+        dict
+            Keys: ``overall_staleness_rating``, ``findings``.
+        """
+        return self._client.staleness(self.id)
+
+    def divergence(self) -> list[dict[str, Any]]:
+        """Return divergence analysis results for this replay.
+
+        Returns
+        -------
+        list[dict]
+            List of detected divergence events.
+        """
+        return self._client.divergence(self.id)
+
+    def counterfactual(
+        self,
+        token_id: str,
+        *,
+        modified_inputs: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Run a counterfactual (what-if) simulation on this replay.
+
+        Parameters
+        ----------
+        token_id:
+            The execution token ID to simulate against.
+        modified_inputs:
+            Dict of input fields to override in the simulation.
+
+        Returns
+        -------
+        dict
+            Counterfactual analysis result.
+        """
+        return self._client.counterfactual(self.id, token_id=token_id, modified_inputs=modified_inputs)
+
+    def compare(self, other_trace_id: str) -> dict[str, Any]:
+        """Compare this replay session against another trace.
+
+        Creates a new replay session for ``other_trace_id``, then runs a
+        forensic comparison against this session.
+
+        Parameters
+        ----------
+        other_trace_id:
+            Trace ID of the session to compare against.
+
+        Returns
+        -------
+        dict
+            Comparison result including ``differences`` list.
+        """
+        other = self._client.create(trace_id=other_trace_id)
+        return self._client.compare(self.id, other.id)
+
+    def __repr__(self) -> str:
+        return f"<ReplaySession id={self.id!r}>"
+
+
+class ReplayClient:
+    """Manage forensic replay sessions.
+
+    Accessed as ``client.replay``.
+
+    Examples
+    --------
+    >>> session = client.replay.create(trace_id="trace-abc")
+    >>> session.root_cause()
+    >>> session.compare("trace-def")
+    """
+
+    def __init__(self, client: "BlocklogClient") -> None:
+        self._client = client
+
+    def create(
+        self,
+        trace_id: str,
+        *,
+        token_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> ReplaySession:
+        """Create a forensic replay session for a given trace.
+
+        Parameters
+        ----------
+        trace_id:
+            The trace to replay.
+        token_id:
+            Execution token ID to bind to this session.
+        metadata:
+            Extra metadata for the replay session.
+
+        Returns
+        -------
+        ReplaySession
+            A session handle with access to all forensic sub-resources.
+        """
+        payload: dict[str, Any] = {"trace_id": trace_id}
+        if token_id is not None:
+            payload["token_id"] = token_id
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        data = self._client.retry.run(
+            lambda: self._client.transport.request("POST", "/forensics/replays", json=payload)
+        )
+        return ReplaySession(data, self)
+
+    def get(self, replay_session_id: str) -> ReplaySession:
+        """Fetch an existing replay session by ID."""
+        data = self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/forensics/replays/{replay_session_id}")
+        )
+        return ReplaySession(data, self)
+
+    def timeline(self, replay_session_id: str) -> list[dict[str, Any]]:
+        """Return the event timeline for a replay session."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/forensics/replays/{replay_session_id}/timeline")
+        )
+
+    def root_cause(self, replay_session_id: str) -> dict[str, Any]:
+        """Run root-cause analysis on a replay session."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/forensics/replays/{replay_session_id}/root-cause")
+        )
+
+    def causal_graph(self, replay_session_id: str) -> dict[str, Any]:
+        """Return the causal graph for a replay session."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/forensics/replays/{replay_session_id}/causal-graph")
+        )
+
+    def staleness(self, replay_session_id: str) -> dict[str, Any]:
+        """Return staleness heatmap for a replay session."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/forensics/replays/{replay_session_id}/staleness")
+        )
+
+    def divergence(self, replay_session_id: str) -> list[dict[str, Any]]:
+        """Return divergence analysis for a replay session."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/forensics/replays/{replay_session_id}/divergence")
+        )
+
+    def counterfactual(
+        self,
+        replay_session_id: str,
+        *,
+        token_id: str,
+        modified_inputs: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Run a counterfactual simulation."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request(
+                "POST",
+                f"/forensics/replays/{replay_session_id}/counterfactuals",
+                json={"token_id": token_id, "modified_inputs": modified_inputs},
+            )
+        )
+
+    def compare(
+        self,
+        baseline_session_id: str,
+        candidate_session_id: str,
+    ) -> dict[str, Any]:
+        """Compare two replay sessions and return a diff of differences."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("POST", "/forensics/compare", json={
+                "baseline_session_id": baseline_session_id,
+                "candidate_session_id": candidate_session_id,
+            })
+        )
+
+    def get_comparison(self, comparison_id: str) -> dict[str, Any]:
+        """Retrieve a previously computed replay comparison."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/forensics/compare/{comparison_id}")
+        )

blocklog/api/traces.py

@@ -0,0 +1,137 @@
+"""
+blocklog.api.traces
+~~~~~~~~~~~~~~~~~~~
+Layer 2 client for trace and session queries.
+
+Available via ``client.traces.*``.
+
+Backend endpoints
+-----------------
+- GET  /api/v1/traces
+- GET  /api/v1/traces/{trace_id}
+- GET  /api/v1/sessions/{session_id}/timeline
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from blocklog.client import BlocklogClient
+
+
+class TracesClient:
+    """Query traces and session timelines.
+
+    Accessed as ``client.traces``.
+
+    Examples
+    --------
+    >>> traces = client.traces.list(event_type="DECISION_COMPLETE", limit=20)
+    >>> detail  = client.traces.get("trace-uuid")
+    >>> timeline = client.traces.session_timeline("session-uuid")
+    """
+
+    def __init__(self, client: "BlocklogClient") -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        trace_id: str | None = None,
+        session_id: str | None = None,
+        workflow_id: str | None = None,
+        source: str | None = None,
+        event_type: str | None = None,
+        from_ts: str | None = None,
+        to_ts: str | None = None,
+        limit: int = 50,
+    ) -> list[dict[str, Any]]:
+        """List traces with optional filters.
+
+        Parameters
+        ----------
+        trace_id:
+            Filter to a specific trace.
+        session_id:
+            Filter to a specific session.
+        workflow_id:
+            Filter to a specific workflow.
+        source:
+            Filter by event source string.
+        event_type:
+            Filter by event type (e.g. ``"DECISION_COMPLETE"``).
+        from_ts:
+            ISO-8601 lower bound for event timestamp.
+        to_ts:
+            ISO-8601 upper bound for event timestamp.
+        limit:
+            Maximum number of results (1–200, default 50).
+
+        Returns
+        -------
+        list[dict]
+            List of trace/log records.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if trace_id:
+            params["trace_id"] = trace_id
+        if session_id:
+            params["session_id"] = session_id
+        if workflow_id:
+            params["workflow_id"] = workflow_id
+        if source:
+            params["source"] = source
+        if event_type:
+            params["event_type"] = event_type
+        if from_ts:
+            params["from"] = from_ts
+        if to_ts:
+            params["to"] = to_ts
+
+        result = self._client.retry.run(
+            lambda: self._client.transport.request("GET", "/traces", params=params)
+        )
+        return result.get("items", result) if isinstance(result, dict) else result
+
+    def get(self, trace_id: str) -> dict[str, Any]:
+        """Fetch detailed information about a specific trace.
+
+        Parameters
+        ----------
+        trace_id:
+            UUID of the trace.
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/traces/{trace_id}")
+        )
+
+    def session_timeline(
+        self,
+        session_id: str,
+        *,
+        cursor: str | None = None,
+        limit: int = 100,
+    ) -> dict[str, Any]:
+        """Return the paginated event timeline for a session.
+
+        Parameters
+        ----------
+        session_id:
+            UUID of the session.
+        cursor:
+            Pagination cursor from a previous response.
+        limit:
+            Max events to return (1–500, default 100).
+
+        Returns
+        -------
+        dict
+            Paginated response with ``items`` and optional ``next_cursor``.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if cursor:
+            params["cursor"] = cursor
+
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/sessions/{session_id}/timeline", params=params)
+        )

blocklog/api/verify.py

@@ -0,0 +1,100 @@
+"""
+blocklog.api.verify
+~~~~~~~~~~~~~~~~~~~
+Layer 2 client for cryptographic verification.
+
+Available via ``client.verify.*``.
+
+Backend endpoints
+-----------------
+- GET  /api/v1/verify/log/{log_id}
+- GET  /api/v1/verify/batch/{batch_id}
+- GET  /api/v1/decisions/{id}/verify
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from blocklog.client import BlocklogClient
+
+
+class VerifyClient:
+    """Cryptographically verify logs, batches, and decisions.
+
+    Every item recorded by Blocklog is anchored to a blockchain via a
+    Merkle tree.  These methods let you prove that a specific log entry
+    or batch has not been tampered with since it was anchored.
+
+    Accessed as ``client.verify``.
+
+    Examples
+    --------
+    >>> result = client.verify.log("log-uuid-here")
+    >>> print(result["status"])   # "verified"
+    >>> print(result["merkle_proof"])
+
+    >>> result = client.verify.decision("dec-uuid-here")
+    >>> print(result["status"])   # "verified"
+    """
+
+    def __init__(self, client: "BlocklogClient") -> None:
+        self._client = client
+
+    def log(self, log_id: str) -> dict[str, Any]:
+        """Verify a single log entry against its Merkle proof.
+
+        Parameters
+        ----------
+        log_id:
+            UUID of the log entry to verify.
+
+        Returns
+        -------
+        dict
+            Keys: ``status``, ``merkle_proof``, ``batch_anchor``,
+            ``time_attestation``, ``details``.
+
+        Raises
+        ------
+        httpx.HTTPStatusError
+            If the log is not found or verification fails.
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/verify/log/{log_id}")
+        )
+
+    def batch(self, batch_id: str) -> dict[str, Any]:
+        """Verify an entire batch against its blockchain anchor.
+
+        Parameters
+        ----------
+        batch_id:
+            ID of the batch to verify.
+
+        Returns
+        -------
+        dict
+            Keys: ``status``, ``anchor_tx``, ``timestamp``,
+            ``time_attestation``, ``details``.
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/verify/batch/{batch_id}")
+        )
+
+    def decision(self, decision_id: str) -> dict[str, Any]:
+        """Verify all evidence attached to a decision.
+
+        Parameters
+        ----------
+        decision_id:
+            UUID of the decision to verify.
+
+        Returns
+        -------
+        dict
+            Verification summary including Merkle and blockchain evidence.
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/decisions/{decision_id}/verify")
+        )

blocklog/approval.py

@@ -0,0 +1,119 @@
+"""
+blocklog.approval
+~~~~~~~~~~~~~~~~~
+Module-level namespace for human approval workflows.
+
+Usage (Layer 1)::
+
+    from blocklog import approval
+
+    approval.request(
+        decision_id="dec_abc123",
+        reason="Trade exceeds $500k threshold",
+        reviewer="risk-team@fund.com",
+    )
+
+    approval.reject(reviewer="alice@fund.com", reason="Insufficient data")
+
+    approval.escalate(
+        from_reviewer="alice@fund.com",
+        to_reviewer="head-of-risk@fund.com",
+        reason="Requires executive sign-off",
+    )
+
+    trail = approval.audit_trail()
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def request(
+    decision_id: str | None = None,
+    *,
+    reason: str,
+    reviewer: str | None = None,
+    log_id: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Request human approval for a decision.
+
+    This is a **non-blocking** call — it registers the approval request
+    and triggers configured webhooks/notifications, then returns
+    immediately.
+
+    Parameters
+    ----------
+    decision_id:
+        UUID of the decision requiring approval.
+    reason:
+        Human-readable explanation of why approval is needed.
+    reviewer:
+        Email / identifier of the intended reviewer.
+    log_id:
+        UUID of a specific log entry, if approval is on a log rather
+        than a top-level decision.
+    metadata:
+        Extra context to store with the approval request.
+    """
+    from blocklog._global import get_client
+    return get_client().approval.request(
+        decision_id=decision_id,
+        reason=reason,
+        reviewer=reviewer,
+        log_id=log_id,
+        metadata=metadata,
+    )
+
+
+def reject(reviewer: str, *, reason: str, decision_id: str | None = None) -> dict[str, Any]:
+    """Record that a reviewer has rejected a decision.
+
+    Parameters
+    ----------
+    reviewer:
+        Identity of the person rejecting.
+    reason:
+        Explanation for the rejection.
+    decision_id:
+        Optional reference to the decision being rejected.
+    """
+    from blocklog._global import get_client
+    return get_client().approval.reject(reviewer=reviewer, reason=reason, decision_id=decision_id)
+
+
+def escalate(
+    from_reviewer: str,
+    to_reviewer: str,
+    *,
+    reason: str,
+) -> dict[str, Any]:
+    """Escalate an approval request to a different reviewer.
+
+    Parameters
+    ----------
+    from_reviewer:
+        Current reviewer escalating the decision.
+    to_reviewer:
+        Target reviewer who should take over.
+    reason:
+        Explanation for the escalation.
+    """
+    from blocklog._global import get_client
+    return get_client().approval.escalate(
+        from_reviewer=from_reviewer,
+        to_reviewer=to_reviewer,
+        reason=reason,
+    )
+
+
+def list_overrides() -> list[dict[str, Any]]:
+    """Return all HITL override records for the company."""
+    from blocklog._global import get_client
+    return get_client().approval.list_overrides()
+
+
+def audit_trail() -> list[dict[str, Any]]:
+    """Return the full HITL audit trail in reverse-chronological order."""
+    from blocklog._global import get_client
+    return get_client().approval.audit_trail()

blocklog/async_client.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from blocklog.client import BlocklogClient
+from blocklog.config import BlocklogConfig
+from blocklog.models.responses import IngestResponse
+from blocklog.transport.httpx_async import AsyncTransport
+
+
+class AsyncBlocklogClient(BlocklogClient):
+    def __init__(self, config: BlocklogConfig) -> None:
+        super().__init__(config)
+        self.transport = AsyncTransport(
+            base_url=config.base_url,
+            api_key=config.api_key,
+            timeout=config.timeout,
+        )
+
+    async def event(self, event_type: str, payload: dict, **kwargs) -> IngestResponse:
+        envelope = self._build_event(event_type=event_type, payload=payload, **kwargs)
+        result = await self.transport.request("POST", "/logs", json=self._serialize(envelope))
+        return IngestResponse.model_validate(result)
+
+    async def flush(self, *, batch=None):
+        batch = batch or self.buffer.flush()
+        if not batch:
+            return {"ingested": 0, "log_ids": []}
+        payload = {"logs": [self._serialize(item) for item in batch]}
+        return await self.transport.request("POST", "/logs/batch", json=payload)

blocklog/batching/buffer.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from blocklog.models.events import EventEnvelope
+
+
+@dataclass(slots=True)
+class EventBuffer:
+    batch_size: int
+    items: list[EventEnvelope] = field(default_factory=list)
+
+    def add(self, event: EventEnvelope) -> list[EventEnvelope] | None:
+        self.items.append(event)
+        if len(self.items) >= self.batch_size:
+            return self.flush()
+        return None
+
+    def flush(self) -> list[EventEnvelope]:
+        drained = list(self.items)
+        self.items.clear()
+        return drained