blocklog 0.2.0__py3-none-any.whl

blocklog/managers/decision.py

@@ -0,0 +1,336 @@
+"""
+blocklog.managers.decision
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``decision()`` context manager — the highest-priority surface of the SDK.
+
+Usage (Layer 1)::
+
+    import blocklog
+
+    blocklog.init(api_key="blk_...")
+
+    with blocklog.decision(type="BUY", asset="TSLA", confidence=0.87) as d:
+        price = fetch_price("TSLA")
+        d.record_input(price=price, signal="momentum_crossover")
+
+        order = place_order("TSLA", qty=100)
+        d.record_output(order_id=order.id, filled_at=order.price)
+
+        if order.value > 500_000:
+            d.request_approval(reason="Trade exceeds threshold")
+
+    # After the block:
+    print(d.id)          # UUID of the recorded decision
+    print(d.verified)    # True if blockchain-anchored
+"""
+from __future__ import annotations
+
+import logging
+import traceback as _traceback
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from typing import Any, Generator
+
+logger = logging.getLogger(__name__)
+
+
+class DecisionContext:
+    """Live handle to a decision being recorded.
+
+    Obtained from the ``decision()`` context manager.  Do not instantiate
+    directly.
+
+    Attributes
+    ----------
+    id : str | None
+        The backend-assigned UUID for this decision.  Available after the
+        context body starts executing (set during ``__enter__``).
+    decision_type : str
+        The decision type you passed in (e.g. ``"BUY"``, ``"TRADE"``,
+        ``"APPROVE"``).
+    status : str
+        ``"open"`` while inside the ``with`` block, ``"complete"`` on
+        clean exit, ``"error"`` on exception.
+    """
+
+    def __init__(
+        self,
+        *,
+        decision_type: str,
+        asset: str | None = None,
+        confidence: float | None = None,
+        metadata: dict[str, Any] | None = None,
+        agent_id: str | None = None,
+        trace_id: str | None = None,
+    ) -> None:
+        self.decision_type = decision_type
+        self.asset = asset
+        self.confidence = confidence
+        self.metadata: dict[str, Any] = metadata or {}
+        self.agent_id = agent_id
+        self._trace_id = trace_id
+
+        self.id: str | None = None
+        self.status: str = "open"
+        self._inputs: list[dict] = []
+        self._outputs: list[dict] = []
+        self._tags: list[str] = []
+        self._started_at: datetime = datetime.now(timezone.utc)
+        self._approval_requested: bool = False
+
+    # ------------------------------------------------------------------
+    # Public methods available inside the ``with`` block
+    # ------------------------------------------------------------------
+
+    def record_input(self, **kwargs: Any) -> "DecisionContext":
+        """Record structured inputs that fed into this decision.
+
+        Call this before the AI model / logic runs.
+
+        Parameters
+        ----------
+        **kwargs
+            Arbitrary key-value pairs describing the inputs.  Will be
+            stored verbatim and appear in replays and forensic timelines.
+
+        Examples
+        --------
+        >>> d.record_input(price=412.50, volume=1_200_000, signal="rsi_oversold")
+        """
+        self._inputs.append({"recorded_at": _now_iso(), **kwargs})
+        self._send_event("DECISION_INPUT", kwargs)
+        return self
+
+    def record_output(self, **kwargs: Any) -> "DecisionContext":
+        """Record structured outputs / results of this decision.
+
+        Call this after the AI model / logic produces a result.
+
+        Parameters
+        ----------
+        **kwargs
+            Arbitrary key-value pairs describing the outputs.
+
+        Examples
+        --------
+        >>> d.record_output(order_id="ord_88", filled_at=413.10, qty=100)
+        """
+        self._outputs.append({"recorded_at": _now_iso(), **kwargs})
+        self._send_event("DECISION_OUTPUT", kwargs)
+        return self
+
+    def tag(self, *tags: str) -> "DecisionContext":
+        """Attach one or more string labels to this decision.
+
+        Tags appear in the dashboard and can be used to filter/search.
+
+        Examples
+        --------
+        >>> d.tag("high-value", "requires-review", "momentum-strategy")
+        """
+        self._tags.extend(tags)
+        return self
+
+    def request_approval(
+        self,
+        reason: str,
+        reviewer: str | None = None,
+    ) -> "DecisionContext":
+        """Request human approval for this decision (HITL).
+
+        This is a **non-blocking** call.  It records the approval request
+        against the decision and notifies the reviewer (via backend
+        webhooks / email, as configured in your Blocklog workspace).
+        Execution continues; it is the caller's responsibility to gate
+        further actions on approval status.
+
+        Parameters
+        ----------
+        reason:
+            Human-readable explanation for why approval is needed.
+        reviewer:
+            Optional email / identifier of the intended reviewer.
+
+        Examples
+        --------
+        >>> if order_value > 500_000:
+        ...     d.request_approval(
+        ...         reason="Trade exceeds $500k threshold",
+        ...         reviewer="risk-team@fund.com",
+        ...     )
+        """
+        self._approval_requested = True
+        try:
+            from blocklog._global import get_client
+            client = get_client()
+            client.approval.request(
+                decision_id=self.id,
+                reason=reason,
+                reviewer=reviewer,
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("blocklog: approval.request() failed: %s", exc)
+        return self
+
+    def verify(self) -> dict[str, Any]:
+        """Immediately verify this decision against the blockchain anchor.
+
+        Returns
+        -------
+        dict
+            Verification result from ``GET /decisions/{id}/verify``.
+        """
+        if not self.id:
+            raise RuntimeError("Decision has not been committed yet.")
+        from blocklog._global import get_client
+        return get_client().decisions.verify(self.id)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _send_event(self, event_type: str, payload: dict) -> None:
+        """Fire an event log to the ingest endpoint (best-effort)."""
+        try:
+            from blocklog._global import get_client
+            from blocklog.context.vars import get_context
+
+            ctx = get_context()
+            client = get_client()
+            client.event(
+                event_type,
+                payload={
+                    "decision_id": self.id,
+                    "decision_type": self.decision_type,
+                    "asset": self.asset,
+                    **payload,
+                },
+                trace_id=str(ctx.trace_id) if ctx else self._trace_id,
+                session_id=str(ctx.session_id) if ctx else None,
+                actor_id=self.agent_id or (ctx.agent_id if ctx else None),
+                actor_type="agent",
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("blocklog: event send failed (%s): %s", event_type, exc)
+
+    def _commit(self) -> None:
+        """Create the decision record in the backend."""
+        try:
+            from blocklog._global import get_client
+            from blocklog.context.vars import get_context
+
+            ctx = get_context()
+            client = get_client()
+            result = client.decisions.create(
+                decision_type=self.decision_type,
+                asset=self.asset,
+                confidence=self.confidence,
+                metadata={
+                    **self.metadata,
+                    "tags": self._tags,
+                    "started_at": self._started_at.isoformat(),
+                },
+                trace_id=str(ctx.trace_id) if ctx else self._trace_id,
+                session_id=str(ctx.session_id) if ctx else None,
+                agent_id=self.agent_id or (ctx.agent_id if ctx else None),
+            )
+            self.id = str(result.get("id", result.get("decision_id", "")))
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("blocklog: decision.create() failed: %s", exc)
+
+    def _complete(self) -> None:
+        self.status = "complete"
+        self._send_event("DECISION_COMPLETE", {
+            "inputs": self._inputs,
+            "outputs": self._outputs,
+            "tags": self._tags,
+            "approval_requested": self._approval_requested,
+            "completed_at": _now_iso(),
+        })
+
+    def _error(self, exc: BaseException) -> None:
+        self.status = "error"
+        self._send_event("DECISION_ERROR", {
+            "error_type": type(exc).__name__,
+            "error_message": str(exc),
+            "traceback": _traceback.format_exc(),
+            "tags": self._tags,
+            "failed_at": _now_iso(),
+        })
+
+
+# ---------------------------------------------------------------------------
+# Public factory
+# ---------------------------------------------------------------------------
+
+@contextmanager
+def decision(
+    *,
+    type: str,  # noqa: A002
+    asset: str | None = None,
+    confidence: float | None = None,
+    metadata: dict[str, Any] | None = None,
+    agent_id: str | None = None,
+    trace_id: str | None = None,
+) -> Generator[DecisionContext, None, None]:
+    """Context manager for recording an AI decision.
+
+    Creates a decision record in Blocklog, lets you annotate it with
+    inputs/outputs, then automatically closes it on exit — cleanly or
+    with an error event if an exception is raised.
+
+    Parameters
+    ----------
+    type:
+        Decision type identifier.  Use a short, uppercase string that is
+        meaningful in your domain (``"BUY"``, ``"SELL"``, ``"APPROVE"``,
+        ``"REJECT"``, ``"ROUTE"``, ``"SUMMARISE"``…).
+    asset:
+        Optional asset or resource this decision is about
+        (``"TSLA"``, ``"customer_123"``, ``"invoice_456"``…).
+    confidence:
+        Optional model confidence score between 0 and 1.
+    metadata:
+        Arbitrary extra fields stored with the decision record.
+    agent_id:
+        Override the agent identity for this decision.  Normally
+        inherited from the surrounding ``@agent`` context.
+    trace_id:
+        Override the trace ID.  Normally inherited automatically.
+
+    Yields
+    ------
+    DecisionContext
+        A live handle you can use to call ``record_input()``,
+        ``record_output()``, ``tag()``, ``request_approval()``, etc.
+
+    Examples
+    --------
+    >>> with blocklog.decision(type="BUY", asset="TSLA", confidence=0.87) as d:
+    ...     d.record_input(price=412.50, signal="momentum")
+    ...     order = place_order("TSLA", qty=100)
+    ...     d.record_output(order_id=order.id)
+    """
+    ctx = DecisionContext(
+        decision_type=type,
+        asset=asset,
+        confidence=confidence,
+        metadata=metadata,
+        agent_id=agent_id,
+        trace_id=trace_id,
+    )
+    ctx._commit()
+    try:
+        yield ctx
+        ctx._complete()
+    except BaseException as exc:
+        ctx._error(exc)
+        raise
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()

blocklog/middleware/hooks.py

@@ -0,0 +1,11 @@
+from collections.abc import Callable
+
+
+Hook = Callable[[dict], dict]
+
+
+def apply_hooks(payload: dict, hooks: list[Hook]) -> dict:
+    current = payload
+    for hook in hooks:
+        current = hook(current)
+    return current

blocklog/models/events.py

@@ -0,0 +1,33 @@
+from datetime import datetime, timezone
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, Field
+
+
+class EventEnvelope(BaseModel):
+    event_type: str
+    payload: dict
+    source: str = "python-sdk"
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    idempotency_key: str | None = None
+    trace_id: UUID | None = None
+    session_id: UUID | None = None
+    workflow_id: UUID | None = None
+    parent_event_id: UUID | None = None
+    root_event_id: UUID | None = None
+    span_id: str | None = None
+    attempt_no: int = 1
+    causality_type: str | None = None
+    schema_version: str = "1.0"
+    event_version: str = "1.0"
+    actor_type: str | None = None
+    actor_id: str | None = None
+    agent_metadata: dict = Field(default_factory=dict)
+
+
+class SessionContext(BaseModel):
+    trace_id: UUID = Field(default_factory=uuid4)
+    session_id: UUID = Field(default_factory=uuid4)
+    workflow_id: UUID | None = None
+    agent_id: str | None = None
+    source: str = "python-sdk"

blocklog/models/responses.py

@@ -0,0 +1,18 @@
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class IngestResponse(BaseModel):
+    log_id: str
+    company_id: str
+    event_type: str
+    source: str
+    idempotency_key: str | None = None
+    timestamp: datetime | None = None
+    created_at: datetime
+    trace_id: UUID | None = None
+    session_id: UUID | None = None
+    workflow_id: UUID | None = None
+    parent_event_id: UUID | None = None

blocklog/replay.py

@@ -0,0 +1,64 @@
+"""
+blocklog.replay
+~~~~~~~~~~~~~~~
+Module-level factory for forensic replay sessions.
+
+Usage (Layer 1)::
+
+    import blocklog
+
+    session = blocklog.replay("trace-abc-123")
+
+    # Explore what happened
+    timeline   = session.timeline()
+    root_cause = session.root_cause()
+    graph      = session.causal_graph()
+    stale      = session.staleness()
+
+    # What would have happened differently?
+    cf = session.counterfactual(token_id="tok_x", modified_inputs={"price": 400})
+
+    # Compare against another run
+    diff = session.compare(other_trace_id="trace-def-456")
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from blocklog.api.replay import ReplaySession
+
+
+def replay(
+    trace_id: str,
+    *,
+    token_id: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> "ReplaySession":
+    """Create a forensic replay session for a trace.
+
+    Parameters
+    ----------
+    trace_id:
+        The trace to replay.  All events associated with this trace will
+        be reconstructed into a timeline, causal graph, and analysis.
+    token_id:
+        Execution token ID to bind to the session (required for
+        counterfactual simulations).
+    metadata:
+        Optional extra metadata for the replay session.
+
+    Returns
+    -------
+    ReplaySession
+        A session handle with methods for timeline, root_cause,
+        causal_graph, staleness, divergence, counterfactual, and compare.
+
+    Examples
+    --------
+    >>> session = blocklog.replay("trace-abc")
+    >>> cause = session.root_cause()
+    >>> print(cause["description"])
+    """
+    from blocklog._global import get_client
+    return get_client().replay.create(trace_id=trace_id, token_id=token_id, metadata=metadata)

blocklog/signing/canonical.py

@@ -0,0 +1,5 @@
+import json
+
+
+def canonical_json(payload: dict) -> bytes:
+    return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")

blocklog/signing/ed25519.py

@@ -0,0 +1,25 @@
+from hashlib import sha256
+
+from .canonical import canonical_json
+
+
+def hash_sign(payload: dict, private_key: str | None = None) -> str:
+    """Generate a deterministic hash signature for a payload.
+    
+    This is NOT cryptographic Ed25519 signing. It generates a deterministic
+    SHA256 hash of the payload combined with a seed/key for tamper-evidence
+    purposes. For true cryptographic signing, use the cryptography library.
+    
+    Args:
+        payload: The payload to hash
+        private_key: Optional seed/key for the hash (defaults to "blocklog")
+    
+    Returns:
+        Hexadecimal SHA256 hash string
+    """
+    seed = private_key or "blocklog"
+    return sha256(seed.encode("utf-8") + canonical_json(payload)).hexdigest()
+
+
+# Backward compatibility alias
+pseudo_sign = hash_sign

blocklog/transport/auth.py

@@ -0,0 +1,8 @@
+def build_headers(api_key: str, extra: dict[str, str] | None = None) -> dict[str, str]:
+    headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": api_key,
+    }
+    if extra:
+        headers.update(extra)
+    return headers

blocklog/transport/httpx_async.py

@@ -0,0 +1,39 @@
+import asyncio
+
+try:
+    import httpx
+except ModuleNotFoundError:  # pragma: no cover - exercised in local fallback mode
+    httpx = None
+    import requests
+else:
+    requests = None
+
+from .auth import build_headers
+
+
+class AsyncTransport:
+    def __init__(self, *, base_url: str, api_key: str, timeout: float) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.client = httpx.AsyncClient(timeout=timeout) if httpx is not None else None
+
+    async def request(self, method: str, path: str, *, json: dict | None = None, headers: dict[str, str] | None = None):
+        if self.client is not None:
+            response = await self.client.request(
+                method,
+                f"{self.base_url}{path}",
+                json=json,
+                headers=build_headers(self.api_key, headers),
+            )
+        else:
+            response = await asyncio.to_thread(
+                requests.request,
+                method,
+                f"{self.base_url}{path}",
+                json=json,
+                headers=build_headers(self.api_key, headers),
+                timeout=self.timeout,
+            )
+        response.raise_for_status()
+        return response.json()

blocklog/transport/httpx_sync.py

@@ -0,0 +1,36 @@
+try:
+    import httpx
+except ModuleNotFoundError:  # pragma: no cover - exercised in local fallback mode
+    httpx = None
+    import requests
+else:
+    requests = None
+
+from .auth import build_headers
+
+
+class SyncTransport:
+    def __init__(self, *, base_url: str, api_key: str, timeout: float) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.client = httpx.Client(timeout=timeout) if httpx is not None else None
+
+    def request(self, method: str, path: str, *, json: dict | None = None, headers: dict[str, str] | None = None):
+        if self.client is not None:
+            response = self.client.request(
+                method,
+                f"{self.base_url}{path}",
+                json=json,
+                headers=build_headers(self.api_key, headers),
+            )
+        else:
+            response = requests.request(
+                method,
+                f"{self.base_url}{path}",
+                json=json,
+                headers=build_headers(self.api_key, headers),
+                timeout=self.timeout,
+            )
+        response.raise_for_status()
+        return response.json()

blocklog/transport/retry.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from random import random
+from time import sleep
+
+
+@dataclass(slots=True)
+class RetryPolicy:
+    max_retries: int = 3
+    base_delay: float = 0.25
+
+    def backoff(self, attempt: int) -> float:
+        return self.base_delay * (2 ** attempt) + random() * 0.1
+
+    def run(self, fn):
+        last_error = None
+        for attempt in range(self.max_retries):
+            try:
+                return fn()
+            except Exception as exc:  # noqa: BLE001
+                last_error = exc
+                if attempt == self.max_retries - 1:
+                    raise
+                sleep(self.backoff(attempt))
+        raise RuntimeError("retry failed") from last_error

blocklog/verify.py

@@ -0,0 +1,72 @@
+"""
+blocklog.verify
+~~~~~~~~~~~~~~~
+Module-level namespace for cryptographic verification.
+
+Usage (Layer 1)::
+
+    import blocklog
+
+    result = blocklog.verify.log("log-uuid-here")
+    result = blocklog.verify.batch("batch-uuid-here")
+    result = blocklog.verify.decision("dec-uuid-here")
+
+    print(result["status"])          # "verified"
+    print(result["time_attestation"])
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def log(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``.
+    """
+    from blocklog._global import get_client
+    return get_client().verify.log(log_id)
+
+
+def batch(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``.
+    """
+    from blocklog._global import get_client
+    return get_client().verify.batch(batch_id)
+
+
+def decision(decision_id: str) -> dict[str, Any]:
+    """Verify all evidence attached to a specific decision.
+
+    Parameters
+    ----------
+    decision_id:
+        UUID of the decision to verify.
+
+    Returns
+    -------
+    dict
+        Verification summary including Merkle and blockchain evidence.
+    """
+    from blocklog._global import get_client
+    return get_client().verify.decision(decision_id)