openbox-langgraph-sdk-python 0.2.0__tar.gz → 1.0.0__tar.gz

{openbox_langgraph_sdk_python-0.2.0 → openbox_langgraph_sdk_python-1.0.0}/.gitignore

@@ -7,4 +7,7 @@ build/
 .idea/
 .DS_Store
 repomix-output.xml
-.vscode/
+.vscode/
+_notes/
+plans/
+.claude/

openbox_langgraph_sdk_python-1.0.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 0.3.0
+
+Migrates the SDK onto the shared `openbox-sdk-python` (`openbox_core`) governance
+core. The public API (classes, functions, `initialize()` signature, DID signing)
+is preserved; the changes below are internal rewiring plus a small, deliberate
+set of wire and semantic changes, each regression-gated by a reproducible
+golden-payload oracle.
+
+### Changed — wire protocol (lifecycle events)
+
+- Lifecycle events (`SignalReceived`, `WorkflowStarted`/`Completed`,
+  `LLMStarted`/`Completed`, `ToolStarted`/`Completed`) now serialize through the
+  shared `openbox_core` `EventEnvelope` + strict gate instead of hand-built
+  request bodies. The wire body is byte-identical to before **except** three
+  compatibility-noise fields the base envelope omits by construction and no
+  longer sends for lifecycle events: `hook_trigger: false`, `spans: []`,
+  `span_count: 0`. Core treats an absent `hook_trigger` as `false`; this is the
+  same envelope format the Temporal SDK already ships to Core.
+- Lifecycle-event requests now carry the base SDK's `User-Agent`; hook-triggered
+  requests keep `OpenBox-LangGraph-SDK/<version>`.
+
+### Changed — semantics
+
+- **Approval parsing is action-first and strict.** When both are present the
+  `action` field now wins over `verdict` (was verdict-first). An unknown or
+  empty approval response resolves to *pending* (keeps polling) — never an
+  implicit approve. The previous lenient "unknown → allow" fallback at the
+  human-approval boundary is removed.
+- **Hook-level HITL approval retry now runs governed.** After an approval is
+  granted, the pending abort state is cleared on both the base and legacy stores
+  before the graph re-invokes. Previously the stale abort flag re-blocked the
+  approved retry (`clear_activity_abort` had no caller) — a genuine bug, now
+  fixed.
+- **Fail-open is precise.** A governance transport/parse failure surfaces as
+  "no verdict" (fail-open, unchanged) only for a genuine client-synthesized
+  fallback; a real blocking verdict that happens to carry `fallback_used: true`
+  still enforces.
+- Expired-approval-before-allow ordering is unchanged (an expired approval
+  raises even when allow-shaped).
+
+### Added
+
+- **`use_core_instrumentation`** config flag (default `False`). When enabled,
+  covered hook families (`http`, `dbapi`, `asyncpg`, `sqlalchemy`, `file`) are
+  governed through the shared `openbox_core` hook runtime while uncovered
+  families (`urllib`, `urllib3`, `redis`, `mongo`) stay on the legacy hooks —
+  each operation governed exactly once. Approval on this path is raise-only and
+  never blocks the event loop. Per-family flips (making the core runtime the
+  default for a family) remain follow-up work.
+- `openbox_langgraph.__version__`.
+- `multi_agent_session_id` config/handler option (distinct from `session_id`).
+- Dependency on `openbox-sdk-python` (the shared governance core).
+
+### Preserved (regression-gated)
+
+DID request signing (byte-identical `X-OpenBox-Agent-*` headers), the
+`(activity_id, event_type)` de-dup, transient-failure PII redaction, the
+public `client=` injection seam, and every public class/function signature.

{openbox_langgraph_sdk_python-0.2.0 → openbox_langgraph_sdk_python-1.0.0}/CLAUDE.md

@@ -37,8 +37,10 @@ cd test-agent && uv run python agent.py
 
 The SDK has three governance layers that intercept operations at different levels:
 
-### Layer 1: LangGraph Event Stream (langgraph_handler.py)
-`OpenBoxLangGraphHandler` wraps a compiled LangGraph graph. It processes the v2 event stream (`on_chain_start/end`, `on_tool_start/end`, `on_chat_model_start/end`), sends governance events to OpenBox Core via `GovernanceClient`, and enforces verdicts. This is the main entry point — users call `create_openbox_graph_handler()` (sync function, returns handler immediately) to wrap their graph.
+### Layer 1: Tool/LLM Lifecycle (Producer-Owned via LangChain-Core Callback)
+Tool and LLM lifecycle emission is **owned by the callback layer** (`openbox-langchain-sdk-python`). The `OpenBoxLangChainCoreAsyncCallbackHandler` / `...SyncCallbackHandler` emit lifecycle events (ActivityStarted, ActivityCompleted, LLMStarted, LLMCompleted) directly to OpenBox Core via the `ActivityBridge` ownership channel. This fixes span ordering/correlation bugs: tool hook spans now nest inside the tool's ActivityStarted activity; LLM provider hook spans map into the LLM activity; completions reuse the start activity_id (no more `-c` suffix).
+
+The LangGraph stream-event layer serves as a **fallback for telemetry and span reconstruction** when the callback is not installed (e.g., injected clients or subagent-gated handlers). Completions use stream events for telemetry only — `gate.aevaluate()` polls and continues, never retries the graph. **Sync agents fail-shut on REQUIRE_APPROVAL** (no working sync approval poller).
 
 ### Layer 2: Hook Governance (http/db/file_governance_hooks.py)
 Intercepts low-level operations using built-in instrumentation:

{openbox_langgraph_sdk_python-0.2.0 → openbox_langgraph_sdk_python-1.0.0}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: openbox-langgraph-sdk-python
-Version: 0.2.0
+Version: 1.0.0
 Summary: OpenBox governance and observability SDK for LangGraph
 License: MIT
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: cryptography>=42.0.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: langchain-core>=1.3.3
 Requires-Dist: langgraph>=0.2.0
+Requires-Dist: langsmith>=0.8.18
+Requires-Dist: openbox-langchain-sdk-python>=1.0.0
+Requires-Dist: openbox-sdk-python>=1.0.1
 Requires-Dist: opentelemetry-api>=1.20.0
 Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.41b0
 Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0
@@ -84,10 +86,11 @@ Your code                 SDK (3 layers)                              OpenBox Co
 
 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
+  ├─ Layer 1: Tool/LLM Lifecycle (openbox-langchain-sdk-python)
+  │    Tool lifecycle via LangChain-Core callback  ────────────────→  Policy engine
+  │    LLM lifecycle via LangChain-Core callback   ───────────────→  Guardrails
+  │    ActivityBridge deduplicates callback events
+  │    Stream events serve as fallback (when callback not installed)
   │         ↑ enforce verdict (allow / block / redact / pause)
   │
   ├─ Layer 2: Hook Governance (http/db/file hooks)
@@ -101,7 +104,7 @@ governed.ainvoke()
        Links hook-level operations to the tool call that triggered them
 ```
 
-**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 1** tool and LLM lifecycle is **producer-owned** via the LangChain-Core callback (owned by `openbox-langchain-sdk-python`). It sends governance events (ActivityStarted, LLMStarted, etc.) to OpenBox Core and enforces verdicts. The LangGraph event stream serves as a fallback when the callback is not installed (e.g., injected clients or subagent-gated handlers); completions use stream events for telemetry only via `gate.aevaluate` (poll-and-continue, never retry-the-graph).
 
 **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).
 

{openbox_langgraph_sdk_python-0.2.0 → openbox_langgraph_sdk_python-1.0.0}/README.md

@@ -44,10 +44,11 @@ Your code                 SDK (3 layers)                              OpenBox Co
 
 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
+  ├─ Layer 1: Tool/LLM Lifecycle (openbox-langchain-sdk-python)
+  │    Tool lifecycle via LangChain-Core callback  ────────────────→  Policy engine
+  │    LLM lifecycle via LangChain-Core callback   ───────────────→  Guardrails
+  │    ActivityBridge deduplicates callback events
+  │    Stream events serve as fallback (when callback not installed)
   │         ↑ enforce verdict (allow / block / redact / pause)
   │
   ├─ Layer 2: Hook Governance (http/db/file hooks)
@@ -61,7 +62,7 @@ governed.ainvoke()
        Links hook-level operations to the tool call that triggered them
 ```
 
-**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 1** tool and LLM lifecycle is **producer-owned** via the LangChain-Core callback (owned by `openbox-langchain-sdk-python`). It sends governance events (ActivityStarted, LLMStarted, etc.) to OpenBox Core and enforces verdicts. The LangGraph event stream serves as a fallback when the callback is not installed (e.g., injected clients or subagent-gated handlers); completions use stream events for telemetry only via `gate.aevaluate` (poll-and-continue, never retry-the-graph).
 
 **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).