openbox-langchain-sdk-python 0.1.0__tar.gz

openbox_langchain_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_langchain/
+
+      - 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_langchain_sdk_python-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+*.so
+.DS_Store
+CLAUDE.md
+plans/

openbox_langchain_sdk_python-0.1.0/AGENTS.md

@@ -0,0 +1,112 @@
+# AGENTS.md — OpenBox LangChain SDK
+
+## Project Overview
+
+OpenBox governance SDK for LangChain agents. Intercepts agent execution via `AgentMiddleware` and enforces OpenBox policies, guardrails, HITL approvals, and behavior rules.
+
+## Architecture
+
+Three-layer governance:
+
+- **Layer 1:** `OpenBoxLangChainMiddleware` (AgentMiddleware subclass) — Intercepts agent lifecycle (before/after agent, wrap model/tool calls)
+- **Layer 2:** Hook governance (HTTP/DB/File I/O) — Imported from `openbox-langgraph-sdk-python`
+- **Layer 3:** Activity context mapping via `WorkflowSpanProcessor` — Imported from `openbox-langgraph-sdk-python`
+
+**Key principle:** Only the middleware integration layer is new code. All governance infrastructure is imported from `openbox-langgraph-sdk-python` (not copied).
+
+## Package Structure
+
+```
+openbox_langchain/
+├── __init__.py                     # Public API (re-exports + exports middleware)
+├── middleware.py                   # OpenBoxLangChainMiddleware + options
+├── middleware_factory.py           # create_openbox_langchain_middleware() factory
+├── middleware_hooks.py             # Event builders, PII redaction, OTel helpers
+├── middleware_hook_handlers.py     # before_agent, after_agent, wrap_model_call handlers
+└── middleware_tool_hook.py         # wrap_tool_call handler
+```
+
+**Code count:** 1,025 total lines (all new), focused on middleware integration only.
+
+## Key Classes
+
+- `OpenBoxLangChainMiddleware` — Main middleware (AgentMiddleware subclass)
+- `OpenBoxLangChainMiddlewareOptions` — Configuration dataclass
+
+## Key Functions
+
+- `create_openbox_langchain_middleware()` — Factory (primary entry point)
+- `handle_before_agent()` / `ahandle_before_agent()` — Session setup, pre-screen
+- `handle_after_agent()` / `ahandle_after_agent()` — Cleanup
+- `handle_wrap_model_call()` / `ahandle_wrap_model_call()` — LLM interception, PII redaction
+- `handle_wrap_tool_call()` / `ahandle_wrap_tool_call()` — Tool governance, OTel spans
+
+## Quick Start
+
+```python
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+from openbox_langchain import create_openbox_langchain_middleware
+
+# Create middleware
+middleware = create_openbox_langchain_middleware(
+    api_url="https://core.openbox.ai",
+    api_key="obx_live_...",
+    agent_name="MyAgent",
+)
+
+# Create agent with middleware
+model = ChatOpenAI(model="gpt-4")
+tools = [...]
+
+agent = create_react_agent(
+    model=model,
+    tools=tools,
+    middleware=[middleware],
+)
+
+# Invoke — governance applied automatically
+result = agent.invoke({"messages": [("user", "your query")]})
+```
+
+## Commands
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Test
+pytest tests/ -v
+
+# Lint
+ruff check openbox_langchain/
+
+# Type check
+mypy openbox_langchain/
+```
+
+## Testing
+
+**Current:** 99 tests, 100% pass rate
+
+**Coverage:**
+- Unit tests for each hook handler
+- Integration tests for full agent workflow
+- Mock client tests for verdict enforcement
+- Pre-screen caching, OTel context, async/sync bridge
+- Error handling (network, timeout, invalid verdicts)
+
+## Documentation
+
+- **README.md** — Quick start + configuration
+- **docs/project-overview-pdr.md** — Functional/non-functional requirements
+- **docs/system-architecture.md** — 3-layer design, data flow, verdict system
+- **docs/code-standards.md** — Patterns, conventions, guidelines
+- **docs/codebase-summary.md** — Module organization, dependencies
+- **docs/project-roadmap.md** — Timeline, milestones, future work
+
+## References
+
+- **DeepAgent SDK:** `/Users/tino/code/openbox-deepagent-sdk-python/` (reference middleware pattern)
+- **LangGraph SDK:** `/Users/tino/code/openbox-langgraph-sdk-python/` (governance infrastructure)
+- **SDK Guide:** `/Users/tino/code/sdk-implementation-guide/README.md`

openbox_langchain_sdk_python-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: openbox-langchain-sdk-python
+Version: 0.1.0
+Summary: OpenBox governance and observability SDK for LangChain
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: langchain>=0.3.0
+Requires-Dist: langgraph>=0.2.0
+Requires-Dist: openbox-langgraph-sdk-python>=0.1.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'
+Description-Content-Type: text/markdown
+
+# OpenBox LangChain SDK — Python
+
+Governance and observability SDK for LangChain agents. Intercepts agent execution via `AgentMiddleware` to enforce OpenBox policies, guardrails, HITL approval flows, and hook-level governance (HTTP/DB/File I/O).
+
+## Installation
+
+```bash
+pip install openbox-langchain-sdk-python
+```
+
+## Quick Start
+
+```python
+from langchain.agents import create_agent
+from openbox_langchain import create_openbox_langchain_middleware
+
+# 1. Create middleware
+middleware = create_openbox_langchain_middleware(
+    api_url="https://core.openbox.ai",
+    api_key="obx_live_...",
+    agent_name="MyAgent",
+)
+
+# 2. Create agent with middleware
+agent = create_agent(
+    model="openai:gpt-4o",
+    tools=[...],
+    middleware=[middleware],
+)
+
+# 3. Invoke — governance applied automatically
+result = agent.invoke({"messages": [("user", "your query")]})
+```
+
+## How It Works
+
+Three-layer governance architecture:
+
+| Layer | Mechanism | Governs |
+|-------|-----------|---------|
+| 1 | AgentMiddleware hooks | Agent lifecycle (before/after), model calls, tool execution |
+| 2 | Hook Governance | HTTP requests, DB queries, file I/O at kernel boundary |
+| 3 | Activity Context Mapping | Links hook traces to governance activities via OTel |
+
+**Middleware hooks:**
+- `before_agent` / `abefore_agent` — Session setup, pre-screen guardrails
+- `wrap_model_call` / `awrap_model_call` — LLM interception, PII redaction
+- `wrap_tool_call` / `awrap_tool_call` — Tool governance, OTel span registration
+- `after_agent` / `aafter_agent` — Session cleanup
+
+## Configuration
+
+```python
+middleware = create_openbox_langchain_middleware(
+    api_url="https://core.openbox.ai",  # OpenBox Core URL
+    api_key="obx_live_...",              # API key (obx_live_* or obx_test_*)
+    agent_name="MyAgent",                # Agent name (from dashboard)
+    governance_timeout=30.0,             # HTTP timeout in seconds
+    validate=True,                       # Validate API key on startup
+    session_id="session-123",            # Optional session tracking
+    sqlalchemy_engine=engine,            # Optional DB governance
+    tool_type_map={                      # Optional tool classification
+        "search_web": "http",
+        "query_db": "database",
+    },
+)
+```
+
+## Supported Agent Types
+
+- `create_agent(model, tools, middleware=[...])` — recommended
+- Any LangChain agent builder that accepts `middleware`
+
+## Verdict Enforcement
+
+5-tier verdict system:
+- **ALLOW** — Request permitted
+- **CONSTRAIN** — Request constrained (e.g., rate limit)
+- **REQUIRE_APPROVAL** — Human approval required (HITL polling)
+- **BLOCK** — Request blocked with error
+- **HALT** — Entire workflow halted (unrecoverable error)
+
+## Requirements
+
+- Python 3.11+
+- LangChain >= 0.3.0
+- LangGraph >= 0.2.0
+- openbox-langgraph-sdk-python >= 0.1.0
+
+## API Reference
+
+**Primary factory:**
+- `create_openbox_langchain_middleware()` — Creates configured middleware
+
+**Re-exported from langgraph SDK:**
+- `enforce_verdict()` — Enforce verdicts
+- `poll_until_decision()` — HITL approval polling
+- `GovernanceClient`, `GovernanceConfig` — Core types
+
+See `openbox_langchain.__init__.py` for full API export list.
+
+## License
+
+MIT

openbox_langchain_sdk_python-0.1.0/README.md

@@ -0,0 +1,104 @@
+# OpenBox LangChain SDK — Python
+
+Governance and observability SDK for LangChain agents. Intercepts agent execution via `AgentMiddleware` to enforce OpenBox policies, guardrails, HITL approval flows, and hook-level governance (HTTP/DB/File I/O).
+
+## Installation
+
+```bash
+pip install openbox-langchain-sdk-python
+```
+
+## Quick Start
+
+```python
+from langchain.agents import create_agent
+from openbox_langchain import create_openbox_langchain_middleware
+
+# 1. Create middleware
+middleware = create_openbox_langchain_middleware(
+    api_url="https://core.openbox.ai",
+    api_key="obx_live_...",
+    agent_name="MyAgent",
+)
+
+# 2. Create agent with middleware
+agent = create_agent(
+    model="openai:gpt-4o",
+    tools=[...],
+    middleware=[middleware],
+)
+
+# 3. Invoke — governance applied automatically
+result = agent.invoke({"messages": [("user", "your query")]})
+```
+
+## How It Works
+
+Three-layer governance architecture:
+
+| Layer | Mechanism | Governs |
+|-------|-----------|---------|
+| 1 | AgentMiddleware hooks | Agent lifecycle (before/after), model calls, tool execution |
+| 2 | Hook Governance | HTTP requests, DB queries, file I/O at kernel boundary |
+| 3 | Activity Context Mapping | Links hook traces to governance activities via OTel |
+
+**Middleware hooks:**
+- `before_agent` / `abefore_agent` — Session setup, pre-screen guardrails
+- `wrap_model_call` / `awrap_model_call` — LLM interception, PII redaction
+- `wrap_tool_call` / `awrap_tool_call` — Tool governance, OTel span registration
+- `after_agent` / `aafter_agent` — Session cleanup
+
+## Configuration
+
+```python
+middleware = create_openbox_langchain_middleware(
+    api_url="https://core.openbox.ai",  # OpenBox Core URL
+    api_key="obx_live_...",              # API key (obx_live_* or obx_test_*)
+    agent_name="MyAgent",                # Agent name (from dashboard)
+    governance_timeout=30.0,             # HTTP timeout in seconds
+    validate=True,                       # Validate API key on startup
+    session_id="session-123",            # Optional session tracking
+    sqlalchemy_engine=engine,            # Optional DB governance
+    tool_type_map={                      # Optional tool classification
+        "search_web": "http",
+        "query_db": "database",
+    },
+)
+```
+
+## Supported Agent Types
+
+- `create_agent(model, tools, middleware=[...])` — recommended
+- Any LangChain agent builder that accepts `middleware`
+
+## Verdict Enforcement
+
+5-tier verdict system:
+- **ALLOW** — Request permitted
+- **CONSTRAIN** — Request constrained (e.g., rate limit)
+- **REQUIRE_APPROVAL** — Human approval required (HITL polling)
+- **BLOCK** — Request blocked with error
+- **HALT** — Entire workflow halted (unrecoverable error)
+
+## Requirements
+
+- Python 3.11+
+- LangChain >= 0.3.0
+- LangGraph >= 0.2.0
+- openbox-langgraph-sdk-python >= 0.1.0
+
+## API Reference
+
+**Primary factory:**
+- `create_openbox_langchain_middleware()` — Creates configured middleware
+
+**Re-exported from langgraph SDK:**
+- `enforce_verdict()` — Enforce verdicts
+- `poll_until_decision()` — HITL approval polling
+- `GovernanceClient`, `GovernanceConfig` — Core types
+
+See `openbox_langchain.__init__.py` for full API export list.
+
+## License
+
+MIT