openbox-langgraph-sdk-python 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

openbox_langgraph/config.py

@@ -250,9 +250,12 @@ def initialize(
     validate_url_security(api_url)
 
     if not validate_api_key_format(api_key):
+        # Show only the structural prefix, never actual secret chars
+        parts = api_key.split("_", 2)
+        prefix_hint = "_".join(parts[:2]) + "_..." if len(parts) >= 2 else "???"
         msg = (
             f"Invalid API key format. Expected 'obx_live_*' or 'obx_test_*', "
-            f"got: '{api_key[:15]}...' (showing first 15 chars)"
+            f"got prefix: '{prefix_hint}'"
         )
         raise OpenBoxAuthError(msg)
 

openbox_langgraph/file_governance_hooks.py

@@ -72,8 +72,14 @@ def _build_file_span_data(
     }
 
     # Only include optional fields if they have values
+    # Truncate file content to prevent oversized governance payloads
+    _MAX_FILE_DATA = 4096
     if data is not None:
-        result["data"] = data
+        data_str = str(data)
+        if len(data_str) > _MAX_FILE_DATA:
+            result["data"] = data_str[:_MAX_FILE_DATA] + "...[truncated]"
+        else:
+            result["data"] = data_str
     if bytes_read is not None:
         result["bytes_read"] = bytes_read
     if bytes_written is not None:

openbox_langgraph/http_governance_hooks.py

@@ -64,6 +64,34 @@ _TEXT_CONTENT_TYPES = (
     "application/x-www-form-urlencoded",
 )
 
+# Headers that must be redacted before sending to governance API
+_SENSITIVE_HEADERS = frozenset({
+    "authorization", "cookie", "set-cookie", "x-api-key",
+    "x-auth-token", "proxy-authorization", "www-authenticate",
+})
+
+# Max body size sent to governance API (bytes of string repr)
+_MAX_BODY_CAPTURE = 8192
+
+
+def _sanitize_headers(headers: dict | None) -> dict | None:
+    """Redact sensitive headers (auth tokens, cookies) before governance."""
+    if not headers:
+        return headers
+    return {
+        k: "[REDACTED]" if k.lower() in _SENSITIVE_HEADERS else v
+        for k, v in headers.items()
+    }
+
+
+def _truncate_body(body: str | None) -> str | None:
+    """Truncate body to _MAX_BODY_CAPTURE to prevent oversized payloads."""
+    if body is None:
+        return None
+    if len(body) > _MAX_BODY_CAPTURE:
+        return body[:_MAX_BODY_CAPTURE] + "...[truncated]"
+    return body
+
 
 # ═══════════════════════════════════════════════════════════════════════════════
 # Shared HTTP utilities
@@ -136,10 +164,10 @@ def _build_http_span_data(
         # HTTP-specific root fields
         "http_method": http_method,
         "http_url": http_url,
-        "request_body": request_body,
-        "request_headers": request_headers,
-        "response_body": response_body,
-        "response_headers": response_headers,
+        "request_body": _truncate_body(request_body),
+        "request_headers": _sanitize_headers(request_headers),
+        "response_body": _truncate_body(response_body),
+        "response_headers": _sanitize_headers(response_headers),
         "http_status_code": http_status_code,
         "error": error,
     }

openbox_langgraph/types.py

@@ -39,10 +39,13 @@ class Verdict(StrEnum):
 
     @property
     def priority(self) -> int:
-        """Priority for aggregation: HALT=5, BLOCK=4, REQUIRE_APPROVAL=3, CONSTRAIN=2, ALLOW=1"""
+        """Priority for aggregation: HALT=4, BLOCK=3, REQUIRE_APPROVAL=2, CONSTRAIN=1, ALLOW=0.
+
+        Matches OpenBox Core's Verdict enum (0-indexed, governance.go).
+        """
         return {
-            Verdict.ALLOW: 1, Verdict.CONSTRAIN: 2, Verdict.REQUIRE_APPROVAL: 3,
-            Verdict.BLOCK: 4, Verdict.HALT: 5,
+            Verdict.ALLOW: 0, Verdict.CONSTRAIN: 1, Verdict.REQUIRE_APPROVAL: 2,
+            Verdict.BLOCK: 3, Verdict.HALT: 4,
         }[self]
 
     @classmethod

{openbox_langgraph_sdk_python-0.1.0.dist-info → openbox_langgraph_sdk_python-0.1.2.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: openbox-langgraph-sdk-python
-Version: 0.1.0
+Version: 0.1.2
 Summary: OpenBox governance and observability SDK for LangGraph
 License: MIT
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain-core>=1.2.22
 Requires-Dist: langgraph>=0.2.0
 Requires-Dist: opentelemetry-api>=1.20.0
 Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.41b0
@@ -35,21 +35,21 @@ Requires-Dist: opentelemetry-instrumentation-urllib>=0.41b0; extra == 'otel'
 Requires-Dist: opentelemetry-sdk>=1.20.0; extra == 'otel'
 Description-Content-Type: text/markdown
 
-# openbox-langgraph-sdk
+# openbox-langgraph-sdk-python
 
-[![PyPI](https://img.shields.io/pypi/v/openbox-langgraph-sdk)](https://pypi.org/project/openbox-langgraph-sdk/)
-[![Python](https://img.shields.io/pypi/pyversions/openbox-langgraph-sdk)](https://pypi.org/project/openbox-langgraph-sdk/)
+[![PyPI](https://img.shields.io/pypi/v/openbox-langgraph-sdk-python)](https://pypi.org/project/openbox-langgraph-sdk-python/)
+[![Python](https://img.shields.io/pypi/pyversions/openbox-langgraph-sdk-python)](https://pypi.org/project/openbox-langgraph-sdk-python/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 Real-time governance and observability for [LangGraph](https://github.com/langchain-ai/langgraph) agents — powered by [OpenBox](https://openbox.ai).
 
-**OpenBox** sits between your agent and the world. Every tool call, LLM prompt, and subagent dispatch passes through a policy engine before it executes. You write policies in [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/); OpenBox enforces them — blocking harmful actions, screening for PII, and routing sensitive operations to a human approver — all without changing your agent code.
+**OpenBox** sits between your agent and the world. Every tool call, LLM prompt, HTTP request, database query, and file operation passes through a policy engine before it executes. You write policies in [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/); OpenBox enforces them — blocking harmful actions, screening for PII, and routing sensitive operations to a human approver — all without changing your agent code.
 
 ---
 
 ## Table of Contents
 
-- [How it works](#how-it-works)
+- [Architecture](#architecture)
 - [Installation](#installation)
 - [Quickstart](#quickstart)
 - [Configuration reference](#configuration-reference)
@@ -59,6 +59,11 @@ Real-time governance and observability for [LangGraph](https://github.com/langch
   - [Human-in-the-loop (HITL)](#human-in-the-loop-hitl)
   - [Behavior Rules (AGE)](#behavior-rules-age)
   - [Tool classification](#tool-classification)
+- [Hook governance](#hook-governance)
+  - [HTTP hooks](#http-hooks)
+  - [Database hooks](#database-hooks)
+  - [File I/O hooks](#file-io-hooks)
+  - [Custom function tracing](#custom-function-tracing)
 - [Error handling](#error-handling)
 - [Advanced usage](#advanced-usage)
 - [Debugging](#debugging)
@@ -66,21 +71,38 @@ Real-time governance and observability for [LangGraph](https://github.com/langch
 
 ---
 
-## How it works
+## Architecture
+
+The SDK has three governance layers that intercept operations at different levels:
 
 ```
-Your code                SDK                         OpenBox Core
-──────────               ───                         ────────────
-governed.ainvoke()  →  streams LangGraph events  →  Policy engine (OPA / Rego)
-                       on_tool_start              →  Guardrails (PII, toxicity…)
-                       on_chat_model_start        →  Behavior Rules (AGE)
-                       on_chain_start             →  HITL approval queue
-                            ↑
-                       enforce verdict
-                       (allow / block / redact / pause)
+Your code                 SDK (3 layers)                              OpenBox Core
+──────────                ──────────────                              ────────────
+
+governed.ainvoke()
+  │
+  ├─ Layer 1: LangGraph Event Stream (langgraph_handler.py)
+  │    on_tool_start/end  ─────────────────────────────────────────→  Policy engine
+  │    on_chat_model_start/end  ───────────────────────────────────→  Guardrails
+  │    on_chain_start/end  ────────────────────────────────────────→  HITL queue
+  │         ↑ enforce verdict (allow / block / redact / pause)
+  │
+  ├─ Layer 2: Hook Governance (http/db/file hooks)
+  │    httpx/requests outbound calls  ─────────────────────────────→  Behavior Rules (AGE)
+  │    SQL queries (psycopg2, asyncpg, pymongo, redis, SQLAlchemy) →  Per-operation policies
+  │    File I/O (open, read, write)  ──────────────────────────────→  File access policies
+  │         ↑ block before operation executes (started stage)
+  │
+  └─ Layer 3: Activity Context (span_processor.py)
+       Maps trace_id → governance activity_id
+       Links hook-level operations to the tool call that triggered them
 ```
 
-The SDK wraps your compiled LangGraph graph and intercepts every event in the [LangGraph v2 event stream](https://langchain-ai.github.io/langgraph/how-tos/streaming-events-from-within-tools/). It sends governance events to OpenBox Core, receives verdicts, and enforces them — all before your tool or LLM call continues.
+**Layer 1** wraps your compiled LangGraph graph and intercepts the [v2 event stream](https://langchain-ai.github.io/langgraph/how-tos/streaming-events-from-within-tools/). It sends governance events (WorkflowStarted, ActivityStarted, etc.) to OpenBox Core and enforces verdicts.
+
+**Layer 2** uses built-in instrumentation to intercept low-level operations (HTTP requests, DB queries, file I/O) made by your tools. Each operation is evaluated at two stages: `started` (can block) and `completed` (informational).
+
+**Layer 3** maintains the mapping between traces and governance activities, so Layer 2 hooks know which tool call each operation belongs to.
 
 **Zero graph changes required.** You keep writing LangGraph exactly as you normally would.
 
@@ -89,10 +111,18 @@ The SDK wraps your compiled LangGraph graph and intercepts every event in the [L
 ## Installation
 
 ```bash
-pip install openbox-langgraph-sdk
+pip install openbox-langgraph-sdk-python
 ```
 
-**Requirements:** Python 3.11+, `langgraph >= 0.2`, `langchain-core >= 0.2`
+Or with `uv`:
+
+```bash
+uv add openbox-langgraph-sdk-python
+```
+
+**Requirements:** Python 3.11+, `langgraph >= 0.2`, `langchain-core >= 0.3`
+
+**Included instrumentation libraries:** The package includes built-in instrumentors for `httpx`, `requests`, `urllib3`, `psycopg2`, `asyncpg`, `mysql`, `pymysql`, `pymongo`, `redis`, `sqlalchemy`, and `sqlite3`. These are activated automatically when you create the handler.
 
 ---
 
@@ -123,7 +153,7 @@ llm = ChatOpenAI(model="gpt-4o-mini")
 agent = create_react_agent(llm, tools=[search_web, write_file])
 
 async def main():
-    governed = await create_openbox_graph_handler(
+    governed = create_openbox_graph_handler(
         graph=agent,
         api_url=os.environ["OPENBOX_URL"],
         api_key=os.environ["OPENBOX_API_KEY"],
@@ -139,15 +169,15 @@ async def main():
 asyncio.run(main())
 ```
 
-That's it. Your agent now sends governance events to OpenBox on every tool call and LLM prompt.
+That's it. Your agent now sends governance events to OpenBox on every tool call, LLM prompt, HTTP request, and database query.
 
 ### Try it locally (included test agent)
 
-This repository includes a runnable LangGraph test agent under `sdk-langgraph-python/test-agent`.
+The repository includes a runnable LangGraph test agent under `test-agent/`.
 
-It is designed to validate:
+It validates:
 
-- **Guardrails** on `agent_validatePrompt`
+- **Guardrails** on LLM prompts
 - **Policies** on tool invocations (BLOCK / REQUIRE_APPROVAL)
 - **HITL** approval polling
 - **Behavior Rules (AGE)** via `httpx` spans from `search_web`
@@ -165,20 +195,23 @@ See `test-agent/README.md` for setup and run instructions.
 | `graph` | `CompiledGraph` | **required** | Your compiled LangGraph graph |
 | `api_url` | `str` | **required** | Base URL of your OpenBox Core instance |
 | `api_key` | `str` | **required** | API key (`obx_live_*` or `obx_test_*`) |
-| `agent_name` | `str` | `None` | Agent name as configured in the dashboard (used for policy lookup and execution tree) |
+| `agent_name` | `str` | `None` | Agent name as configured in the dashboard |
 | `validate` | `bool` | `True` | Validate API key against server on startup |
 | `on_api_error` | `str` | `"fail_open"` | `"fail_open"` (allow on error) or `"fail_closed"` (block on error) |
 | `governance_timeout` | `float` | `30.0` | HTTP timeout in seconds for governance calls |
 | `session_id` | `str` | `None` | Optional session identifier for multi-session agents |
 | `task_queue` | `str` | `"langgraph"` | Task queue label attached to all governance events |
 | `hitl` | `dict` | `{}` | Human-in-the-loop config (see [HITL](#human-in-the-loop-hitl)) |
-| `tool_type_map` | `dict[str, str]` | `{}` | Map tool names to semantic types for policy classification (see [Tool classification](#tool-classification)) |
-| `skip_chain_types` | `set[str]` | `set()` | Chain node names to skip (no governance event sent) |
+| `tool_type_map` | `dict[str, str]` | `{}` | Map tool names to semantic types (see [Tool classification](#tool-classification)) |
+| `skip_chain_types` | `set[str]` | `set()` | Chain node names to skip |
 | `skip_tool_types` | `set[str]` | `set()` | Tool names to skip entirely |
 | `send_chain_start_event` | `bool` | `True` | Send `WorkflowStarted` event |
 | `send_chain_end_event` | `bool` | `True` | Send `WorkflowCompleted` event |
 | `send_llm_start_event` | `bool` | `True` | Send `LLMStarted` event (enables prompt guardrails) |
 | `send_llm_end_event` | `bool` | `True` | Send `LLMCompleted` event |
+| `enable_telemetry` | `bool` | `True` | Enable hook governance (HTTP, DB, file I/O) |
+| `sqlalchemy_engine` | `Engine` | `None` | SQLAlchemy Engine instance to instrument (if created before handler) |
+| `resolve_subagent_name` | `Callable` | `None` | Hook for framework-specific subagent name detection |
 
 ---
 
@@ -198,7 +231,7 @@ Policies are written in [Rego](https://www.openpolicyagent.org/docs/latest/polic
 | `input.workflow_type` | `string` | Your `agent_name` |
 | `input.workflow_id` | `string` | Session workflow ID |
 | `input.trust_tier` | `int` | Agent trust tier (1–4) from dashboard |
-| `input.hook_trigger` | `bool` | `true` when event is a hook-level re-evaluation (see [below](#the-hook_trigger-guard)) |
+| `input.hook_trigger` | `bool` | `true` when event is a hook-level re-evaluation |
 
 **Example — block a restricted search term:**
 
@@ -227,7 +260,7 @@ result := {"decision": "BLOCK", "reason": "Restricted topic."} if {
 **Example — require approval for sensitive exports:**
 
 ```rego
-result := {"decision": "REQUIRE_APPROVAL", "reason": "Data export requires compliance sign-off."} if {
+result := {"decision": "REQUIRE_APPROVAL", "reason": "Data export requires sign-off."} if {
     input.event_type == "ActivityStarted"
     input.activity_type == "export_data"
     not input.hook_trigger
@@ -245,9 +278,9 @@ result := {"decision": "REQUIRE_APPROVAL", "reason": "Data export requires compl
 
 #### The `hook_trigger` guard
 
-The SDK's HTTP telemetry layer intercepts outgoing HTTP requests made by your tools and sends a second `ActivityStarted` event for the underlying network call. This event has `hook_trigger: true`.
+The SDK's hook layer intercepts outgoing HTTP requests, DB queries, and file operations made by your tools and sends additional governance events with `hook_trigger: true`.
 
-**Always add `not input.hook_trigger`** to `BLOCK` and `REQUIRE_APPROVAL` rules to prevent them from double-firing on the HTTP-level re-evaluation.
+**Always add `not input.hook_trigger`** to `BLOCK` and `REQUIRE_APPROVAL` rules to prevent them from double-firing on hook-level re-evaluations.
 
 ---
 
@@ -255,15 +288,13 @@ The SDK's HTTP telemetry layer intercepts outgoing HTTP requests made by your to
 
 Guardrails screen the content of LLM prompts and tool outputs. Configure them in the dashboard per agent.
 
-Supported guardrail types:
-
-| Type | ID | What it detects |
-|---|---|---|
-| PII detection | `1` | Names, emails, phone numbers, SSNs, credit cards |
-| Content filter | `2` | Harmful or unsafe content categories |
-| Toxicity | `3` | Toxic language |
-| Ban words | `4` | Custom word/phrase blocklist |
-| Regex | `5` | Custom regex patterns |
+| Type | What it detects |
+|---|---|
+| PII detection | Names, emails, phone numbers, SSNs, credit cards |
+| Content filter | Harmful or unsafe content categories |
+| Toxicity | Toxic language |
+| Ban words | Custom word/phrase blocklist |
+| Regex | Custom regex patterns |
 
 When a guardrail fires on an LLM prompt:
 - **PII redaction** — the prompt is automatically redacted before the LLM sees it
@@ -273,31 +304,27 @@ When a guardrail fires on an LLM prompt:
 
 ### Human-in-the-loop (HITL)
 
-When a policy returns `REQUIRE_APPROVAL`, the agent pauses and polls OpenBox for a human decision. Enable HITL in the handler:
+When a policy returns `REQUIRE_APPROVAL`, the agent pauses and polls OpenBox for a human decision:
 
 ```python
-governed = await create_openbox_graph_handler(
+governed = create_openbox_graph_handler(
     graph=agent,
     api_url=os.environ["OPENBOX_URL"],
     api_key=os.environ["OPENBOX_API_KEY"],
     agent_name="MyAgent",
     hitl={
         "enabled": True,
-        "poll_interval_ms": 5_000,   # check every 5 seconds
-        "max_wait_ms": 300_000,      # timeout after 5 minutes
+        "poll_interval_ms": 5_000,
     },
 )
 ```
 
 The human approves or rejects from the OpenBox dashboard. The SDK resumes or raises `ApprovalRejectedError` accordingly.
 
-**HITL config options:**
-
 | Key | Type | Default | Description |
 |---|---|---|---|
 | `enabled` | `bool` | `False` | Enable HITL polling |
 | `poll_interval_ms` | `int` | `5000` | How often to poll for a decision |
-| `max_wait_ms` | `int` | `300000` | Total timeout before `ApprovalTimeoutError` |
 | `skip_tool_types` | `set[str]` | `set()` | Tools that never wait for HITL |
 
 ---
@@ -311,18 +338,16 @@ Example use cases:
 - Detect unusual tool call sequences (e.g. data exfiltration patterns)
 - Enforce rate limits per tool type
 
-The SDK automatically attaches HTTP span telemetry (via `httpx` hooks) so that `http_get` / `http_post` spans are captured and sent with `ActivityCompleted` events.
+The SDK automatically attaches HTTP span telemetry so that outbound HTTP calls are captured and sent with `ActivityCompleted` events.
 
 ---
 
 ### Tool classification
 
-The SDK can classify tools into semantic types, which enriches the execution tree in the dashboard and enables type-based policy matching via the `__openbox` metadata mechanism (described below).
-
-Configure `tool_type_map` when creating the handler:
+Classify tools into semantic types for richer execution trees and type-based policy matching:
 
 ```python
-governed = await create_openbox_graph_handler(
+governed = create_openbox_graph_handler(
     graph=agent,
     api_url=os.environ["OPENBOX_URL"],
     api_key=os.environ["OPENBOX_API_KEY"],
@@ -336,23 +361,12 @@ governed = await create_openbox_graph_handler(
 )
 ```
 
-**Supported `tool_type` values:** `"http"`, `"database"`, `"builtin"`, `"a2a"`
-
-#### Matching on tool type in Rego
+**Supported values:** `"http"`, `"database"`, `"builtin"`, `"a2a"`, `"custom"`
 
-When a tool type is resolved, the SDK appends an `__openbox` metadata sentinel to `activity_input`. This lets Rego policies classify tools without requiring any changes to OpenBox Core:
-
-```json
-"activity_input": [
-  {"query": "latest AI papers"},
-  {"__openbox": {"tool_type": "http"}}
-]
-```
-
-Rego can then match on it:
+The SDK appends `__openbox` metadata to `activity_input` so Rego can match on tool type:
 
 ```rego
-result := {"decision": "REQUIRE_APPROVAL", "reason": "HTTP calls require approval."} if {
+result := {"decision": "REQUIRE_APPROVAL", "reason": "HTTP tools need approval."} if {
     input.event_type == "ActivityStarted"
     not input.hook_trigger
     some item in input.activity_input
@@ -360,14 +374,92 @@ result := {"decision": "REQUIRE_APPROVAL", "reason": "HTTP calls require approva
 }
 ```
 
-> **Tip:** `activity_type` (the tool name) is always the most reliable field to match on for specific tools. Use `__openbox.tool_type` when you want to write rules that apply to an entire category of tools.
+---
+
+## Hook governance
+
+The SDK uses built-in instrumentation to intercept low-level operations made by your tools. This runs automatically when `enable_telemetry=True` (the default).
+
+### HTTP hooks
+
+Intercepts outbound HTTP requests via `httpx`, `requests`, `urllib3`, and `urllib`. Each request is evaluated at two stages:
+
+- **started** — before the request is sent (can block)
+- **completed** — after the response is received (informational, captures status code and body)
+
+Governance payloads include `http_method`, `http_url`, `request_body`, `response_body`, `http_status_code`, and `request_headers`/`response_headers`.
+
+The SDK automatically ignores requests to the OpenBox Core API itself to prevent recursion.
+
+### Database hooks
+
+Intercepts database queries for all supported libraries:
+
+| Library | Protocol |
+|---|---|
+| `psycopg2` | PostgreSQL |
+| `asyncpg` | PostgreSQL (async) |
+| `mysql-connector-python` | MySQL |
+| `pymysql` | MySQL |
+| `sqlite3` | SQLite |
+| `pymongo` | MongoDB |
+| `redis` | Redis |
+| `sqlalchemy` | ORM (any backend) |
+
+Governance payloads include `db_system`, `db_name`, `db_operation`, `db_statement`, and `server_address`/`server_port`.
+
+If your SQLAlchemy engine is created before the handler, pass it explicitly:
+
+```python
+from sqlalchemy import create_engine
+
+engine = create_engine("postgresql://...")
+
+governed = create_openbox_graph_handler(
+    graph=agent,
+    api_url=os.environ["OPENBOX_URL"],
+    api_key=os.environ["OPENBOX_API_KEY"],
+    agent_name="MyAgent",
+    sqlalchemy_engine=engine,
+)
+```
+
+### File I/O hooks
+
+Intercepts `builtins.open()` and `os.fdopen()` to track file operations. Governance payloads include `file_path`, `file_mode`, `file_operation`, and byte counts.
+
+System paths (`/dev/`, `/proc/`, `/sys/`, `__pycache__`, `.pyc`, `.so`) are automatically skipped.
+
+### Custom function tracing
+
+Use the `@traced` decorator to capture internal function calls as traced spans with governance evaluation:
+
+```python
+from openbox_langgraph import traced
+
+@traced
+def process_data(input_data):
+    return transform(input_data)
+
+@traced(name="custom-span-name", capture_args=True, capture_result=True)
+async def fetch_data(url):
+    return await http_get(url)
+```
+
+For manual span creation:
+
+```python
+from openbox_langgraph import create_span
+
+with create_span("my-operation", {"input": data}) as span:
+    result = do_something()
+    span.set_attribute("output", result)
+```
 
 ---
 
 ## Error handling
 
-The SDK raises typed exceptions that you can catch:
-
 ```python
 from openbox_langgraph import (
     GovernanceBlockedError,
@@ -394,10 +486,10 @@ except ApprovalTimeoutError as e:
 | Exception | When raised |
 |---|---|
 | `GovernanceBlockedError` | Policy returned `BLOCK` |
-| `GovernanceHaltError` | Policy returned `HALT`, or HITL was rejected/expired |
+| `GovernanceHaltError` | Policy returned `HALT` |
 | `GuardrailsValidationError` | Guardrail fired on an LLM prompt or tool output |
 | `ApprovalRejectedError` | Human rejected a `REQUIRE_APPROVAL` decision |
-| `ApprovalTimeoutError` | HITL polling exceeded `max_wait_ms` |
+| `ApprovalTimeoutError` | HITL polling exceeded timeout (server-controlled) |
 
 ---
 
@@ -405,7 +497,7 @@ except ApprovalTimeoutError as e:
 
 ### Streaming
 
-`astream_governed` mirrors LangGraph's `astream` and yields the original event stream while governance runs in the background:
+`astream_governed` yields the original event stream while governance runs in the background:
 
 ```python
 async for event in governed.astream_governed(
@@ -413,48 +505,47 @@ async for event in governed.astream_governed(
     config={"configurable": {"thread_id": "session-001"}},
     stream_mode="values",
 ):
-    # process streamed events
     pass
 ```
 
 ### Multi-turn sessions
 
-Pass a consistent `thread_id` in `configurable` across turns to maintain conversation state:
+Pass a consistent `thread_id` across turns:
 
 ```python
 config = {"configurable": {"thread_id": "user-42-session-7"}}
 
-# Turn 1
 await governed.ainvoke({"messages": [{"role": "user", "content": "Hello"}]}, config=config)
-
-# Turn 2 — same session, governance sees the full history
-await governed.ainvoke({"messages": [{"role": "user", "content": "Now export the data"}]}, config=config)
+await governed.ainvoke({"messages": [{"role": "user", "content": "Export the data"}]}, config=config)
 ```
 
-### Skipping internal chains
+### Subagent detection
 
-LangGraph emits `on_chain_start` for many internal nodes (prompt templates, runnables, etc.). Skip nodes that don't need governance to reduce noise:
+For multi-agent systems, provide a `resolve_subagent_name` hook to identify subagent tool calls:
 
 ```python
-governed = await create_openbox_graph_handler(
+def detect_subagent(event):
+    if event.name == "delegate_to_researcher":
+        return "researcher"
+    return None
+
+governed = create_openbox_graph_handler(
     graph=agent,
-    ...
-    skip_chain_types={
-        "agent",
-        "call_model",
-        "RunnableSequence",
-        "Prompt",
-        "ChatPromptTemplate",
-    },
+    api_url=os.environ["OPENBOX_URL"],
+    api_key=os.environ["OPENBOX_API_KEY"],
+    agent_name="MyAgent",
+    resolve_subagent_name=detect_subagent,
 )
 ```
 
+When a subagent is detected, the SDK tags the governance event with `subagent_name` for execution tree tracking in the dashboard.
+
 ### `fail_closed` mode
 
-For high-sensitivity production agents, use `on_api_error="fail_closed"` to block all tool calls if OpenBox Core is unreachable:
+For high-sensitivity agents, block all tool calls if OpenBox Core is unreachable:
 
 ```python
-governed = await create_openbox_graph_handler(
+governed = create_openbox_graph_handler(
     graph=agent,
     on_api_error="fail_closed",
     ...
@@ -471,7 +562,7 @@ Set `OPENBOX_DEBUG=1` to log all governance requests and responses:
 OPENBOX_DEBUG=1 python agent.py
 ```
 
-Each governance exchange is printed to stdout:
+Output:
 
 ```
 [OpenBox Debug] governance request: { "event_type": "ActivityStarted", "activity_type": "search_web", ... }
@@ -482,11 +573,16 @@ Each governance exchange is printed to stdout:
 
 ## Contributing
 
-Contributions are welcome! Please open an issue before submitting a large pull request.
-
 ```bash
-git clone https://github.com/openbox-ai/openbox-langchain-sdk
-cd sdk-langgraph-python
-pip install -e ".[dev]"
-pytest
+git clone https://github.com/OpenBox-AI/openbox-langgraph-sdk-python
+cd openbox-langgraph-sdk-python
+uv sync --all-extras
+uv run pytest
+uv run ruff check openbox_langgraph/
 ```
+
+---
+
+## License
+
+MIT

{openbox_langgraph_sdk_python-0.1.0.dist-info → openbox_langgraph_sdk_python-0.1.2.dist-info}/RECORD

@@ -1,18 +1,18 @@
 openbox_langgraph/__init__.py,sha256=_hLVtJi-ERJ_GQJImJOMsSzu8RKse52kA-Lsk-hskgs,3581
 openbox_langgraph/client.py,sha256=YpTvZEruBuhYPHbOlt9Hq1YsB_b3Ak9cwuTXYdVr2_M,13356
-openbox_langgraph/config.py,sha256=p3PqUneLTWVy-3zsApNDPVcvG66itiVELu_yA_3hBBU,11477
+openbox_langgraph/config.py,sha256=xWMqcntzY6yveP2roqsC2gdkc66n9F8c903ATt415f4,11643
 openbox_langgraph/db_governance_hooks.py,sha256=9Cj3Afsr3WUl1HYqOC8Q1P8OWMOR0lSOZhO5OxrpOl8,40120
 openbox_langgraph/errors.py,sha256=ZEE6gUBf6KSEUqwOU887ocMoJuqX9Jt3U12u93BevQk,3712
-openbox_langgraph/file_governance_hooks.py,sha256=rbHkpIZ_WJyy4Ww0SJI7tl9NcK9PCpo0WoQtCX103GA,15837
+openbox_langgraph/file_governance_hooks.py,sha256=ddPZEF8yu8iq48rfU3OhI867P6G_I9Kt_ajfPo_6izc,16100
 openbox_langgraph/hitl.py,sha256=p8Xyxp9vvIBciumghM2RGJ53deIIwbufLRmw-PPLteU,2751
 openbox_langgraph/hook_governance.py,sha256=ZDAcyjTBQnFkwG6fv6XOAwiMtwXRQAQCTgTWiD6np40,13946
-openbox_langgraph/http_governance_hooks.py,sha256=2wC9qaGuABNnM31_jX2fUuvoKnVd9IRc4YkdQvLTrx0,27202
+openbox_langgraph/http_governance_hooks.py,sha256=DbY1p_ZipUxJqR6jrc9FjLVA4RkYRVx6p-Nrlf0hzt8,28170
 openbox_langgraph/langgraph_handler.py,sha256=BD61U9F2ESLzSTDJ-wXLS5tNFjvoaeSLHqoj2ABYfQQ,72177
 openbox_langgraph/otel_setup.py,sha256=ti9hQ8pWVj8gQk8E4WMw9gDPqGUlGSzoJLoav38EJno,17305
 openbox_langgraph/span_processor.py,sha256=tY3OXXIq9b47vjmA1oZy2Uu7N1Y5gSaxBOI1RgZK09Q,13289
 openbox_langgraph/tracing.py,sha256=818uke3pRRRFLuO5Ca-Tj3p-LA2QCVjRiI41gQcs5yU,12590
-openbox_langgraph/types.py,sha256=mJEBbxQ6S1a7dQ85sfDDyrdJzkaspa_BmJT_OvJVo6k,18508
+openbox_langgraph/types.py,sha256=EUozIU3pCimjXItwKLaZ-NLLpHGAD06SgBRxgK1rHHg,18591
 openbox_langgraph/verdict_handler.py,sha256=YmZjBxzOa2RBbkF13xDCPUAGzz7m1hwdMErwOVDl2WM,8323
-openbox_langgraph_sdk_python-0.1.0.dist-info/METADATA,sha256=MepDaeXz5p0yCHz9mOZuk4oVI2xCRBvzq50HeySdoNQ,17553
-openbox_langgraph_sdk_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-openbox_langgraph_sdk_python-0.1.0.dist-info/RECORD,,
+openbox_langgraph_sdk_python-0.1.2.dist-info/METADATA,sha256=V3opgqntXab1KFXSYKwjc-0uEUpq4uDNcVYXzMkzeD4,20963
+openbox_langgraph_sdk_python-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+openbox_langgraph_sdk_python-0.1.2.dist-info/RECORD,,