blocklog 0.2.0__py3-none-any.whl

blocklog/decorators/tool.py

@@ -0,0 +1,206 @@
+"""
+blocklog.decorators.tool
+~~~~~~~~~~~~~~~~~~~~~~~~
+The ``@tool`` decorator — wraps a function so every call is recorded as a
+``TOOL_CALL`` event, capturing inputs, outputs, duration, and errors.
+
+The decorator inherits the parent ``@agent`` trace context automatically.
+
+Usage::
+
+    import blocklog
+
+    @blocklog.tool
+    def fetch_price(ticker: str) -> float:
+        return market_api.get_price(ticker)
+
+    # With a custom name and schema hint:
+    @blocklog.tool(name="fetch-market-price", schema={"ticker": "str"})
+    def fetch_price(ticker: str) -> float:
+        ...
+"""
+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 tool(
+    func: F | None = None,
+    *,
+    name: str | None = None,
+    schema: dict[str, Any] | None = None,
+    tags: list[str] | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> F | Callable[[F], F]:
+    """Decorator that records a tool call as a Blocklog event.
+
+    Automatically captures:
+    - Function name, call arguments
+    - Return value
+    - Duration in milliseconds
+    - Any exception raised
+
+    Inherits the trace/session context set by the surrounding ``@agent``.
+
+    Can be used with or without arguments:
+
+    .. code-block:: python
+
+        @blocklog.tool
+        def my_tool(x: int) -> int: ...
+
+        @blocklog.tool(name="my-tool", tags=["external-api"])
+        def my_tool(x: int) -> int: ...
+
+    Parameters
+    ----------
+    func:
+        The function to decorate (when used without arguments).
+    name:
+        Human-readable tool name.  Defaults to ``func.__name__``.
+    schema:
+        Optional dict describing the input schema (for documentation /
+        dashboard display purposes).
+    tags:
+        Optional string tags.
+    metadata:
+        Arbitrary extra data stored with each tool call event.
+    """
+    def decorator(fn: F) -> F:
+        tool_name = name or fn.__name__
+        tool_meta = {
+            "tool_name": tool_name,
+            "tags": tags or [],
+            "schema": schema or {},
+            **(metadata or {}),
+        }
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return _run_sync(fn, args, kwargs, tool_name, tool_meta)
+
+        @functools.wraps(fn)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            return await _run_async(fn, args, kwargs, tool_name, tool_meta)
+
+        if inspect.iscoroutinefunction(fn):
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper  # type: ignore[return-value]
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _run_sync(fn: Callable, args: tuple, kwargs: dict, tool_name: str, meta: dict) -> Any:
+    started_at = _now()
+    call_args = _safe_args(fn, args, kwargs)
+    try:
+        result = fn(*args, **kwargs)
+        _emit("TOOL_CALL", {
+            **meta,
+            "inputs": call_args,
+            "output": _safe_repr(result),
+            "duration_ms": _elapsed_ms(started_at),
+            "status": "ok",
+        })
+        return result
+    except BaseException as exc:
+        _emit("TOOL_CALL", {
+            **meta,
+            "inputs": call_args,
+            "error_type": type(exc).__name__,
+            "error_message": str(exc),
+            "traceback": _traceback.format_exc(),
+            "duration_ms": _elapsed_ms(started_at),
+            "status": "error",
+        })
+        raise
+
+
+async def _run_async(fn: Callable, args: tuple, kwargs: dict, tool_name: str, meta: dict) -> Any:
+    started_at = _now()
+    call_args = _safe_args(fn, args, kwargs)
+    try:
+        result = await fn(*args, **kwargs)
+        _emit("TOOL_CALL", {
+            **meta,
+            "inputs": call_args,
+            "output": _safe_repr(result),
+            "duration_ms": _elapsed_ms(started_at),
+            "status": "ok",
+        })
+        return result
+    except BaseException as exc:
+        _emit("TOOL_CALL", {
+            **meta,
+            "inputs": call_args,
+            "error_type": type(exc).__name__,
+            "error_message": str(exc),
+            "traceback": _traceback.format_exc(),
+            "duration_ms": _elapsed_ms(started_at),
+            "status": "error",
+        })
+        raise
+
+
+def _emit(event_type: str, payload: dict) -> None:
+    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=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="tool",
+        )
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("blocklog: tool emit failed: %s", exc)
+
+
+def _safe_args(fn: Callable, args: tuple, kwargs: dict) -> dict:
+    """Build a safe dict of call arguments, best-effort."""
+    try:
+        sig = inspect.signature(fn)
+        bound = sig.bind(*args, **kwargs)
+        bound.apply_defaults()
+        return {k: _safe_repr(v) for k, v in bound.arguments.items()}
+    except Exception:  # noqa: BLE001
+        return {"args": str(args), "kwargs": str(kwargs)}
+
+
+def _safe_repr(value: Any) -> Any:
+    """Truncate large values so they don't bloat the event payload."""
+    if isinstance(value, (str, int, float, bool, type(None))):
+        return value
+    try:
+        s = repr(value)
+        return s if len(s) <= 512 else s[:509] + "..."
+    except Exception:  # noqa: BLE001
+        return "<unserializable>"
+
+
+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)

blocklog/incident.py

@@ -0,0 +1,89 @@
+"""
+blocklog.incident
+~~~~~~~~~~~~~~~~~
+Module-level namespace for incident management.
+
+Usage (Layer 1)::
+
+    from blocklog import incident
+
+    inc = incident.create(
+        title="Anomalous BUY signal on TSLA",
+        trace_id="trace-abc",
+        severity="high",
+    )
+
+    inc.assign("alice@fund.com")
+    inc.annotate("Reviewing related decisions from the same session")
+    inc.resolve(summary="False positive — model weights corrected")
+    inc.close()
+
+    report = inc.report()
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from blocklog.api.incidents import IncidentHandle
+
+
+def create(
+    title: str,
+    *,
+    trace_id: str | None = None,
+    severity: str = "medium",
+    description: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> "IncidentHandle":
+    """Create a new incident.
+
+    Parameters
+    ----------
+    title:
+        Short title describing the incident.
+    trace_id:
+        UUID of the trace associated with this incident.
+    severity:
+        ``"low"``, ``"medium"``, ``"high"``, or ``"critical"``.
+    description:
+        Longer free-text description.
+    metadata:
+        Arbitrary extra fields.
+
+    Returns
+    -------
+    IncidentHandle
+        A live handle with access to the full lifecycle (assign, resolve,
+        close, annotate, report, etc.).
+
+    Examples
+    --------
+    >>> inc = blocklog.incident.create(
+    ...     title="Unexpected SELL on AAPL",
+    ...     trace_id="trace-abc",
+    ...     severity="high",
+    ... )
+    >>> inc.assign("alice@fund.com")
+    >>> inc.resolve(summary="False positive")
+    """
+    from blocklog._global import get_client
+    return get_client().incidents.create(
+        title=title,
+        trace_id=trace_id,
+        severity=severity,
+        description=description,
+        metadata=metadata,
+    )
+
+
+def get(incident_id: str) -> "IncidentHandle":
+    """Fetch an existing incident by ID."""
+    from blocklog._global import get_client
+    return get_client().incidents.get(incident_id)
+
+
+def list_all() -> list["IncidentHandle"]:
+    """List all incidents for the authenticated company."""
+    from blocklog._global import get_client
+    return get_client().incidents.list()

blocklog/integrations/langchain.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from datetime import datetime, timezone
+from typing import Any
+
+
+class BlocklogLangChainCallbackHandler:
+    def __init__(self, client, *, source: str = "langchain") -> None:
+        self.client = client
+        self.source = source
+        self._last_run_id = None
+
+    def on_chain_start(self, serialized: dict[str, Any], inputs: dict[str, Any], *, run_id=None, parent_run_id=None, **kwargs):
+        self._last_run_id = run_id
+        self.client.event(
+            "agent.chain.started",
+            {
+                "serialized": serialized,
+                "inputs": inputs,
+                "parent_run_id": str(parent_run_id) if parent_run_id else None,
+            },
+            source=self.source,
+            span_id=str(run_id) if run_id else None,
+            causality_type="chain_start",
+            agent_metadata=_agent_metadata(
+                framework="langchain",
+                parent_run_id=parent_run_id,
+                extra=kwargs.get("metadata"),
+                context={
+                    "input_keys": sorted(inputs.keys()),
+                    "context_fetched_at": _utc_now(),
+                },
+            ),
+        )
+
+    def on_chain_end(self, outputs: dict[str, Any], *, run_id=None, parent_run_id=None, **kwargs):
+        self.client.event(
+            "agent.chain.completed",
+            {"outputs": outputs, "parent_run_id": str(parent_run_id) if parent_run_id else None},
+            source=self.source,
+            span_id=str(run_id or self._last_run_id) if (run_id or self._last_run_id) else None,
+            causality_type="chain_end",
+            agent_metadata=_agent_metadata(framework="langchain", parent_run_id=parent_run_id, extra=kwargs.get("metadata")),
+        )
+
+    def on_llm_start(self, serialized: dict[str, Any], prompts: Sequence[str], *, run_id=None, parent_run_id=None, **kwargs):
+        self.client.event(
+            "agent.model.started",
+            {"serialized": serialized, "prompts": list(prompts), "parent_run_id": str(parent_run_id) if parent_run_id else None},
+            source=self.source,
+            span_id=str(run_id) if run_id else None,
+            causality_type="llm_start",
+            agent_metadata=_agent_metadata(
+                framework="langchain",
+                parent_run_id=parent_run_id,
+                extra=kwargs.get("metadata"),
+                context={
+                    "prompt_count": len(prompts),
+                    "context_fetched_at": _utc_now(),
+                },
+            ),
+        )
+
+    def on_llm_end(self, response: Any, *, run_id=None, parent_run_id=None, **kwargs):
+        self.client.event(
+            "agent.model.completed",
+            {"response": _safe_model_dump(response), "parent_run_id": str(parent_run_id) if parent_run_id else None},
+            source=self.source,
+            span_id=str(run_id) if run_id else None,
+            causality_type="llm_end",
+            agent_metadata=_agent_metadata(framework="langchain", parent_run_id=parent_run_id, extra=kwargs.get("metadata")),
+        )
+
+    def on_tool_start(self, serialized: dict[str, Any], input_str: str, *, run_id=None, parent_run_id=None, **kwargs):
+        self.client.event(
+            "agent.tool.started",
+            {"serialized": serialized, "input": input_str, "parent_run_id": str(parent_run_id) if parent_run_id else None},
+            source=self.source,
+            span_id=str(run_id) if run_id else None,
+            causality_type="tool_start",
+            agent_metadata=_agent_metadata(
+                framework="langchain",
+                parent_run_id=parent_run_id,
+                extra=kwargs.get("metadata"),
+                context={"context_fetched_at": _utc_now()},
+            ),
+        )
+
+    def on_tool_end(self, output: Any, *, run_id=None, parent_run_id=None, **kwargs):
+        self.client.event(
+            "agent.tool.completed",
+            {"output": _safe_model_dump(output), "parent_run_id": str(parent_run_id) if parent_run_id else None},
+            source=self.source,
+            span_id=str(run_id) if run_id else None,
+            causality_type="tool_end",
+            agent_metadata=_agent_metadata(framework="langchain", parent_run_id=parent_run_id, extra=kwargs.get("metadata")),
+        )
+
+
+def instrument_langchain(client):
+    return BlocklogLangChainCallbackHandler(client)
+
+
+def _safe_model_dump(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump()
+    if hasattr(value, "dict"):
+        return value.dict()
+    if isinstance(value, (str, int, float, bool, list, dict)) or value is None:
+        return value
+    return str(value)
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _agent_metadata(*, framework: str, parent_run_id=None, extra: dict[str, Any] | None = None, context: dict[str, Any] | None = None) -> dict[str, Any]:
+    metadata = {
+        "framework": framework,
+        "captured_at": _utc_now(),
+        "parent_run_id": str(parent_run_id) if parent_run_id else None,
+    }
+    if context:
+        metadata.update(context)
+    if extra:
+        metadata.update(extra)
+    return metadata

blocklog/integrations/langgraph.py

@@ -0,0 +1,3 @@
+def instrument_langgraph(client):
+    client.add_hook(lambda payload: payload)
+    return client

blocklog/integrations/openai_agents.py

@@ -0,0 +1,3 @@
+def instrument_openai_agents(client):
+    client.add_hook(lambda payload: payload)
+    return client

blocklog/managers/__init__.py

@@ -0,0 +1,3 @@
+from blocklog.managers.decision import decision, DecisionContext
+
+__all__ = ["decision", "DecisionContext"]