blocklog 0.2.0__py3-none-any.whl

blocklog/__init__.py

@@ -0,0 +1,78 @@
+"""
+blocklog — Infrastructure for AI Decision-Making
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Record every decision your AI agents make.
+
+Quick start::
+
+    import blocklog
+
+    blocklog.init(api_key="blk_...")
+
+    @blocklog.agent(name="stock-trader")
+    def run():
+        with blocklog.decision(type="BUY", asset="TSLA") as d:
+            price = fetch_price("TSLA")
+            d.record_input(price=price)
+
+            order = place_order("TSLA", qty=100)
+            d.record_output(order_id=order.id)
+
+Public API
+----------
+``blocklog.init()``         — configure the SDK
+``@blocklog.agent``         — trace an AI agent function or class
+``@blocklog.tool``          — record a tool call with inputs/outputs
+``blocklog.decision()``     — context manager for AI decision recording
+"""
+from __future__ import annotations
+
+# ── Tier 1: Getting Started ───────────────────────────────────────────────────
+from blocklog._init_fn import init
+from blocklog.decorators.agent import agent
+from blocklog.decorators.tool import tool
+from blocklog.managers.decision import decision, DecisionContext
+
+# ── Tier 2: Governance & Investigation ────────────────────────────────────────
+from blocklog import approval      # noqa: E402
+from blocklog.replay import replay # noqa: E402
+
+__version__ = "0.2.0"
+
+# Expose only the minimum concepts required to understand Blocklog.
+# Advanced features (incident, verify, compliance, clients) are hidden
+# from quickstart autocomplete but remain accessible via their submodules.
+__all__ = [
+    # Tier 1
+    "init",
+    "agent",
+    "tool",
+    "decision",
+    "DecisionContext",
+    # Tier 2
+    "approval",
+    "replay",
+]
+
+def __getattr__(name: str):
+    # Backward compatibility for direct client access (hidden from autocomplete)
+    if name == "BlocklogClient":
+        from blocklog.client import BlocklogClient
+        return BlocklogClient
+    if name == "AsyncBlocklogClient":
+        from blocklog.async_client import AsyncBlocklogClient
+        return AsyncBlocklogClient
+    if name == "BlocklogConfig":
+        from blocklog.config import BlocklogConfig
+        return BlocklogConfig
+    if name == "agent_session":
+        from blocklog.context.managers import agent_session
+        return agent_session
+    if name == "get_context":
+        from blocklog.context.vars import get_context
+        return get_context
+    if name == "set_context":
+        from blocklog.context.vars import set_context
+        return set_context
+    raise AttributeError(f"module 'blocklog' has no attribute {name!r}")

blocklog/_global.py

@@ -0,0 +1,20 @@
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from blocklog.client import BlocklogClient
+
+_global_client: Optional["BlocklogClient"] = None
+
+def get_client() -> "BlocklogClient":
+    if _global_client is None:
+        raise RuntimeError(
+            "Blocklog API key not configured.\n\n"
+            "Use:\n"
+            "from blocklog import init\n"
+            "init(api_key=\"YOUR_API_KEY\")"
+        )
+    return _global_client
+
+def set_client(client: "BlocklogClient") -> None:
+    global _global_client
+    _global_client = client

blocklog/_init_fn.py

@@ -0,0 +1,95 @@
+"""
+blocklog._init_fn
+~~~~~~~~~~~~~~~~~
+Implements the top-level ``blocklog.init()`` call.
+
+Usage::
+
+    import blocklog
+    blocklog.init(api_key="blk_...")
+
+    # or via environment variable BLOCKLOG_API_KEY
+    blocklog.init()
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from blocklog.client import BlocklogClient
+
+
+def init(
+    api_key: str | None = None,
+    *,
+    base_url: str | None = None,
+    signing_key: str | None = None,
+    timeout: float | None = None,
+    max_retries: int | None = None,
+    debug: bool = False,
+) -> "BlocklogClient":
+    """Initialise the Blocklog SDK.
+
+    Call once at application startup — typically right after your other
+    infrastructure initialisation (logging, config loading, etc.).
+
+    Parameters
+    ----------
+    api_key:
+        Your Blocklog API key.  Falls back to the ``BLOCKLOG_API_KEY``
+        environment variable when omitted.
+    base_url:
+        Override the default API base URL.  Useful for self-hosted
+        deployments.  Falls back to ``BLOCKLOG_BASE_URL``.
+    signing_key:
+        Ed25519 private key used to sign log payloads for tamper-evidence.
+        Falls back to ``BLOCKLOG_SDK_SIGNING_KEY``.
+    timeout:
+        Per-request timeout in seconds (default: 10).
+    max_retries:
+        Number of automatic retries on transient failures (default: 3).
+    debug:
+        When ``True``, logs every outbound request to stderr.
+
+    Returns
+    -------
+    BlocklogClient
+        The configured global client instance.  You normally don't need
+        to store this — all module-level helpers (``decision``,
+        ``approval``, ``incident``, ``replay``, ``verify``,
+        ``compliance``) pick it up automatically.
+
+    Examples
+    --------
+    >>> import blocklog
+    >>> blocklog.init(api_key="blk_live_...")
+
+    >>> # Environment-variable driven (CI / production)
+    >>> blocklog.init()
+    """
+    from blocklog._global import set_client
+    from blocklog.client import BlocklogClient
+    from blocklog.config import BlocklogConfig
+
+    overrides: dict = {}
+    if api_key is not None:
+        overrides["api_key"] = api_key
+    if base_url is not None:
+        overrides["base_url"] = base_url
+    if signing_key is not None:
+        overrides["signing_key"] = signing_key
+    if timeout is not None:
+        overrides["timeout"] = timeout
+    if max_retries is not None:
+        overrides["max_retries"] = max_retries
+
+    config = BlocklogConfig(**overrides)
+
+    if debug:
+        import logging
+        logging.basicConfig(level=logging.DEBUG)
+        logging.getLogger("blocklog").setLevel(logging.DEBUG)
+
+    client = BlocklogClient(config)
+    set_client(client)
+    return client

blocklog/api/approval.py

@@ -0,0 +1,182 @@
+"""
+blocklog.api.approval
+~~~~~~~~~~~~~~~~~~~~~
+Layer 2 client for Human-in-the-Loop (HITL) approval workflows.
+
+Available via ``client.approval.*``.
+
+Backend endpoints
+-----------------
+- POST  /api/v1/hitl/approve
+- POST  /api/v1/hitl/reject
+- POST  /api/v1/hitl/escalate
+- GET   /api/v1/hitl/overrides
+- GET   /api/v1/hitl/overrides/{id}
+- GET   /api/v1/hitl/audit-trail
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from blocklog.client import BlocklogClient
+
+
+class ApprovalClient:
+    """Manage human approval workflows (HITL).
+
+    Accessed as ``client.approval``.
+
+    Examples
+    --------
+    >>> client.approval.request(
+    ...     decision_id="dec_abc123",
+    ...     reason="Trade exceeds $500k threshold",
+    ...     reviewer="risk-team@fund.com",
+    ... )
+    """
+
+    def __init__(self, client: "BlocklogClient") -> None:
+        self._client = client
+
+    def request(
+        self,
+        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 or log entry.
+
+        This is a **non-blocking** operation.  It registers the approval
+        request in Blocklog and triggers any configured webhooks or
+        notification rules.  Execution continues immediately.
+
+        Parameters
+        ----------
+        decision_id:
+            UUID of the decision requiring approval.
+        reason:
+            Human-readable explanation of why approval is needed.
+        reviewer:
+            Email or identifier of the intended reviewer.
+        log_id:
+            UUID of the specific log entry, if approval is on a log
+            rather than a top-level decision.
+        metadata:
+            Extra context to attach to the approval request.
+
+        Returns
+        -------
+        dict
+            Backend response confirming the request was registered.
+        """
+        payload: dict[str, Any] = {"reason": reason}
+        if decision_id is not None:
+            payload["decision_id"] = decision_id
+        if reviewer is not None:
+            payload["reviewer"] = reviewer
+        if log_id is not None:
+            payload["log_id"] = log_id
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        return self._client.retry.run(
+            lambda: self._client.transport.request("POST", "/hitl/approve", json=payload)
+        )
+
+    def reject(
+        self,
+        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.
+        """
+        payload: dict[str, Any] = {
+            "reviewer": reviewer,
+            "rejection_reason": reason,
+        }
+        if decision_id is not None:
+            payload["decision_id"] = decision_id
+
+        return self._client.retry.run(
+            lambda: self._client.transport.request("POST", "/hitl/reject", json=payload)
+        )
+
+    def escalate(
+        self,
+        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.
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request("POST", "/hitl/escalate", json={
+                "current_reviewer": from_reviewer,
+                "escalation_target": to_reviewer,
+                "escalation_reason": reason,
+            })
+        )
+
+    def list_overrides(self) -> list[dict[str, Any]]:
+        """Return all HITL override records for the company.
+
+        Returns
+        -------
+        list[dict]
+            List of override records (approvals that changed an outcome).
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", "/hitl/overrides")
+        )
+
+    def get_override(self, override_id: int) -> dict[str, Any]:
+        """Fetch a specific HITL override record.
+
+        Parameters
+        ----------
+        override_id:
+            Integer ID of the override.
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/hitl/overrides/{override_id}")
+        )
+
+    def audit_trail(self) -> list[dict[str, Any]]:
+        """Return the full HITL audit trail for the company.
+
+        Includes all approve / reject / escalate events in reverse
+        chronological order.
+
+        Returns
+        -------
+        list[dict]
+            Ordered list of HITL audit log entries.
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", "/hitl/audit-trail")
+        )

blocklog/api/compliance.py

@@ -0,0 +1,162 @@
+"""
+blocklog.api.compliance
+~~~~~~~~~~~~~~~~~~~~~~~
+Layer 2 client for compliance report generation.
+
+Available via ``client.compliance.*``.
+
+Backend endpoints
+-----------------
+- GET   /api/v1/compliance/dashboard
+- GET   /api/v1/compliance/reports
+- POST  /api/v1/compliance/reports
+- GET   /api/v1/compliance/reports/{id}
+- POST  /api/v1/compliance/reports/{id}/share
+- GET   /api/v1/compliance/reports/{id}/export
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from blocklog.client import BlocklogClient
+
+
+class ComplianceClient:
+    """Generate and manage compliance reports.
+
+    Accessed as ``client.compliance``.
+
+    Examples
+    --------
+    >>> report = client.compliance.generate(
+    ...     trace_id="trace-abc",
+    ...     framework="SOC2",
+    ... )
+    >>> share_url = client.compliance.share(report["id"], expires_in=86400)
+    """
+
+    def __init__(self, client: "BlocklogClient") -> None:
+        self._client = client
+
+    def generate(
+        self,
+        trace_id: str | None = None,
+        *,
+        framework: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Generate a compliance report.
+
+        Parameters
+        ----------
+        trace_id:
+            Scope the report to a specific trace.  Omit to generate a
+            company-wide report.
+        framework:
+            Compliance framework (``"SOC2"``, ``"GDPR"``, ``"ISO27001"``…).
+        date_from:
+            ISO-8601 start of the reporting window.
+        date_to:
+            ISO-8601 end of the reporting window.
+        metadata:
+            Arbitrary extra data to embed in the report.
+
+        Returns
+        -------
+        dict
+            The generated report record.
+        """
+        payload: dict[str, Any] = {}
+        if trace_id is not None:
+            payload["trace_id"] = trace_id
+        if framework is not None:
+            payload["framework"] = framework
+        if date_from is not None:
+            payload["date_from"] = date_from
+        if date_to is not None:
+            payload["date_to"] = date_to
+        if metadata is not None:
+            payload["metadata"] = metadata
+
+        return self._client.retry.run(
+            lambda: self._client.transport.request("POST", "/compliance/reports", json=payload)
+        )
+
+    def get(self, report_id: str) -> dict[str, Any]:
+        """Fetch a compliance report by ID."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", f"/compliance/reports/{report_id}")
+        )
+
+    def list(self) -> list[dict[str, Any]]:
+        """List all compliance reports for the company."""
+        result = self._client.retry.run(
+            lambda: self._client.transport.request("GET", "/compliance/reports")
+        )
+        return result.get("items", result) if isinstance(result, dict) else result
+
+    def dashboard(self) -> dict[str, Any]:
+        """Return the compliance dashboard summary."""
+        return self._client.retry.run(
+            lambda: self._client.transport.request("GET", "/compliance/dashboard")
+        )
+
+    def share(
+        self,
+        report_id: str,
+        *,
+        expires_in: int | None = None,
+        recipient_email: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a shareable link for a compliance report.
+
+        Parameters
+        ----------
+        report_id:
+            UUID of the report to share.
+        expires_in:
+            Seconds until the share link expires.
+        recipient_email:
+            Optional email of the recipient (for audit purposes).
+
+        Returns
+        -------
+        dict
+            Response including ``share_url`` or ``token``.
+        """
+        payload: dict[str, Any] = {}
+        if expires_in is not None:
+            payload["expires_in"] = expires_in
+        if recipient_email is not None:
+            payload["recipient_email"] = recipient_email
+
+        return self._client.retry.run(
+            lambda: self._client.transport.request("POST", f"/compliance/reports/{report_id}/share", json=payload)
+        )
+
+    def export(
+        self,
+        report_id: str,
+        *,
+        download: bool = False,
+    ) -> dict[str, Any]:
+        """Export a compliance report as JSON.
+
+        Parameters
+        ----------
+        report_id:
+            UUID of the report to export.
+        download:
+            When ``True``, request the binary download stream (returned
+            as raw content from the backend).
+        """
+        return self._client.retry.run(
+            lambda: self._client.transport.request(
+                "GET",
+                f"/compliance/reports/{report_id}/export",
+                params={"download": str(download).lower()},
+            )
+        )