openbox-langgraph-sdk-python 0.1.0__tar.gz

openbox_langgraph_sdk_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,71 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["*.*.*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Lint
+        run: uv run ruff check openbox_langgraph/
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          PKG_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "::error::Tag $TAG does not match pyproject.toml version $PKG_VERSION"
+            exit 1
+          fi
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist and wheel
+        run: pip install build && python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true

openbox_langgraph_sdk_python-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+/openbox_langgraph/__pycache__
+/tests/__pycache__

openbox_langgraph_sdk_python-0.1.0/PKG-INFO

@@ -0,0 +1,492 @@
+Metadata-Version: 2.4
+Name: openbox-langgraph-sdk-python
+Version: 0.1.0
+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: langgraph>=0.2.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-mysql>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-pymongo>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-pymysql>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-requests>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-sqlite3>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-urllib3>=0.41b0
+Requires-Dist: opentelemetry-instrumentation-urllib>=0.41b0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20.0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-requests>=0.41b0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-urllib3>=0.41b0; extra == 'otel'
+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
+
+[![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/)
+[![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.
+
+---
+
+## Table of Contents
+
+- [How it works](#how-it-works)
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [Configuration reference](#configuration-reference)
+- [Governance features](#governance-features)
+  - [Policies (OPA / Rego)](#policies-opa--rego)
+  - [Guardrails](#guardrails)
+  - [Human-in-the-loop (HITL)](#human-in-the-loop-hitl)
+  - [Behavior Rules (AGE)](#behavior-rules-age)
+  - [Tool classification](#tool-classification)
+- [Error handling](#error-handling)
+- [Advanced usage](#advanced-usage)
+- [Debugging](#debugging)
+- [Contributing](#contributing)
+
+---
+
+## How it works
+
+```
+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)
+```
+
+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.
+
+**Zero graph changes required.** You keep writing LangGraph exactly as you normally would.
+
+---
+
+## Installation
+
+```bash
+pip install openbox-langgraph-sdk
+```
+
+**Requirements:** Python 3.11+, `langgraph >= 0.2`, `langchain-core >= 0.2`
+
+---
+
+## Quickstart
+
+### 1. Get your API key
+
+Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy your API key (`obx_live_...` or `obx_test_...`).
+
+### 2. Set environment variables
+
+```bash
+export OPENBOX_URL="https://core.openbox.ai"
+export OPENBOX_API_KEY="obx_live_..."
+```
+
+### 3. Wrap your graph
+
+```python
+import os
+import asyncio
+from langgraph.prebuilt import create_react_agent
+from langchain_openai import ChatOpenAI
+from openbox_langgraph import create_openbox_graph_handler
+
+# Your existing agent — no changes needed
+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(
+        graph=agent,
+        api_url=os.environ["OPENBOX_URL"],
+        api_key=os.environ["OPENBOX_API_KEY"],
+        agent_name="MyAgent",  # must match the agent name in your dashboard
+    )
+
+    result = await governed.ainvoke(
+        {"messages": [{"role": "user", "content": "Search for the latest AI papers"}]},
+        config={"configurable": {"thread_id": "session-001"}},
+    )
+    print(result["messages"][-1].content)
+
+asyncio.run(main())
+```
+
+That's it. Your agent now sends governance events to OpenBox on every tool call and LLM prompt.
+
+### Try it locally (included test agent)
+
+This repository includes a runnable LangGraph test agent under `sdk-langgraph-python/test-agent`.
+
+It is designed to validate:
+
+- **Guardrails** on `agent_validatePrompt`
+- **Policies** on tool invocations (BLOCK / REQUIRE_APPROVAL)
+- **HITL** approval polling
+- **Behavior Rules (AGE)** via `httpx` spans from `search_web`
+
+See `test-agent/README.md` for setup and run instructions.
+
+---
+
+## Configuration reference
+
+`create_openbox_graph_handler` accepts the following keyword arguments:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `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) |
+| `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) |
+| `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 |
+
+---
+
+## Governance features
+
+### Policies (OPA / Rego)
+
+Policies are written in [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) and configured in the OpenBox dashboard under your agent. The SDK sends an `ActivityStarted` event before every tool call; your policy decides what happens next.
+
+**Fields available in `input`:**
+
+| Field | Type | Description |
+|---|---|---|
+| `input.event_type` | `string` | `"ActivityStarted"` or `"ActivityCompleted"` |
+| `input.activity_type` | `string` | Tool name (e.g. `"search_web"`) |
+| `input.activity_input` | `array` | Tool arguments as a JSON array |
+| `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)) |
+
+**Example — block a restricted search term:**
+
+```rego
+package org.openboxai.policy
+
+import future.keywords.if
+import future.keywords.in
+
+default result = {"decision": "CONTINUE", "reason": null}
+
+restricted_terms := {"nuclear weapon", "bioweapon", "malware synthesis"}
+
+result := {"decision": "BLOCK", "reason": "Restricted topic."} if {
+    input.event_type == "ActivityStarted"
+    input.activity_type == "search_web"
+    not input.hook_trigger
+    count(input.activity_input) > 0
+    entry := input.activity_input[0]
+    is_object(entry)
+    some term in restricted_terms
+    contains(lower(entry.query), term)
+}
+```
+
+**Example — require approval for sensitive exports:**
+
+```rego
+result := {"decision": "REQUIRE_APPROVAL", "reason": "Data export requires compliance sign-off."} if {
+    input.event_type == "ActivityStarted"
+    input.activity_type == "export_data"
+    not input.hook_trigger
+}
+```
+
+**Possible decisions:**
+
+| Decision | Effect |
+|---|---|
+| `CONTINUE` | Tool executes normally |
+| `BLOCK` | `GovernanceBlockedError` raised — tool does not execute |
+| `REQUIRE_APPROVAL` | Agent pauses; human must approve or reject in dashboard |
+| `HALT` | `GovernanceHaltError` raised — session terminated |
+
+#### 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`.
+
+**Always add `not input.hook_trigger`** to `BLOCK` and `REQUIRE_APPROVAL` rules to prevent them from double-firing on the HTTP-level re-evaluation.
+
+---
+
+### Guardrails
+
+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 |
+
+When a guardrail fires on an LLM prompt:
+- **PII redaction** — the prompt is automatically redacted before the LLM sees it
+- **Content block** — `GuardrailsValidationError` is raised
+
+---
+
+### 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:
+
+```python
+governed = await 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
+    },
+)
+```
+
+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 |
+
+---
+
+### Behavior Rules (AGE)
+
+Behavior Rules detect patterns across sequences of tool calls within a session. They are configured in the dashboard and enforced by the OpenBox Activity Governance Engine (AGE).
+
+Example use cases:
+- Flag if an agent calls an external URL more than N times in one session
+- 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.
+
+---
+
+### 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:
+
+```python
+governed = await create_openbox_graph_handler(
+    graph=agent,
+    api_url=os.environ["OPENBOX_URL"],
+    api_key=os.environ["OPENBOX_API_KEY"],
+    agent_name="MyAgent",
+    tool_type_map={
+        "search_web": "http",
+        "export_data": "http",
+        "query_db":    "database",
+        "write_file":  "builtin",
+    },
+)
+```
+
+**Supported `tool_type` values:** `"http"`, `"database"`, `"builtin"`, `"a2a"`
+
+#### Matching on tool type in Rego
+
+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:
+
+```rego
+result := {"decision": "REQUIRE_APPROVAL", "reason": "HTTP calls require approval."} if {
+    input.event_type == "ActivityStarted"
+    not input.hook_trigger
+    some item in input.activity_input
+    item["__openbox"].tool_type == "http"
+}
+```
+
+> **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.
+
+---
+
+## Error handling
+
+The SDK raises typed exceptions that you can catch:
+
+```python
+from openbox_langgraph import (
+    GovernanceBlockedError,
+    GovernanceHaltError,
+    GuardrailsValidationError,
+    ApprovalRejectedError,
+    ApprovalTimeoutError,
+)
+
+try:
+    result = await governed.ainvoke({"messages": [...]}, config=...)
+except GovernanceBlockedError as e:
+    print(f"Action blocked by policy: {e}")
+except GovernanceHaltError as e:
+    print(f"Session halted: {e}")
+except GuardrailsValidationError as e:
+    print(f"Guardrail triggered: {e}")
+except ApprovalRejectedError as e:
+    print(f"Human rejected the action: {e}")
+except ApprovalTimeoutError as e:
+    print(f"HITL approval timed out: {e}")
+```
+
+| Exception | When raised |
+|---|---|
+| `GovernanceBlockedError` | Policy returned `BLOCK` |
+| `GovernanceHaltError` | Policy returned `HALT`, or HITL was rejected/expired |
+| `GuardrailsValidationError` | Guardrail fired on an LLM prompt or tool output |
+| `ApprovalRejectedError` | Human rejected a `REQUIRE_APPROVAL` decision |
+| `ApprovalTimeoutError` | HITL polling exceeded `max_wait_ms` |
+
+---
+
+## Advanced usage
+
+### Streaming
+
+`astream_governed` mirrors LangGraph's `astream` and yields the original event stream while governance runs in the background:
+
+```python
+async for event in governed.astream_governed(
+    {"messages": [{"role": "user", "content": "..."}]},
+    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:
+
+```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)
+```
+
+### Skipping internal chains
+
+LangGraph emits `on_chain_start` for many internal nodes (prompt templates, runnables, etc.). Skip nodes that don't need governance to reduce noise:
+
+```python
+governed = await create_openbox_graph_handler(
+    graph=agent,
+    ...
+    skip_chain_types={
+        "agent",
+        "call_model",
+        "RunnableSequence",
+        "Prompt",
+        "ChatPromptTemplate",
+    },
+)
+```
+
+### `fail_closed` mode
+
+For high-sensitivity production agents, use `on_api_error="fail_closed"` to block all tool calls if OpenBox Core is unreachable:
+
+```python
+governed = await create_openbox_graph_handler(
+    graph=agent,
+    on_api_error="fail_closed",
+    ...
+)
+```
+
+---
+
+## Debugging
+
+Set `OPENBOX_DEBUG=1` to log all governance requests and responses:
+
+```bash
+OPENBOX_DEBUG=1 python agent.py
+```
+
+Each governance exchange is printed to stdout:
+
+```
+[OpenBox Debug] governance request: { "event_type": "ActivityStarted", "activity_type": "search_web", ... }
+[OpenBox Debug] governance response: { "verdict": "allow", ... }
+```
+
+---
+
+## 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
+```