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
