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

{openbox_langgraph_sdk_python-0.2.0 → openbox_langgraph_sdk_python-1.1.0}/.github/workflows/pr-quality.yml

@@ -165,7 +165,7 @@ jobs:
         id: sonarqube_quality_gate
         if: ${{ env.SONAR_TOKEN != '' && env.SONAR_HOST_URL != '' }}
         continue-on-error: true
-        uses: SonarSource/sonarqube-quality-gate-action@master
+        uses: SonarSource/sonarqube-quality-gate-action@v1.2.0
         with:
           pollingTimeoutSec: 600
         env:

{openbox_langgraph_sdk_python-0.2.0 → openbox_langgraph_sdk_python-1.1.0}/.github/workflows/publish.yml

@@ -342,7 +342,7 @@ jobs:
         id: sonarqube_quality_gate
         if: ${{ env.SONAR_TOKEN != '' && env.SONAR_HOST_URL != '' }}
         continue-on-error: true
-        uses: SonarSource/sonarqube-quality-gate-action@master
+        uses: SonarSource/sonarqube-quality-gate-action@v1.2.0
         with:
           pollingTimeoutSec: 600
         env:

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

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

openbox_langgraph_sdk_python-1.1.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 1.1.0
+
+- Upgrade `openbox-sdk-python` to `>=1.4.0` for IAM v3 workload identity. Keep
+  `openbox-langchain-sdk-python` at `>=1.0.0` (locked to 1.0.0).
+- Update locked AnyIO to 4.14.2 and urllib3 to 2.8.0 in the SDK and demo, plus
+  pyasn1 to 0.6.4 in the demo, to address Trivy's critical/high findings.
+- Add `workload_private_key` to initialization, graph creation, runtime creation,
+  and standalone governance clients, with framework/global environment support
+  during initialization and runtime creation.
+- Delegate workload bootstrap, token exchange, caching, and refresh to the base
+  SDK. Reuse the handler's runtime client for validation, sync/raw evaluation,
+  and approval polling alongside callbacks and operation hooks.
+- Preserve authentication, signing, and bootstrap/configuration errors under
+  fail-open policies. Export `OpenBoxSigningError` with Core's `reason_code`.
+- Preserve legacy DID/API-key configuration and the base SDK's explicit
+  no-workload-authority fallback for rolling upgrades.
+
+## 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.1.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.1.0}/PKG-INFO

@@ -1,14 +1,16 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openbox-langgraph-sdk-python
-Version: 0.2.0
+Version: 1.1.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.4.0
 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).
 
@@ -133,17 +136,14 @@ uv add openbox-langgraph-sdk-python
 
 ### 1. Get your agent credentials
 
-Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy the agent API key plus its DID credentials.
-
-New OpenBox agents have DID signing enabled by default. Keep the private key secret and load it from your environment.
+Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy its API key. For an IAM v3 workload-enabled agent, also load the PKCS8 PEM RSA private key registered for its active Keycloak service account. Keep the key secret.
 
 ### 2. Set environment variables
 
 ```bash
 export OPENBOX_URL="https://core.openbox.ai"
 export OPENBOX_API_KEY="obx_live_..."
-export OPENBOX_AGENT_DID="did:aip:..."
-export OPENBOX_AGENT_PRIVATE_KEY="..."
+export OPENBOX_WORKLOAD_PRIVATE_KEY="$(cat /path/to/workload-private-key.pem)"
 ```
 
 ### 3. Wrap your graph
@@ -178,6 +178,50 @@ asyncio.run(main())
 
 That's it. Your agent now sends governance events to OpenBox on every tool call, LLM prompt, HTTP request, and database query.
 
+### IAM v3 workload identity
+
+IAM v3 is provided by `openbox-sdk-python>=1.4.0`. The existing
+`openbox-langchain-sdk-python` dependency remains at `>=1.0.0`; its callbacks
+use the same base runtime as the LangGraph handler and operation hooks.
+
+You can pass the workload key explicitly instead of setting an environment variable:
+
+```python
+governed = create_openbox_graph_handler(
+    graph=agent,
+    api_url=os.environ["OPENBOX_URL"],
+    api_key=os.environ["OPENBOX_API_KEY"],
+    workload_private_key=os.environ["OPENBOX_WORKLOAD_PRIVATE_KEY"],
+)
+```
+
+Key resolution is explicit argument, then `OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY`,
+then `OPENBOX_WORKLOAD_PRIVATE_KEY`. The value is the PEM contents, not a file path.
+The Python base SDK selects workload authentication from this key; no
+`OPENBOX_AGENT_IDENTITY_METHOD` setting is needed for IAM v3.
+
+The base SDK fetches `/api/v3/auth/bootstrap`, exchanges a signed `private_key_jwt`
+for a short-lived Keycloak token, and sends the API key plus
+`X-OpenBox-Workload-Token` on v3 validation, evaluation, and approval requests.
+It owns token caching and refresh for OpenBox-, Okta-, and Entra-managed identities.
+Lifecycle callbacks, hooks, synchronous/raw evaluations, and approval polling share
+the handler's runtime client. A standalone `GovernanceClient` also accepts
+`workload_private_key`; call `await client.close()` when finished with it.
+
+Authentication and signing failures raise `OpenBoxAuthError` or its subclass
+`OpenBoxSigningError` even with `on_api_error="fail_open"`. The signing error retains
+Core's `reason_code`. Invalid bootstrap metadata raises `OpenBoxConfigError`, and
+bootstrap/token service outages raise `OpenBoxNetworkError`; these do not become
+implicit ALLOW or pending approval results. `validate=False` skips the startup
+network check only: the key is still validated locally, and runtime requests
+still authenticate.
+
+The base SDK preserves rolling-upgrade compatibility: bootstrap HTTP 404, or
+HTTP 409 with `workload_identity_unavailable`, retains the configured legacy route.
+Other bootstrap failures do not downgrade. Existing DID signing remains available
+through `agent_did`/`agent_private_key` or `OPENBOX_AGENT_DID`/`OPENBOX_AGENT_PRIVATE_KEY`.
+Without identity credentials, the existing API-key-only behavior is preserved.
+
 ### Try it locally (included test agent)
 
 The repository includes a runnable LangGraph test agent under `test-agent/`.
@@ -204,6 +248,7 @@ See `test-agent/README.md` for setup and run instructions.
 | `api_key` | `str` | **required** | API key (`obx_live_*` or `obx_test_*`) |
 | `agent_did` | `str` | `OPENBOX_AGENT_DID` | Agent DID used to sign governance requests |
 | `agent_private_key` | `str` | `OPENBOX_AGENT_PRIVATE_KEY` | Base64 raw Ed25519 private key seed for the agent DID |
+| `workload_private_key` | `str` | `OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY`, then `OPENBOX_WORKLOAD_PRIVATE_KEY` | PKCS8 PEM RSA key for IAM v3 workload authentication |
 | `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) |

{openbox_langgraph_sdk_python-0.2.0 → openbox_langgraph_sdk_python-1.1.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).
 
@@ -93,17 +94,14 @@ uv add openbox-langgraph-sdk-python
 
 ### 1. Get your agent credentials
 
-Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy the agent API key plus its DID credentials.
-
-New OpenBox agents have DID signing enabled by default. Keep the private key secret and load it from your environment.
+Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy its API key. For an IAM v3 workload-enabled agent, also load the PKCS8 PEM RSA private key registered for its active Keycloak service account. Keep the key secret.
 
 ### 2. Set environment variables
 
 ```bash
 export OPENBOX_URL="https://core.openbox.ai"
 export OPENBOX_API_KEY="obx_live_..."
-export OPENBOX_AGENT_DID="did:aip:..."
-export OPENBOX_AGENT_PRIVATE_KEY="..."
+export OPENBOX_WORKLOAD_PRIVATE_KEY="$(cat /path/to/workload-private-key.pem)"
 ```
 
 ### 3. Wrap your graph
@@ -138,6 +136,50 @@ asyncio.run(main())
 
 That's it. Your agent now sends governance events to OpenBox on every tool call, LLM prompt, HTTP request, and database query.
 
+### IAM v3 workload identity
+
+IAM v3 is provided by `openbox-sdk-python>=1.4.0`. The existing
+`openbox-langchain-sdk-python` dependency remains at `>=1.0.0`; its callbacks
+use the same base runtime as the LangGraph handler and operation hooks.
+
+You can pass the workload key explicitly instead of setting an environment variable:
+
+```python
+governed = create_openbox_graph_handler(
+    graph=agent,
+    api_url=os.environ["OPENBOX_URL"],
+    api_key=os.environ["OPENBOX_API_KEY"],
+    workload_private_key=os.environ["OPENBOX_WORKLOAD_PRIVATE_KEY"],
+)
+```
+
+Key resolution is explicit argument, then `OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY`,
+then `OPENBOX_WORKLOAD_PRIVATE_KEY`. The value is the PEM contents, not a file path.
+The Python base SDK selects workload authentication from this key; no
+`OPENBOX_AGENT_IDENTITY_METHOD` setting is needed for IAM v3.
+
+The base SDK fetches `/api/v3/auth/bootstrap`, exchanges a signed `private_key_jwt`
+for a short-lived Keycloak token, and sends the API key plus
+`X-OpenBox-Workload-Token` on v3 validation, evaluation, and approval requests.
+It owns token caching and refresh for OpenBox-, Okta-, and Entra-managed identities.
+Lifecycle callbacks, hooks, synchronous/raw evaluations, and approval polling share
+the handler's runtime client. A standalone `GovernanceClient` also accepts
+`workload_private_key`; call `await client.close()` when finished with it.
+
+Authentication and signing failures raise `OpenBoxAuthError` or its subclass
+`OpenBoxSigningError` even with `on_api_error="fail_open"`. The signing error retains
+Core's `reason_code`. Invalid bootstrap metadata raises `OpenBoxConfigError`, and
+bootstrap/token service outages raise `OpenBoxNetworkError`; these do not become
+implicit ALLOW or pending approval results. `validate=False` skips the startup
+network check only: the key is still validated locally, and runtime requests
+still authenticate.
+
+The base SDK preserves rolling-upgrade compatibility: bootstrap HTTP 404, or
+HTTP 409 with `workload_identity_unavailable`, retains the configured legacy route.
+Other bootstrap failures do not downgrade. Existing DID signing remains available
+through `agent_did`/`agent_private_key` or `OPENBOX_AGENT_DID`/`OPENBOX_AGENT_PRIVATE_KEY`.
+Without identity credentials, the existing API-key-only behavior is preserved.
+
 ### Try it locally (included test agent)
 
 The repository includes a runnable LangGraph test agent under `test-agent/`.
@@ -164,6 +206,7 @@ See `test-agent/README.md` for setup and run instructions.
 | `api_key` | `str` | **required** | API key (`obx_live_*` or `obx_test_*`) |
 | `agent_did` | `str` | `OPENBOX_AGENT_DID` | Agent DID used to sign governance requests |
 | `agent_private_key` | `str` | `OPENBOX_AGENT_PRIVATE_KEY` | Base64 raw Ed25519 private key seed for the agent DID |
+| `workload_private_key` | `str` | `OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY`, then `OPENBOX_WORKLOAD_PRIVATE_KEY` | PKCS8 PEM RSA key for IAM v3 workload authentication |
 | `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) |