openbox-langchain-sdk-python 0.1.0

OpenBox governance and observability SDK for LangChain

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

pip install openbox-langchain-sdk-python

Quick Start

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

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