openbox-langgraph-sdk-python 0.2.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

openbox_langgraph/__init__.py

@@ -17,6 +17,8 @@ Example:
     ... )
 """
 
+__version__ = "1.0.0"
+
 from openbox_langgraph.client import GovernanceClient, build_auth_headers
 from openbox_langgraph.config import (
     GovernanceConfig,
@@ -115,6 +117,7 @@ __all__ = [
     "WorkflowEventType",
     "WorkflowSpanBuffer",
     "WorkflowSpanProcessor",
+    "__version__",
     "build_agent_identity_canonical_request",
     "build_auth_headers",
     "create_agent_identity_headers",

openbox_langgraph/activity_context_binding.py

@@ -0,0 +1,126 @@
+"""Dual-write ActivityContext registration + per-turn cleanup for the opt-in
+base-SDK core runtime.
+
+`langgraph_handler.py` already registers trace/activity correlation with the
+legacy `WorkflowSpanProcessor` at every tool/LLM start and clears it at
+completion — that dual-write's counterpart lands here so the (opt-in, later
+phase) core hook runtime can resolve the SAME activity via
+`TraceContextRegistry` without the legacy processor's behavior changing by one
+line. This module is INERT unless a handler has an actual core runtime — see
+`should_dual_write`.
+
+Trace-only, never a ContextVar bind: LangGraph tool/LLM execution runs inside
+a spawned `asyncio.Task` (or, for sync tools, a `run_in_executor` worker
+thread) that already snapshot its ContextVar chain before this module's
+registration call can run — a bind here can never reach that code. See
+`core_runtime.py`'s module docstring and `tests/test_contextvars_propagation.py`
+for the empirical proof.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from openbox_core.contracts.context import ActivityContext
+from openbox_core.runtime import OpenBoxRuntime
+
+from openbox_langgraph.config import GovernanceConfig
+from openbox_langgraph.core_runtime import get_trace_registry
+
+__all__ = [
+    "build_activity_context",
+    "register_activity",
+    "should_dual_write",
+    "unregister_activity",
+]
+
+
+def should_dual_write(core_runtime: OpenBoxRuntime | None) -> bool:
+    """True only when the handler owns a real core runtime.
+
+    Handlers built with an injected `client` (e.g. a test double, or a
+    subclass overriding `evaluate_event`) have `core_runtime is None` by
+    construction (`langgraph_handler.py.__init__`) — this dual-write is
+    legacy-only for them, exactly like the gate-routing it mirrors.
+    """
+    return core_runtime is not None
+
+
+def build_activity_context(
+    *,
+    config: GovernanceConfig,
+    workflow_id: str,
+    run_id: str,
+    activity_id: str,
+    activity_type: str,
+    activity_input: Any = None,
+    langgraph_node: str | None = None,
+    langgraph_step: int | None = None,
+    tool_type: str | None = None,
+    tool_name: str | None = None,
+    tool_call_id: str | None = None,
+    subagent_name: str | None = None,
+    parent_ids: list[str] | None = None,
+) -> ActivityContext:
+    """Map one LangGraph activity boundary onto the base SDK's `ActivityContext`.
+
+    `workflow_id`/`run_id` are the PER-TURN ids `langgraph_handler.py` mints in
+    `ainvoke`/`astream_governed`/`astream`/`astream_events` (NOT LangGraph's own
+    per-node `run_id`, which becomes `activity_id` instead) — matching the
+    legacy governance event's own workflow_id/run_id fields exactly, so a hook
+    resolving this context reports the same turn a dashboard operator sees
+    from the legacy path.
+    """
+    metadata: dict[str, Any] = {}
+    if langgraph_node is not None:
+        metadata["node"] = langgraph_node
+    if langgraph_step is not None:
+        metadata["step"] = langgraph_step
+    if tool_type is not None:
+        metadata["tool_type"] = tool_type
+    if tool_name is not None:
+        metadata["tool_name"] = tool_name
+    if tool_call_id is not None:
+        metadata["tool_call_id"] = tool_call_id
+    if subagent_name is not None:
+        metadata["subagent_name"] = subagent_name
+    if parent_ids:
+        metadata["parent_ids"] = list(parent_ids)
+
+    return ActivityContext(
+        workflow_id=workflow_id,
+        run_id=run_id,
+        workflow_type=config.agent_name or "LangGraphRun",
+        task_queue=config.task_queue or "langgraph",
+        activity_id=activity_id,
+        activity_type=activity_type,
+        activity_input=activity_input,
+        agent_name=config.agent_name,
+        session_id=config.session_id,
+        multi_agent_session_id=config.multi_agent_session_id,
+        metadata=metadata,
+    )
+
+
+def register_activity(
+    core_runtime: OpenBoxRuntime | None,
+    trace_id: int,
+    ctx: ActivityContext,
+) -> None:
+    """Trace-only dual-write into the runtime's private `TraceContextRegistry`.
+
+    No-op when `core_runtime` is `None` (injected-client handlers) — see
+    `should_dual_write`. Skips a zero/falsy `trace_id` the same way the legacy
+    `if trace_id:` guard at the call site already does, so a degraded OTel
+    span (no active provider) never registers a bogus all-zero correlation.
+    """
+    if core_runtime is None or not trace_id:
+        return
+    get_trace_registry(core_runtime).register(trace_id, ctx)
+
+
+def unregister_activity(core_runtime: OpenBoxRuntime | None, trace_id: int | None) -> None:
+    """Counterpart cleanup for `register_activity` — activity completion."""
+    if core_runtime is None or not trace_id:
+        return
+    get_trace_registry(core_runtime).unregister(trace_id)

openbox_langgraph/client.py

@@ -5,11 +5,17 @@ from __future__ import annotations
 import json
 import os
 from dataclasses import dataclass
-from datetime import UTC
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import httpx
-
+from openbox_core.client import check_expiration
+from openbox_core.contracts.results import EvaluationResult
+from openbox_core.contracts.results import Verdict as _CoreVerdict
+from openbox_core.errors import ContractError as _CoreContractError
+from openbox_core.errors import GovernanceAPIError as _CoreGovernanceAPIError
+from openbox_core.errors import OpenBoxNetworkError as _CoreOpenBoxNetworkError
+
+from openbox_langgraph.core_events import to_envelope
 from openbox_langgraph.errors import OpenBoxConfigError, OpenBoxNetworkError
 from openbox_langgraph.identity import (
     AgentIdentityConfig,
@@ -25,7 +31,107 @@ from openbox_langgraph.types import (
     to_server_event_type,
 )
 
-_SDK_VERSION = "0.2.0"
+if TYPE_CHECKING:
+    from openbox_core.gate import GovernanceGate
+
+_SDK_PACKAGE_VERSION = "1.0.0"
+_SDK_IDENTIFIER = f"openbox-langgraph-python-v{_SDK_PACKAGE_VERSION}"
+
+
+def _network_fallback_result(on_api_error: str, msg: str) -> GovernanceVerdictResponse | None:
+    """Apply the `on_api_error` policy to a NETWORK/transport failure.
+
+    This is the ONLY place a `GovernanceClient` verdict call may return
+    `None` — it corresponds exactly to a client-synthesized fallback
+    (`EvaluationResult.fallback_allow`): `verdict=ALLOW`, `fallback_used=True`,
+    and an EMPTY `raw` dict (nothing was ever parsed from a real body).
+
+    A response BODY that happens to be `{"verdict": "block",
+    "fallback_used": true}` never reaches this function — it is parsed by
+    `_verdict_from_response_data` instead, whose `raw` is always the
+    non-empty parsed dict, so the None-collapse below can never fire for it
+    and the BLOCK is enforced normally.
+
+    `msg` is the caller's fully-formatted message (kept caller-side so the
+    two distinct failure messages — "Governance API error: HTTP {status}"
+    for a bad response, "Governance API unreachable: {e}" for a raised
+    exception — stay exactly as they were before this translation layer).
+    """
+    if on_api_error == "fail_closed":
+        raise OpenBoxNetworkError(msg)
+    result = EvaluationResult.fallback_allow(msg)
+    return _collapse_client_synthesized_fallback(result)
+
+
+def _verdict_from_response_data(data: dict[str, Any]) -> GovernanceVerdictResponse:
+    """Parse a real HTTP response body into a `GovernanceVerdictResponse`.
+
+    Routed through the base SDK's `EvaluationResult.from_dict` so `raw` is
+    always the full parsed body — the non-empty `raw` is exactly what keeps
+    `_collapse_client_synthesized_fallback` from ever mistaking a real
+    (even oddly-shaped) Core response for a client-side fallback.
+    """
+    return GovernanceVerdictResponse.from_result(EvaluationResult.from_dict(data))
+
+
+def _collapse_client_synthesized_fallback(
+    result: EvaluationResult,
+) -> GovernanceVerdictResponse | None:
+    """Return `None` ONLY for a client-synthesized fail-open fallback.
+
+    The three-part discriminator matches `EvaluationResult.fallback_allow`
+    exactly and nothing else: `fallback_used=True` AND `verdict is ALLOW` AND
+    `raw` is empty (no real body was ever parsed). A response body that
+    happens to carry `fallback_used: true` alongside a blocking verdict, or
+    alongside ALLOW but WITH a real (non-empty) body, is a real Core response
+    and must be returned as a `GovernanceVerdictResponse` so callers enforce
+    it — never silently collapsed to `None`/implicit-ALLOW.
+    """
+    if result.fallback_used and result.verdict is _CoreVerdict.ALLOW and not result.raw:
+        return None
+    return GovernanceVerdictResponse.from_result(result)
+
+
+async def _gate_evaluate(
+    gate: GovernanceGate, event: LangChainGovernanceEvent, on_api_error: str
+) -> GovernanceVerdictResponse | None:
+    """Evaluate one lifecycle event through the base SDK's strict gate.
+
+    The single translation seam between `gate.aevaluate`'s base-SDK contract
+    (`EvaluationResult`, `openbox_core` exceptions) and this SDK's own
+    (`GovernanceVerdictResponse | None`, `openbox_langgraph.errors`) — every
+    gate-routed call site in `evaluate_event` goes through this function so
+    the translation is defined exactly once. Outcome policy (mirrors the legacy
+    httpx path so the wired transport is behaviourally interchangeable):
+
+    - `EvaluationResult.fallback_allow()` (client-synthesized fail-open on a
+      NETWORK error): collapsed to `None` via the same discriminator used for
+      the legacy path, so the pre-screen-`None` -> callback re-evaluation ->
+      PII-redaction flow keeps firing regardless of which transport produced it.
+    - `ContractError` (a malformed envelope — a bug in THIS SDK's own
+      event->envelope mapping, raised pre-network by the strict gate, never
+      from a Core response): ALWAYS a fail-open telemetry-drop (`None`),
+      independent of `on_api_error`. Enforcing fail_closed here would let an
+      SDK-side mapping defect block a user's graph for a reason their OWN policy
+      never produced — strictly worse than dropping one governance event.
+    - `GovernanceAPIError` / `OpenBoxNetworkError` (network-shaped failure) ->
+      this SDK's `OpenBoxNetworkError`, same public exception the legacy path
+      raises under fail_closed.
+    - Any OTHER exception (e.g. a malformed Core 200 body the base parser
+      cannot decode) is a transport-shaped fault, NOT a governance verdict:
+      routed through `_network_fallback_result` so fail_open returns `None`
+      (never crash the graph on a Core hiccup) and fail_closed raises
+      `OpenBoxNetworkError` — matching the legacy httpx catch-all exactly.
+    """
+    try:
+        result = await gate.aevaluate(to_envelope(event))
+    except _CoreContractError:
+        return None
+    except (_CoreGovernanceAPIError, _CoreOpenBoxNetworkError) as e:
+        raise OpenBoxNetworkError(str(e)) from e
+    except Exception as e:
+        return _network_fallback_result(on_api_error, f"Governance gate error: {e}")
+    return _collapse_client_synthesized_fallback(result)
 
 
 def build_auth_headers(
@@ -38,13 +144,13 @@ def build_auth_headers(
 ) -> dict[str, str]:
     """Build standard auth headers for governance API calls.
 
-    Single source of truth — used by GovernanceClient and hook_governance.
+    Single source of truth for the SDK's outbound governance requests.
     """
     headers = {
         "Authorization": f"Bearer {api_key}",
         "Content-Type": "application/json",
-        "User-Agent": f"OpenBox-LangGraph-SDK/{_SDK_VERSION}",
-        "X-OpenBox-SDK-Version": _SDK_VERSION,
+        "User-Agent": f"OpenBox-LangGraph-SDK/{_SDK_IDENTIFIER}",
+        "X-OpenBox-SDK-Version": _SDK_IDENTIFIER,
     }
     if agent_identity:
         if method is None or pathname is None:
@@ -87,6 +193,7 @@ class GovernanceClient:
         on_api_error: str = "fail_open",
         agent_did: str | None = None,
         agent_private_key: str | None = None,
+        gate: GovernanceGate | None = None,
     ) -> None:
         self._api_url = api_url.rstrip("/")
         self._api_key = api_key
@@ -98,9 +205,19 @@ class GovernanceClient:
             did=agent_did,
             private_key=agent_private_key,
         )
+        # Optional base-SDK gate. When wired (by the handler, from a core
+        # runtime built off the SAME api_url/api_key/timeout/on_api_error),
+        # `evaluate_event`'s ASYNC path routes lifecycle events through it
+        # instead of this client's own httpx transport — see `evaluate_event`.
+        # `None` (the default) preserves the exact legacy transport/serialization
+        # for every existing caller that constructs a bare `GovernanceClient()`.
+        # `evaluate_event_sync` (sync middleware hooks) is unaffected either way.
+        self._gate = gate
         # Deduplication: prevent sending the same (activity_id, event_type) twice
         # within the same workflow run. Keyed by (workflow_id, run_id) so it resets
-        # automatically on each new ainvoke() call.
+        # automatically on each new ainvoke() call. Shared by every evaluate_event
+        # call site regardless of which transport (gate or legacy httpx) is active
+        # for a given call — dedup is a client-level concern, not a transport one.
         self._dedup_run: tuple[str, str] | None = None
         self._dedup_sent: set[tuple[str, str]] = set()
 
@@ -186,13 +303,23 @@ class GovernanceClient:
         """Send a governance event to OpenBox Core and return the verdict.
 
         Returns `None` on network failure when `on_api_error` is `fail_open`.
-        Silently drops duplicate (activity_id, event_type) pairs within the same run.
+        Silently drops duplicate (activity_id, event_type) pairs within the same run
+        — this de-dup pre-check runs BEFORE either transport below, so it applies
+        identically whether a `gate` is wired or not.
+
+        When a `gate` was supplied at construction (see `__init__`), the event is
+        routed through the base SDK's `EventEnvelope` + `GovernanceGate.aevaluate`
+        instead of this client's own httpx transport — see `_gate_evaluate`.
+        Overriding `evaluate_event` in a subclass (e.g. the golden-fixture
+        harness's `RecordingGovernanceClient`) still fully intercepts either way,
+        since the branch lives inside THIS method, never at a call site.
 
         Args:
             event: The governance event payload to evaluate.
 
         Raises:
-            OpenBoxNetworkError: On network failure when `on_api_error` is `fail_closed`.
+            OpenBoxNetworkError: On network failure when `on_api_error` is `fail_closed`
+                (from either transport).
         """
         server_event_type = to_server_event_type(event.event_type)
         if event.activity_id and self._is_duplicate(
@@ -205,18 +332,22 @@ class GovernanceClient:
                 )
             return None
 
-        payload = event.to_dict()
-        payload["event_type"] = server_event_type
-        payload["task_queue"] = event.task_queue or "langgraph"
-        payload["source"] = "workflow-telemetry"
-
         if os.environ.get("OPENBOX_DEBUG") == "1":
             import json
 
             print(
-                f"[OpenBox Debug] governance request: {json.dumps(payload, indent=2, default=str)}"
+                f"[OpenBox Debug] governance request: "
+                f"{json.dumps(event.to_dict(), indent=2, default=str)}"
             )
 
+        if self._gate is not None:
+            return await _gate_evaluate(self._gate, event, self._on_api_error)
+
+        payload = event.to_dict()
+        payload["event_type"] = server_event_type
+        payload["task_queue"] = event.task_queue or "langgraph"
+        payload["source"] = "workflow-telemetry"
+
         try:
             client = self._get_client()
             body = _json_body(payload)
@@ -231,21 +362,19 @@ class GovernanceClient:
             )
 
             if not response.is_success:
-                if self._on_api_error == "fail_closed":
-                    msg = f"Governance API error: HTTP {response.status_code}"
-                    raise OpenBoxNetworkError(msg)
-                return None
+                return _network_fallback_result(
+                    self._on_api_error, f"Governance API error: HTTP {response.status_code}"
+                )
 
             data = response.json()
-            return GovernanceVerdictResponse.from_dict(data)
+            return _verdict_from_response_data(data)
 
         except OpenBoxNetworkError:
             raise
         except Exception as e:
-            if self._on_api_error == "fail_closed":
-                msg = f"Governance API unreachable: {e}"
-                raise OpenBoxNetworkError(msg) from e
-            return None
+            return _network_fallback_result(
+                self._on_api_error, f"Governance API unreachable: {e}"
+            )
 
     def evaluate_event_sync(
         self, event: LangChainGovernanceEvent
@@ -288,21 +417,19 @@ class GovernanceClient:
             )
 
             if not response.is_success:
-                if self._on_api_error == "fail_closed":
-                    msg = f"Governance API error: HTTP {response.status_code}"
-                    raise OpenBoxNetworkError(msg)
-                return None
+                return _network_fallback_result(
+                    self._on_api_error, f"Governance API error: HTTP {response.status_code}"
+                )
 
             data = response.json()
-            return GovernanceVerdictResponse.from_dict(data)
+            return _verdict_from_response_data(data)
 
         except OpenBoxNetworkError:
             raise
         except Exception as e:
-            if self._on_api_error == "fail_closed":
-                msg = f"Governance API unreachable: {e}"
-                raise OpenBoxNetworkError(msg) from e
-            return None
+            return _network_fallback_result(
+                self._on_api_error, f"Governance API unreachable: {e}"
+            )
 
     async def poll_approval(self, params: ApprovalPollParams) -> ApprovalResponse | None:
         """Poll for HITL approval status.
@@ -335,19 +462,15 @@ class GovernanceClient:
                 return None
 
             data = response.json()
-            parsed = parse_approval_response(data)
-
-            # SDK-side expiration check
-            if parsed.approval_expiration_time and not parsed.expired:
-                from datetime import datetime
-
-                expiry = datetime.fromisoformat(
-                    parsed.approval_expiration_time.replace("Z", "+00:00")
-                )
-                if expiry < datetime.now(tz=UTC):
-                    parsed.expired = True
-
-            return parsed
+            # SDK-side expiration check — run on the raw dict BEFORE parsing
+            # (matches openbox_core.client.check_expiration's own call order:
+            # check_expiration(data) then ApprovalResult.from_dict(data)).
+            # Handles ISO 'Z', ISO offset, and space-separated DB timestamp
+            # formats; a malformed timestamp is logged and left un-flagged
+            # rather than raised, so one bad timestamp string degrades to
+            # "expiration not confirmed" instead of aborting the whole poll.
+            check_expiration(data)
+            return parse_approval_response(data)
 
         except Exception:
             return None

openbox_langgraph/config.py

@@ -80,9 +80,37 @@ class GovernanceConfig:
     skip_tool_types: set[str] = field(default_factory=set)
     hitl: HITLConfig = field(default_factory=HITLConfig)
     session_id: str | None = None
+    multi_agent_session_id: str | None = None
+    """Optional multi-agent session correlation id, distinct from `session_id`.
+
+    Threaded onto the base SDK's `ActivityContext.multi_agent_session_id` at
+    activity-boundary dual-write registration — never mixed into `session_id`,
+    which stays the single-agent chat-session identifier the legacy governance
+    events already carry."""
     agent_name: str | None = None
     task_queue: str = "langgraph"
     use_native_interrupt: bool = False
+    use_core_instrumentation: bool = True
+    """Route hook governance through the shared ``openbox_core`` base
+    instrumentation — the only hook runtime. Default ``True``. Setting it
+    ``False`` fails fast (``OpenBoxConfigError``): legacy in-repo hook
+    governance has been removed, so there is nothing to fall back to."""
+    strict_activity_context: bool = False
+    """Fail loudly when a tool cannot be bound to a proven ActivityContext.
+
+    A tool run is bindable only inside a governed turn — the handler supplies
+    the turn's ``workflow_id``/``run_id`` down each tool's ``RunnableConfig``.
+    When that turn identity is absent (e.g. a tool driven outside the handler),
+    the ToolNode binder cannot prove which activity a hook span belongs to.
+
+    Default ``False``: log a warning once per such invocation and execute the
+    tool UNBOUND (its hook spans stay intentionally unattached — never guessed).
+    ``True`` (a test/debug aid): raise ``OpenBoxConfigError`` BEFORE the tool
+    body runs, so the tool never executes unbound. Note the raise is thrown from
+    inside the ``ToolNode`` call, so a ``ToolNode`` with the default
+    ``handle_tool_errors=True`` converts it into an error ``ToolMessage``
+    (loud and visible, tool still not run) rather than propagating; build the
+    ``ToolNode`` with ``handle_tool_errors=False`` to make it hard-fail the run."""
     root_node_names: set[str] = field(default_factory=set)
     tool_type_map: dict[str, str] = field(default_factory=dict)
     """Optional mapping of tool name → tool_type for execution tree classification.
@@ -142,9 +170,12 @@ def merge_config(partial: dict[str, Any] | None = None) -> GovernanceConfig:
         skip_tool_types=_to_set(partial.get("skip_tool_types")),
         hitl=hitl,
         session_id=partial.get("session_id"),
+        multi_agent_session_id=partial.get("multi_agent_session_id"),
         agent_name=partial.get("agent_name"),
         task_queue=partial.get("task_queue", "langgraph"),
         use_native_interrupt=partial.get("use_native_interrupt", False),
+        use_core_instrumentation=partial.get("use_core_instrumentation", True),
+        strict_activity_context=partial.get("strict_activity_context", False),
         root_node_names=_to_set(partial.get("root_node_names")),
         tool_type_map=tool_type_map,
     )