blocklog 0.2.0__py3-none-any.whl

blocklog/client.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+from hashlib import sha256
+from typing import Any
+
+from blocklog.api.approval import ApprovalClient
+from blocklog.api.compliance import ComplianceClient
+from blocklog.api.decisions import DecisionsClient
+from blocklog.api.incidents import IncidentsClient
+from blocklog.api.replay import ReplayClient
+from blocklog.api.traces import TracesClient
+from blocklog.api.verify import VerifyClient
+from blocklog.batching.buffer import EventBuffer
+from blocklog.config import BlocklogConfig
+from blocklog.context.managers import agent_session
+from blocklog.context.vars import get_context
+from blocklog.integrations.langchain import instrument_langchain
+from blocklog.integrations.langgraph import instrument_langgraph
+from blocklog.integrations.openai_agents import instrument_openai_agents
+from blocklog.middleware.hooks import apply_hooks
+from blocklog.models.events import EventEnvelope
+from blocklog.models.responses import IngestResponse
+from blocklog.signing.ed25519 import hash_sign
+from blocklog.transport.httpx_sync import SyncTransport
+from blocklog.transport.retry import RetryPolicy
+
+
+class BlocklogClient:
+    """The Blocklog client.
+
+    Most users should call ``blocklog.init(api_key=...)`` instead of
+    instantiating this class directly.  The global client is then
+    accessible to all module-level helpers (``decision``, ``approval``,
+    ``incident``, ``replay``, ``verify``, ``compliance``).
+
+    For advanced control, instantiate this class directly::
+
+        from blocklog import BlocklogClient, BlocklogConfig
+
+        client = BlocklogClient(BlocklogConfig(api_key="blk_..."))
+
+    Attributes
+    ----------
+    decisions : DecisionsClient
+        Layer 2 client for AI Decision records.
+    incidents : IncidentsClient
+        Layer 2 client for the incident lifecycle.
+    approval : ApprovalClient
+        Layer 2 client for HITL approval workflows.
+    replay : ReplayClient
+        Layer 2 client for forensic replay sessions.
+    compliance : ComplianceClient
+        Layer 2 client for compliance report generation.
+    verify : VerifyClient
+        Layer 2 client for cryptographic verification.
+    traces : TracesClient
+        Layer 2 client for trace/session queries.
+    """
+
+    def __init__(self, config: BlocklogConfig) -> None:
+        self.config = config
+        self.transport = SyncTransport(
+            base_url=config.base_url,
+            api_key=config.api_key,
+            timeout=config.timeout,
+        )
+        self.retry = RetryPolicy(max_retries=config.max_retries)
+        self.buffer = EventBuffer(batch_size=config.batch_size)
+        self.hooks: list = []
+
+        # ── Layer 2 domain sub-clients ────────────────────────────────
+        self.decisions = DecisionsClient(self)
+        self.incidents = IncidentsClient(self)
+        self.approval = ApprovalClient(self)
+        self.replay = ReplayClient(self)
+        self.compliance = ComplianceClient(self)
+        self.verify = VerifyClient(self)
+        self.traces = TracesClient(self)
+
+        # ── Legacy aliases (backward compatibility) ───────────────────
+        # These point to the same new clients so old code keeps working.
+        self.forensics = self.replay   # client.forensics.compare(...) still works
+        self.hitl = self.approval      # client.hitl.reject(...) still works
+
+    @classmethod
+    def from_env(cls) -> "BlocklogClient":
+        """Create a client configured entirely from environment variables."""
+        return cls(BlocklogConfig.from_env())
+
+    def add_hook(self, hook) -> "BlocklogClient":
+        """Register a middleware hook applied to every outbound event payload."""
+        self.hooks.append(hook)
+        return self
+
+    def session(self, *, agent_id: str | None = None, source: str = "python-sdk", workflow_id=None):
+        """Open an ``agent_session`` context manager (backward-compatible).
+
+        Prefer the ``@blocklog.agent`` decorator for new code.
+        """
+        return agent_session(agent_id=agent_id, source=source, workflow_id=workflow_id)
+
+    def instrument_openai_agents(self) -> "BlocklogClient":
+        """Auto-instrument the OpenAI Agents SDK."""
+        return instrument_openai_agents(self)
+
+    def instrument_langchain(self) -> "BlocklogClient":
+        """Auto-instrument LangChain."""
+        return instrument_langchain(self)
+
+    def instrument_langgraph(self) -> "BlocklogClient":
+        """Auto-instrument LangGraph."""
+        return instrument_langgraph(self)
+
+    # ── Low-level event ingest (Layer 3) ─────────────────────────────
+
+    def event(self, event_type: str, payload: dict[str, Any], **kwargs) -> IngestResponse:
+        """Emit a single event immediately (synchronous)."""
+        envelope = self._build_event(event_type=event_type, payload=payload, **kwargs)
+        result = self.retry.run(lambda: self.transport.request("POST", "/logs", json=self._serialize(envelope)))
+        return IngestResponse.model_validate(result)
+
+    def enqueue(self, event_type: str, payload: dict[str, Any], **kwargs):
+        """Enqueue an event for batched delivery."""
+        envelope = self._build_event(event_type=event_type, payload=payload, **kwargs)
+        batch = self.buffer.add(envelope)
+        if batch:
+            return self.flush(batch=batch)
+        return None
+
+    def flush(self, *, batch=None):
+        """Flush the event buffer, sending all queued events."""
+        batch = batch or self.buffer.flush()
+        if not batch:
+            return {"ingested": 0, "log_ids": []}
+        payload = {"logs": [self._serialize(item) for item in batch]}
+        return self.retry.run(lambda: self.transport.request("POST", "/logs/batch", json=payload))
+
+    def _build_event(self, *, event_type: str, payload: dict[str, Any], **kwargs) -> EventEnvelope:
+        context = get_context()
+        event = EventEnvelope(
+            event_type=event_type,
+            payload=payload,
+            source=kwargs.get("source") or (context.source if context else "python-sdk"),
+            trace_id=kwargs.get("trace_id") or (context.trace_id if context else None),
+            session_id=kwargs.get("session_id") or (context.session_id if context else None),
+            workflow_id=kwargs.get("workflow_id") or (context.workflow_id if context else None),
+            actor_id=kwargs.get("actor_id") or (context.agent_id if context else None),
+            actor_type=kwargs.get("actor_type", "agent"),
+            parent_event_id=kwargs.get("parent_event_id"),
+            root_event_id=kwargs.get("root_event_id"),
+            span_id=kwargs.get("span_id"),
+            attempt_no=kwargs.get("attempt_no", 1),
+            causality_type=kwargs.get("causality_type"),
+            agent_metadata=kwargs.get("agent_metadata", {}),
+        )
+        if not event.idempotency_key:
+            event.idempotency_key = self._idempotency_key(event)
+        return event
+
+    def _serialize(self, envelope: EventEnvelope) -> dict[str, Any]:
+        payload = {
+            "event_type": envelope.event_type,
+            "timestamp": envelope.timestamp.isoformat(),
+            "data": envelope.payload,
+            "source": envelope.source,
+            "idempotency_key": envelope.idempotency_key,
+            "trace_id": str(envelope.trace_id) if envelope.trace_id else None,
+            "session_id": str(envelope.session_id) if envelope.session_id else None,
+            "workflow_id": str(envelope.workflow_id) if envelope.workflow_id else None,
+            "parent_event_id": str(envelope.parent_event_id) if envelope.parent_event_id else None,
+            "root_event_id": str(envelope.root_event_id) if envelope.root_event_id else None,
+            "span_id": envelope.span_id,
+            "attempt_no": envelope.attempt_no,
+            "causality_type": envelope.causality_type,
+            "schema_version": envelope.schema_version,
+            "event_version": envelope.event_version,
+            "actor_type": envelope.actor_type,
+            "actor_id": envelope.actor_id,
+            "agent_metadata": envelope.agent_metadata,
+        }
+        payload = apply_hooks(payload, self.hooks)
+        if self.config.signing_key:
+            payload["log_signature"] = hash_sign(payload, private_key=self.config.signing_key)
+        return payload
+
+    @staticmethod
+    def _idempotency_key(envelope: EventEnvelope) -> str:
+        digest = sha256(
+            f"{envelope.event_type}:{envelope.source}:{envelope.trace_id}:{envelope.session_id}:{envelope.payload}".encode(
+                "utf-8"
+            )
+        ).hexdigest()[:32]
+        return f"blk_{digest}"
+

blocklog/compliance.py

@@ -0,0 +1,95 @@
+"""
+blocklog.compliance
+~~~~~~~~~~~~~~~~~~~
+Module-level namespace for compliance report generation.
+
+Usage (Layer 1)::
+
+    import blocklog
+
+    report = blocklog.compliance.generate(
+        trace_id="trace-abc",
+        framework="SOC2",
+    )
+    print(report["id"])
+
+    dashboard = blocklog.compliance.dashboard()
+    reports   = blocklog.compliance.list()
+    share_url = blocklog.compliance.share(report["id"], expires_in=86400)
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def generate(
+    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 for 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.
+    """
+    from blocklog._global import get_client
+    return get_client().compliance.generate(
+        trace_id=trace_id,
+        framework=framework,
+        date_from=date_from,
+        date_to=date_to,
+        metadata=metadata,
+    )
+
+
+def get(report_id: str) -> dict[str, Any]:
+    """Fetch a compliance report by ID."""
+    from blocklog._global import get_client
+    return get_client().compliance.get(report_id)
+
+
+def list() -> list[dict[str, Any]]:  # noqa: A001
+    """List all compliance reports for the company."""
+    from blocklog._global import get_client
+    return get_client().compliance.list()
+
+
+def dashboard() -> dict[str, Any]:
+    """Return the compliance dashboard summary."""
+    from blocklog._global import get_client
+    return get_client().compliance.dashboard()
+
+
+def share(
+    report_id: str,
+    *,
+    expires_in: int | None = None,
+    recipient_email: str | None = None,
+) -> dict[str, Any]:
+    """Create a shareable link for a compliance report."""
+    from blocklog._global import get_client
+    return get_client().compliance.share(
+        report_id=report_id,
+        expires_in=expires_in,
+        recipient_email=recipient_email,
+    )
+
+
+def export(report_id: str, *, download: bool = False) -> dict[str, Any]:
+    """Export a compliance report as JSON."""
+    from blocklog._global import get_client
+    return get_client().compliance.export(report_id=report_id, download=download)

blocklog/config.py

@@ -0,0 +1,17 @@
+from os import getenv
+
+from pydantic import BaseModel, Field
+
+
+class BlocklogConfig(BaseModel):
+    base_url: str = Field(default_factory=lambda: getenv("BLOCKLOG_BASE_URL", "http://127.0.0.1:8000/api/v1"))
+    api_key: str = Field(default_factory=lambda: getenv("BLOCKLOG_API_KEY", ""))
+    signing_key: str = Field(default_factory=lambda: getenv("BLOCKLOG_SDK_SIGNING_KEY", ""))
+    timeout: float = Field(default_factory=lambda: float(getenv("BLOCKLOG_TIMEOUT", "10")))
+    max_retries: int = Field(default_factory=lambda: int(getenv("BLOCKLOG_MAX_RETRIES", "3")))
+    batch_size: int = Field(default_factory=lambda: int(getenv("BLOCKLOG_BATCH_SIZE", "100")))
+    flush_interval: float = Field(default_factory=lambda: float(getenv("BLOCKLOG_FLUSH_INTERVAL", "2")))
+
+    @classmethod
+    def from_env(cls) -> "BlocklogConfig":
+        return cls()

blocklog/context/managers.py

@@ -0,0 +1,15 @@
+from contextlib import contextmanager
+
+from blocklog.models.events import SessionContext
+
+from .vars import set_context
+
+
+@contextmanager
+def agent_session(*, agent_id: str | None = None, source: str = "python-sdk", workflow_id=None):
+    context = SessionContext(agent_id=agent_id, source=source, workflow_id=workflow_id)
+    token = set_context(context)
+    try:
+        yield context
+    finally:
+        set_context(None)

blocklog/context/vars.py

@@ -0,0 +1,13 @@
+from contextvars import ContextVar
+
+from blocklog.models.events import SessionContext
+
+_context: ContextVar[SessionContext | None] = ContextVar("blocklog_context", default=None)
+
+
+def set_context(context: SessionContext | None):
+    return _context.set(context)
+
+
+def get_context() -> SessionContext | None:
+    return _context.get()

blocklog/decorators/__init__.py

@@ -0,0 +1,4 @@
+from blocklog.decorators.agent import agent
+from blocklog.decorators.tool import tool
+
+__all__ = ["agent", "tool"]

blocklog/decorators/agent.py

@@ -0,0 +1,219 @@
+"""
+blocklog.decorators.agent
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The ``@agent`` decorator — wraps a function (or class) so that every
+execution is automatically traced, timed, and linked to a Blocklog
+session.
+
+Usage::
+
+    import blocklog
+    blocklog.init(api_key="blk_...")
+
+    @blocklog.agent
+    def market_analyst():
+        ...
+
+    # With options:
+    @blocklog.agent(name="market-analyst", version="2.1", tags=["prod"])
+    def market_analyst():
+        ...
+
+    # On a class:
+    @blocklog.agent(name="hedge-fund-orchestrator")
+    class HedgeFundOrchestrator:
+        def run(self):
+            ...
+"""
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+import traceback as _traceback
+from datetime import datetime, timezone
+from typing import Any, Callable, TypeVar
+
+logger = logging.getLogger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def agent(
+    func: F | None = None,
+    *,
+    name: str | None = None,
+    version: str = "1.0",
+    tags: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> F | Callable[[F], F]:
+    """Decorator that traces an AI agent function or class.
+
+    Automatically:
+    - Opens a Blocklog ``agent_session`` (sets trace/session context)
+    - Emits ``AGENT_START`` event with agent name, version, tags
+    - Emits ``AGENT_COMPLETE`` event with duration on clean return
+    - Emits ``AGENT_ERROR`` event with traceback on exception
+
+    Can be used with or without arguments:
+
+    .. code-block:: python
+
+        @blocklog.agent
+        def my_agent(): ...
+
+        @blocklog.agent(name="my-agent", version="2.0")
+        def my_agent(): ...
+
+    Parameters
+    ----------
+    func:
+        The function to decorate (when used without arguments).
+    name:
+        Human-readable agent name.  Defaults to ``func.__name__``.
+    version:
+        Semver-style version string stored in agent metadata.
+    tags:
+        Optional list of string tags.
+    metadata:
+        Arbitrary extra data stored in the agent metadata.
+
+    Returns
+    -------
+    Callable
+        The decorated function (or a decorator if called with arguments).
+    """
+    def decorator(fn: F) -> F:
+        agent_name = name or fn.__name__
+        agent_meta = {
+            "agent_name": agent_name,
+            "agent_version": version,
+            "tags": tags or [],
+            **(metadata or {}),
+        }
+
+        if inspect.isclass(fn):
+            return _wrap_class(fn, agent_name, agent_meta)  # type: ignore[return-value]
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return _run_sync(fn, args, kwargs, agent_name, agent_meta)
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await _run_async(fn, args, kwargs, agent_name, agent_meta)
+
+        if inspect.iscoroutinefunction(fn):
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper  # type: ignore[return-value]
+
+    # Called as @agent (no args)
+    if func is not None:
+        return decorator(func)
+
+    # Called as @agent(...) — return the decorator
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _run_sync(fn: Callable, args: tuple, kwargs: dict, agent_name: str, meta: dict) -> Any:
+    from blocklog.context.managers import agent_session
+    started_at = _now()
+    with agent_session(agent_id=agent_name, source=f"agent:{agent_name}") as ctx:
+        _emit("AGENT_START", {
+            "agent_name": agent_name,
+            "started_at": started_at,
+            **meta,
+        }, ctx)
+        try:
+            result = fn(*args, **kwargs)
+            _emit("AGENT_COMPLETE", {
+                "agent_name": agent_name,
+                "duration_ms": _elapsed_ms(started_at),
+                "status": "ok",
+            }, ctx)
+            return result
+        except BaseException as exc:
+            _emit("AGENT_ERROR", {
+                "agent_name": agent_name,
+                "duration_ms": _elapsed_ms(started_at),
+                "error_type": type(exc).__name__,
+                "error_message": str(exc),
+                "traceback": _traceback.format_exc(),
+            }, ctx)
+            raise
+
+
+async def _run_async(fn: Callable, args: tuple, kwargs: dict, agent_name: str, meta: dict) -> Any:
+    from blocklog.context.managers import agent_session
+    started_at = _now()
+    with agent_session(agent_id=agent_name, source=f"agent:{agent_name}") as ctx:
+        _emit("AGENT_START", {
+            "agent_name": agent_name,
+            "started_at": started_at,
+            **meta,
+        }, ctx)
+        try:
+            result = await fn(*args, **kwargs)
+            _emit("AGENT_COMPLETE", {
+                "agent_name": agent_name,
+                "duration_ms": _elapsed_ms(started_at),
+                "status": "ok",
+            }, ctx)
+            return result
+        except BaseException as exc:
+            _emit("AGENT_ERROR", {
+                "agent_name": agent_name,
+                "duration_ms": _elapsed_ms(started_at),
+                "error_type": type(exc).__name__,
+                "error_message": str(exc),
+                "traceback": _traceback.format_exc(),
+            }, ctx)
+            raise
+
+
+def _wrap_class(cls: type, agent_name: str, meta: dict) -> type:
+    """Wrap the ``__init__`` of a class to open an agent session."""
+    original_init = cls.__init__
+
+    @functools.wraps(original_init)
+    def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+        from blocklog.context.managers import agent_session
+        from blocklog.context.vars import set_context
+        from blocklog.models.events import SessionContext
+
+        ctx = SessionContext(agent_id=agent_name, source=f"agent:{agent_name}")
+        set_context(ctx)
+        _emit("AGENT_START", {"agent_name": agent_name, **meta}, ctx)
+        original_init(self, *args, **kwargs)
+
+    cls.__init__ = new_init
+    return cls
+
+
+def _emit(event_type: str, payload: dict, ctx: Any) -> None:
+    try:
+        from blocklog._global import get_client
+        client = get_client()
+        client.event(
+            event_type,
+            payload=payload,
+            trace_id=str(ctx.trace_id) if ctx else None,
+            session_id=str(ctx.session_id) if ctx else None,
+            actor_id=ctx.agent_id if ctx else None,
+            actor_type="agent",
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("blocklog: emit %s failed: %s", event_type, exc)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _elapsed_ms(since_iso: str) -> int:
+    start = datetime.fromisoformat(since_iso)
+    return int((datetime.now(timezone.utc) - start).total_seconds() * 1000)