openbox-langchain-sdk-python 0.1.0__py3-none-any.whl

openbox_langchain/__init__.py

@@ -0,0 +1,124 @@
+"""OpenBox LangChain SDK — governance for LangChain agents via middleware."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+# Re-export the openbox-langgraph-sdk public surface
+from openbox_langgraph import (
+    DEFAULT_HITL_CONFIG,
+    ApprovalExpiredError,
+    ApprovalRejectedError,
+    ApprovalResponse,
+    ApprovalTimeoutError,
+    GovernanceBlockedError,
+    GovernanceClient,
+    GovernanceConfig,
+    GovernanceHaltError,
+    GovernanceVerdictResponse,
+    GuardrailsReason,
+    GuardrailsResult,
+    GuardrailsValidationError,
+    HITLConfig,
+    LangChainGovernanceEvent,
+    OpenBoxAuthError,
+    OpenBoxError,
+    OpenBoxInsecureURLError,
+    OpenBoxNetworkError,
+    Verdict,
+    VerdictContext,
+    WorkflowEventType,
+    WorkflowSpanBuffer,
+    WorkflowSpanProcessor,
+    build_auth_headers,
+    create_span,
+    enforce_verdict,
+    get_global_config,
+    highest_priority_verdict,
+    initialize,
+    is_hitl_applicable,
+    lang_graph_event_to_context,
+    merge_config,
+    parse_approval_response,
+    parse_governance_response,
+    poll_until_decision,
+    rfc3339_now,
+    safe_serialize,
+    setup_opentelemetry_for_governance,
+    to_server_event_type,
+    traced,
+    verdict_from_string,
+    verdict_priority,
+    verdict_requires_approval,
+    verdict_should_stop,
+)
+
+from openbox_langchain.middleware import (
+    OpenBoxLangChainMiddleware,
+    OpenBoxLangChainMiddlewareOptions,
+)
+from openbox_langchain.middleware_factory import create_openbox_langchain_middleware
+
+try:
+    __version__ = version("openbox-langchain-sdk-python")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = [
+    # Types
+    "DEFAULT_HITL_CONFIG",
+    # Errors
+    "ApprovalExpiredError",
+    "ApprovalRejectedError",
+    "ApprovalResponse",
+    "ApprovalTimeoutError",
+    "GovernanceBlockedError",
+    # Client
+    "GovernanceClient",
+    # Config
+    "GovernanceConfig",
+    "GovernanceHaltError",
+    "GovernanceVerdictResponse",
+    "GuardrailsReason",
+    "GuardrailsResult",
+    "GuardrailsValidationError",
+    "HITLConfig",
+    "LangChainGovernanceEvent",
+    "OpenBoxAuthError",
+    "OpenBoxError",
+    "OpenBoxInsecureURLError",
+    # Middleware
+    "OpenBoxLangChainMiddleware",
+    "OpenBoxLangChainMiddlewareOptions",
+    "OpenBoxNetworkError",
+    "Verdict",
+    # Verdict
+    "VerdictContext",
+    "WorkflowEventType",
+    "WorkflowSpanBuffer",
+    # OTel
+    "WorkflowSpanProcessor",
+    # Version
+    "__version__",
+    "build_auth_headers",
+    # Primary API
+    "create_openbox_langchain_middleware",
+    "create_span",
+    "enforce_verdict",
+    "get_global_config",
+    "highest_priority_verdict",
+    "initialize",
+    "is_hitl_applicable",
+    "lang_graph_event_to_context",
+    "merge_config",
+    "parse_approval_response",
+    "parse_governance_response",
+    "poll_until_decision",
+    "rfc3339_now",
+    "safe_serialize",
+    "setup_opentelemetry_for_governance",
+    "to_server_event_type",
+    "traced",
+    "verdict_from_string",
+    "verdict_priority",
+    "verdict_requires_approval",
+    "verdict_should_stop",
+]

openbox_langchain/middleware.py

@@ -0,0 +1,239 @@
+"""OpenBox governance middleware for LangChain agents.
+
+Subclasses AgentMiddleware to intercept agent lifecycle and enforce governance:
+    before_agent  → WorkflowStarted + SignalReceived + pre-screen guardrails
+    wrap_model_call → LLMStarted (PII redaction) → Model → LLMCompleted
+    wrap_tool_call  → ToolStarted → Tool (OTel spans) → ToolCompleted
+    after_agent   → WorkflowCompleted + cleanup
+
+Usage:
+    from openbox_langchain import create_openbox_langchain_middleware
+    middleware = create_openbox_langchain_middleware(api_url=..., api_key=...)
+    agent = create_agent(model=..., tools=[...], middleware=[middleware])
+    result = agent.invoke({"messages": [("user", "Hello")]})
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from langchain.agents.middleware.types import AgentMiddleware, ModelRequest
+from langgraph.prebuilt.tool_node import ToolCallRequest
+from openbox_langgraph.client import GovernanceClient
+from openbox_langgraph.config import GovernanceConfig, get_global_config, merge_config
+from openbox_langgraph.types import GovernanceVerdictResponse
+
+if TYPE_CHECKING:
+    from openbox_langgraph.span_processor import WorkflowSpanProcessor
+
+_logger = logging.getLogger("openbox_langchain")
+
+
+@dataclass
+class OpenBoxLangChainMiddlewareOptions:
+    """Configuration for OpenBoxLangChainMiddleware."""
+
+    agent_name: str | None = None
+    session_id: str | None = None
+    task_queue: str = "langchain"
+    on_api_error: str = "fail_open"
+    governance_timeout: float = 30.0
+    tool_type_map: dict[str, str] = field(default_factory=dict)
+    skip_tool_types: set[str] = field(default_factory=set)
+    sqlalchemy_engine: Any = None
+    send_chain_start_event: bool = True
+    send_chain_end_event: bool = True
+    send_llm_start_event: bool = True
+    send_llm_end_event: bool = True
+    send_tool_start_event: bool = True
+    send_tool_end_event: bool = True
+
+
+class OpenBoxLangChainMiddleware(AgentMiddleware):
+    """AgentMiddleware implementing OpenBox governance for LangChain agents.
+
+    Hooks map directly to the governance event lifecycle:
+    - before_agent: session setup (WorkflowStarted, SignalReceived, pre-screen)
+    - wrap_model_call: LLM governance (LLMStarted/Completed, PII redaction)
+    - wrap_tool_call: tool governance (ToolStarted/Completed, SpanProcessor ctx)
+    - after_agent: session close (WorkflowCompleted, cleanup)
+    """
+
+    def __init__(self, options: OpenBoxLangChainMiddlewareOptions | None = None) -> None:
+        opts = options or OpenBoxLangChainMiddlewareOptions()
+        self._options = opts
+
+        self._config: GovernanceConfig = merge_config({
+            "on_api_error": opts.on_api_error,
+            "api_timeout": opts.governance_timeout,
+            "send_chain_start_event": opts.send_chain_start_event,
+            "send_chain_end_event": opts.send_chain_end_event,
+            "send_tool_start_event": opts.send_tool_start_event,
+            "send_tool_end_event": opts.send_tool_end_event,
+            "send_llm_start_event": opts.send_llm_start_event,
+            "send_llm_end_event": opts.send_llm_end_event,
+            "skip_tool_types": opts.skip_tool_types,
+            "session_id": opts.session_id,
+            "agent_name": opts.agent_name,
+            "task_queue": opts.task_queue,
+            "tool_type_map": opts.tool_type_map,
+        })
+
+        gc = get_global_config()
+        self._client = GovernanceClient(
+            api_url=gc.api_url,
+            api_key=gc.api_key,
+            timeout=gc.governance_timeout,
+            on_api_error=self._config.on_api_error,
+        )
+
+        # OTel span processor for hook-level governance (Layer 2/3)
+        self._span_processor: WorkflowSpanProcessor | None = None
+        if gc.api_url and gc.api_key:
+            try:
+                from openbox_langgraph.otel_setup import setup_opentelemetry_for_governance
+                from openbox_langgraph.span_processor import WorkflowSpanProcessor as WSP
+
+                self._span_processor = WSP()
+                setup_opentelemetry_for_governance(
+                    span_processor=self._span_processor,
+                    api_url=gc.api_url,
+                    api_key=gc.api_key,
+                    ignored_urls=[gc.api_url],
+                    api_timeout=gc.governance_timeout,
+                    on_api_error=self._config.on_api_error,
+                    sqlalchemy_engine=opts.sqlalchemy_engine,
+                )
+                logging.getLogger("opentelemetry.context").setLevel(logging.CRITICAL)
+            except Exception:
+                _logger.warning("Failed to initialize OTel hooks; Layer 2/3 disabled")
+
+        # Reusable thread pool for sync-to-async bridge (shut down via close())
+        self._sync_executor: concurrent.futures.ThreadPoolExecutor | None = None
+
+        # Per-invocation state (reset in before_agent)
+        self._sync_mode: bool = False
+        self._workflow_id: str = ""
+        self._run_id: str = ""
+        self._pre_screen_response: GovernanceVerdictResponse | None = None
+        self._first_llm_call: bool = True
+        self._workflow_type: str = opts.agent_name or "LangChainRun"
+
+    def close(self) -> None:
+        """Release resources (thread pool). Safe to call multiple times."""
+        if self._sync_executor is not None:
+            self._sync_executor.shutdown(wait=False)
+            self._sync_executor = None
+
+    # ─── Async-to-sync bridge ──────────────────────────────────────
+
+    def _run_async(self, coro):
+        """Run async coroutine from sync context with OTel context propagation."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+        if loop and loop.is_running():
+            from opentelemetry import context as otel_context
+            ctx = otel_context.get_current()
+
+            def _run_with_ctx():
+                token = otel_context.attach(ctx)
+                try:
+                    return asyncio.run(coro)
+                finally:
+                    try:
+                        otel_context.detach(token)
+                    except Exception:
+                        pass
+
+            if self._sync_executor is None:
+                self._sync_executor = concurrent.futures.ThreadPoolExecutor(max_workers=1)
+            return self._sync_executor.submit(_run_with_ctx).result()
+        return asyncio.run(coro)
+
+    # ─── Sync hooks (for invoke/stream) ────────────────────────────
+
+    def before_agent(self, state, runtime) -> dict[str, Any] | None:
+        self._sync_mode = True
+        if self._span_processor:
+            self._span_processor.set_sync_mode(True)
+        from openbox_langchain.middleware_hook_handlers import handle_before_agent
+        return self._run_async(handle_before_agent(self, state, runtime))
+
+    def after_agent(self, state, runtime) -> dict[str, Any] | None:
+        from openbox_langchain.middleware_hook_handlers import handle_after_agent
+        self._run_async(handle_after_agent(self, state, runtime))
+        return None
+
+    def wrap_model_call(self, request: ModelRequest, handler) -> Any:
+        from opentelemetry import context as otel_ctx
+        from opentelemetry import trace as otel_tr
+
+        from openbox_langchain.middleware_hook_handlers import handle_wrap_model_call
+
+        tracer = otel_tr.get_tracer("openbox-langchain")
+        span = tracer.start_span("llm.call.sync", kind=otel_tr.SpanKind.INTERNAL)
+        token = otel_ctx.attach(otel_tr.set_span_in_context(span))
+
+        try:
+            async def async_handler(req):
+                return handler(req)
+
+            return self._run_async(handle_wrap_model_call(self, request, async_handler))
+        finally:
+            span.end()
+            try:
+                otel_ctx.detach(token)
+            except Exception:
+                pass
+
+    def wrap_tool_call(self, request: ToolCallRequest, handler) -> Any:
+        from opentelemetry import context as otel_ctx
+        from opentelemetry import trace as otel_tr
+
+        from openbox_langchain.middleware_tool_hook import handle_wrap_tool_call
+
+        tool_name = (
+            request.tool_call.get("name", "tool") if hasattr(request, "tool_call") else "tool"
+        )
+        tracer = otel_tr.get_tracer("openbox-langchain")
+        span = tracer.start_span(f"tool.{tool_name}.sync", kind=otel_tr.SpanKind.INTERNAL)
+        token = otel_ctx.attach(otel_tr.set_span_in_context(span))
+
+        try:
+            async def async_handler(req):
+                return handler(req)
+
+            return self._run_async(handle_wrap_tool_call(self, request, async_handler))
+        finally:
+            span.end()
+            try:
+                otel_ctx.detach(token)
+            except Exception:
+                pass
+
+    # ─── Async hooks (for ainvoke/astream) ─────────────────────────
+
+    async def abefore_agent(self, state, runtime) -> dict[str, Any] | None:
+        self._sync_mode = False
+        if self._span_processor:
+            self._span_processor.set_sync_mode(False)
+        from openbox_langchain.middleware_hook_handlers import handle_before_agent
+        return await handle_before_agent(self, state, runtime)
+
+    async def aafter_agent(self, state, runtime) -> dict[str, Any] | None:
+        from openbox_langchain.middleware_hook_handlers import handle_after_agent
+        return await handle_after_agent(self, state, runtime)
+
+    async def awrap_model_call(self, request: ModelRequest, handler) -> Any:
+        from openbox_langchain.middleware_hook_handlers import handle_wrap_model_call
+        return await handle_wrap_model_call(self, request, handler)
+
+    async def awrap_tool_call(self, request: ToolCallRequest, handler) -> Any:
+        from openbox_langchain.middleware_tool_hook import handle_wrap_tool_call
+        return await handle_wrap_tool_call(self, request, handler)

openbox_langchain/middleware_factory.py

@@ -0,0 +1,67 @@
+"""Factory for creating configured OpenBoxLangChainMiddleware instances.
+
+Usage:
+    from openbox_langchain import create_openbox_langchain_middleware
+    middleware = create_openbox_langchain_middleware(
+        api_url=os.environ["OPENBOX_URL"],
+        api_key=os.environ["OPENBOX_API_KEY"],
+        agent_name="MyAgent",
+    )
+    agent = create_agent(model=..., tools=[...], middleware=[middleware])
+    result = agent.invoke({"messages": [("user", "Hello")]})
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+from openbox_langchain.middleware import (
+    OpenBoxLangChainMiddleware,
+    OpenBoxLangChainMiddlewareOptions,
+)
+
+
+def create_openbox_langchain_middleware(
+    *,
+    api_url: str,
+    api_key: str,
+    agent_name: str | None = None,
+    governance_timeout: float = 30.0,
+    validate: bool = True,
+    sqlalchemy_engine: Any = None,
+    **kwargs: Any,
+) -> OpenBoxLangChainMiddleware:
+    """Create a configured OpenBoxLangChainMiddleware for create_agent(middleware=[...]).
+
+    Validates the API key and sets up global config before returning the middleware.
+
+    Args:
+        api_url: Base URL of your OpenBox Core instance.
+        api_key: API key in ``obx_live_*`` or ``obx_test_*`` format.
+        agent_name: Agent name as configured in the dashboard.
+        governance_timeout: HTTP timeout in seconds (default 30.0).
+        validate: If True, validates the API key against the server on startup.
+        sqlalchemy_engine: Optional SQLAlchemy Engine for DB governance.
+        **kwargs: Additional kwargs forwarded to OpenBoxLangChainMiddlewareOptions.
+
+    Returns:
+        A configured ``OpenBoxLangChainMiddleware`` ready for create_agent().
+    """
+    from openbox_langgraph.config import initialize
+
+    initialize(
+        api_url=api_url,
+        api_key=api_key,
+        governance_timeout=governance_timeout,
+        validate=validate,
+    )
+
+    valid_fields = {f.name for f in dataclasses.fields(OpenBoxLangChainMiddlewareOptions)}
+    options = OpenBoxLangChainMiddlewareOptions(
+        agent_name=agent_name,
+        governance_timeout=governance_timeout,
+        sqlalchemy_engine=sqlalchemy_engine,
+        **{k: v for k, v in kwargs.items() if k in valid_fields},
+    )
+    return OpenBoxLangChainMiddleware(options)

openbox_langchain/middleware_hook_handlers.py

@@ -0,0 +1,231 @@
+"""Governance hook handler functions for OpenBoxLangChainMiddleware.
+
+before_agent / after_agent / wrap_model_call / wrap_tool_call implementations.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from openbox_langgraph.types import LangChainGovernanceEvent, safe_serialize
+from openbox_langgraph.verdict_handler import enforce_verdict
+
+from openbox_langchain.middleware_hooks import (
+    _apply_pii_redaction,
+    _base_event_fields,
+    _evaluate,
+    _extract_governance_blocked,
+    _extract_last_user_message,
+    _extract_prompt_from_messages,
+    _extract_response_metadata,
+    _poll_approval_or_halt,
+    _run_with_otel_context,
+)
+
+_logger = logging.getLogger("openbox_langchain")
+
+if TYPE_CHECKING:
+    from openbox_langchain.middleware import OpenBoxLangChainMiddleware
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Hook: before_agent → WorkflowStarted + pre-screen
+# ═══════════════════════════════════════════════════════════════════
+
+
+async def handle_before_agent(
+    mw: OpenBoxLangChainMiddleware, state: Any, runtime: Any,
+) -> dict[str, Any] | None:
+    """Session setup: SignalReceived + WorkflowStarted + pre-screen guardrails."""
+    # Generate unique session IDs per invocation
+    config = getattr(runtime, "config", None) or {}
+    configurable = config.get("configurable", {}) if isinstance(config, dict) else {}
+    thread_id = configurable.get("thread_id", "langchain")
+    _turn = uuid.uuid4().hex
+    mw._workflow_id = f"{thread_id}-{_turn[:8]}"
+    mw._run_id = f"{thread_id}-run-{_turn[8:16]}"
+    mw._first_llm_call = True
+    mw._pre_screen_response = None
+
+    base = _base_event_fields(mw)
+    messages = (
+        state.get("messages", []) if isinstance(state, dict)
+        else getattr(state, "messages", [])
+    )
+
+    # SignalReceived — user prompt as trigger
+    user_prompt = _extract_last_user_message(messages)
+    if user_prompt:
+        sig_event = LangChainGovernanceEvent(
+            **base, event_type="SignalReceived",
+            activity_id=f"{mw._run_id}-sig", activity_type="user_prompt",
+            signal_name="user_prompt", signal_args=[user_prompt],
+        )
+        await _evaluate(mw, sig_event)
+
+    # WorkflowStarted
+    if mw._config.send_chain_start_event:
+        wf_event = LangChainGovernanceEvent(
+            **base, event_type="WorkflowStarted",
+            activity_id=f"{mw._run_id}-wf",
+            activity_type=mw._workflow_type,
+            activity_input=[safe_serialize(state)],
+        )
+        await _evaluate(mw, wf_event)
+
+    # Pre-screen LLMStarted (guardrails on user prompt)
+    if mw._config.send_llm_start_event and user_prompt and user_prompt.strip():
+        gov = LangChainGovernanceEvent(
+            **base, event_type="LLMStarted",
+            activity_id=f"{mw._run_id}-pre", activity_type="llm_call",
+            activity_input=[{"prompt": user_prompt}], prompt=user_prompt,
+        )
+        response = await _evaluate(mw, gov)
+
+        if response is not None:
+            enforcement_error: Exception | None = None
+            try:
+                result = enforce_verdict(response, "llm_start")
+            except Exception as exc:
+                enforcement_error = exc
+
+            if enforcement_error is not None and mw._config.send_chain_end_event:
+                wf_end = LangChainGovernanceEvent(
+                    **_base_event_fields(mw), event_type="WorkflowCompleted",
+                    activity_id=f"{mw._run_id}-wf",
+                    activity_type=mw._workflow_type,
+                    status="failed", error=str(enforcement_error),
+                )
+                await _evaluate(mw, wf_end)
+                raise enforcement_error
+
+            if result and result.requires_hitl:
+                await _poll_approval_or_halt(mw, f"{mw._run_id}-pre", "llm_call")
+
+        mw._pre_screen_response = response
+    return None
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Hook: after_agent → WorkflowCompleted
+# ═══════════════════════════════════════════════════════════════════
+
+
+async def handle_after_agent(
+    mw: OpenBoxLangChainMiddleware, state: Any, runtime: Any,
+) -> dict[str, Any] | None:
+    """Session close: WorkflowCompleted + cleanup."""
+    if mw._config.send_chain_end_event:
+        messages = (
+            state.get("messages", []) if isinstance(state, dict)
+            else getattr(state, "messages", [])
+        )
+        last_content = None
+        if messages:
+            last_msg = messages[-1]
+            last_content = (
+                getattr(last_msg, "content", None) if hasattr(last_msg, "content")
+                else (last_msg.get("content") if isinstance(last_msg, dict) else None)
+            )
+
+        wf_event = LangChainGovernanceEvent(
+            **_base_event_fields(mw), event_type="WorkflowCompleted",
+            activity_id=f"{mw._run_id}-wf",
+            activity_type=mw._workflow_type,
+            workflow_output=safe_serialize({"result": last_content}),
+            status="completed",
+        )
+        await _evaluate(mw, wf_event)
+
+    if mw._span_processor:
+        mw._span_processor.unregister_workflow(mw._workflow_id)
+    return None
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Hook: wrap_model_call → LLMStarted/Completed
+# ═══════════════════════════════════════════════════════════════════
+
+
+async def handle_wrap_model_call(
+    mw: OpenBoxLangChainMiddleware, request: Any, handler: Any,
+) -> Any:
+    """LLM governance: LLMStarted → PII redaction → Model → LLMCompleted."""
+    prompt_text = _extract_prompt_from_messages(request.messages)
+    if not prompt_text.strip():
+        return await handler(request)
+
+    base = _base_event_fields(mw)
+    activity_id = str(uuid.uuid4())
+
+    # Reuse pre-screen response for first LLM call
+    if mw._first_llm_call and mw._pre_screen_response is not None:
+        response = mw._pre_screen_response
+        mw._pre_screen_response = None
+        mw._first_llm_call = False
+        activity_id = f"{mw._run_id}-pre"
+    else:
+        mw._first_llm_call = False
+        if mw._config.send_llm_start_event:
+            gov = LangChainGovernanceEvent(
+                **base, event_type="LLMStarted", activity_id=activity_id,
+                activity_type="llm_call", activity_input=[{"prompt": prompt_text}],
+                prompt=prompt_text,
+            )
+            response = await _evaluate(mw, gov)
+        else:
+            response = None
+
+    # PII redaction
+    if response and response.guardrails_result:
+        gr = response.guardrails_result
+        if gr.input_type == "activity_input" and gr.redacted_input is not None:
+            _apply_pii_redaction(request.messages, gr.redacted_input)
+
+    # Register SpanProcessor context
+    if mw._span_processor:
+        mw._span_processor.set_activity_context(mw._workflow_id, activity_id, {
+            **base, "event_type": "ActivityStarted",
+            "activity_id": activity_id, "activity_type": "llm_call",
+        })
+
+    # Execute model with OTel span + HITL retry loop
+    start = time.monotonic()
+    while True:
+        try:
+            model_response = await _run_with_otel_context(
+                mw, "llm.call", activity_id, handler, request,
+            )
+            break
+        except Exception as exc:
+            hook_err = _extract_governance_blocked(exc)
+            if hook_err is not None and hook_err.verdict == "require_approval":
+                await _poll_approval_or_halt(mw, activity_id, "llm_call")
+            else:
+                raise
+    duration_ms = (time.monotonic() - start) * 1000
+
+    # LLMCompleted
+    if mw._config.send_llm_end_event:
+        meta = _extract_response_metadata(model_response)
+        completed = LangChainGovernanceEvent(
+            **_base_event_fields(mw), event_type="LLMCompleted",
+            activity_id=f"{activity_id}-c", activity_type="llm_call",
+            status="completed", duration_ms=duration_ms,
+            llm_model=meta.get("llm_model"),
+            input_tokens=meta.get("input_tokens"),
+            output_tokens=meta.get("output_tokens"),
+            total_tokens=meta.get("total_tokens"),
+            has_tool_calls=meta.get("has_tool_calls"),
+            completion=meta.get("completion"),
+        )
+        resp = await _evaluate(mw, completed)
+        if resp is not None:
+            enforce_verdict(resp, "llm_end")
+
+    if mw._span_processor:
+        mw._span_processor.clear_activity_context(mw._workflow_id, activity_id)
+    return model_response

openbox_langchain/middleware_hooks.py

@@ -0,0 +1,220 @@
+"""Hook implementations for OpenBoxLangChainMiddleware.
+
+Each function implements one middleware hook, mapping to governance events:
+- handle_before_agent  → SignalReceived + WorkflowStarted + pre-screen LLMStarted
+- handle_after_agent   → WorkflowCompleted + cleanup
+- handle_wrap_model_call → LLMStarted (PII redaction) → Model → LLMCompleted
+- handle_wrap_tool_call  → ToolStarted → Tool (OTel spans) → ToolCompleted
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from openbox_langgraph.errors import (
+    ApprovalExpiredError,
+    ApprovalRejectedError,
+    GovernanceBlockedError,
+    GovernanceHaltError,
+)
+from openbox_langgraph.hitl import HITLPollParams, poll_until_decision
+from openbox_langgraph.types import (
+    rfc3339_now,
+)
+from opentelemetry import context as otel_context
+from opentelemetry import trace as otel_trace
+
+_tracer = otel_trace.get_tracer("openbox-langchain")
+_logger = logging.getLogger("openbox_langchain")
+
+if TYPE_CHECKING:
+    from openbox_langchain.middleware import OpenBoxLangChainMiddleware
+
+
+# ═══════════════════════════════════════════════════════════════════
+# Helpers
+# ═══════════════════════════════════════════════════════════════════
+
+
+def _base_event_fields(mw: OpenBoxLangChainMiddleware) -> dict[str, Any]:
+    """Common fields for all governance events."""
+    return {
+        "source": "workflow-telemetry",
+        "workflow_id": mw._workflow_id,
+        "run_id": mw._run_id,
+        "workflow_type": mw._workflow_type,
+        "task_queue": mw._config.task_queue,
+        "timestamp": rfc3339_now(),
+        "session_id": mw._config.session_id,
+    }
+
+
+async def _evaluate(mw: OpenBoxLangChainMiddleware, event: Any) -> Any:
+    """Send governance event — sync httpx in sync mode, async otherwise."""
+    if mw._sync_mode:
+        return mw._client.evaluate_event_sync(event)
+    return await mw._client.evaluate_event(event)
+
+
+def _extract_governance_blocked(exc: Exception) -> GovernanceBlockedError | None:
+    """Unwrap GovernanceBlockedError from LLM SDK exception chains."""
+    cause: BaseException | None = exc
+    seen: set[int] = set()
+    while cause is not None:
+        if id(cause) in seen:
+            break
+        seen.add(id(cause))
+        if isinstance(cause, GovernanceBlockedError):
+            return cause
+        cause = getattr(cause, "__cause__", None) or getattr(cause, "__context__", None)
+    return None
+
+
+async def _poll_approval_or_halt(
+    mw: OpenBoxLangChainMiddleware, activity_id: str, activity_type: str,
+) -> None:
+    """Poll for HITL approval. On rejection/expiry, raises GovernanceHaltError."""
+    if mw._span_processor:
+        mw._span_processor.clear_activity_abort(mw._workflow_id, activity_id)
+    try:
+        await poll_until_decision(
+            mw._client,
+            HITLPollParams(
+                workflow_id=mw._workflow_id, run_id=mw._run_id,
+                activity_id=activity_id, activity_type=activity_type,
+            ),
+            mw._config.hitl,
+        )
+    except (ApprovalRejectedError, ApprovalExpiredError) as e:
+        if mw._span_processor:
+            mw._span_processor.clear_activity_context(mw._workflow_id, activity_id)
+        raise GovernanceHaltError(str(e)) from e
+
+
+def _extract_last_user_message(messages: list[Any]) -> str | None:
+    """Extract last human/user message text from agent state messages."""
+    for msg in reversed(messages):
+        if isinstance(msg, dict):
+            if msg.get("role") in ("user", "human"):
+                content = msg.get("content")
+                return content if isinstance(content, str) else None
+        elif hasattr(msg, "type") and msg.type in ("human", "generic"):
+            content = msg.content
+            return content if isinstance(content, str) else None
+    return None
+
+
+def _extract_prompt_from_messages(messages: Any) -> str:
+    """Extract human/user message text from a messages list."""
+    if not isinstance(messages, (list, tuple)):
+        return ""
+    parts: list[str] = []
+    for msg in messages:
+        if isinstance(msg, (list, tuple)):
+            for inner in msg:
+                _append_human_content(inner, parts)
+        else:
+            _append_human_content(msg, parts)
+    return "\n".join(parts)
+
+
+def _append_human_content(msg: Any, parts: list[str]) -> None:
+    """Append human message content to parts list."""
+    role = None
+    content = None
+    if hasattr(msg, "type"):
+        role = msg.type
+        content = msg.content
+    elif isinstance(msg, dict):
+        role = msg.get("role") or msg.get("type", "")
+        content = msg.get("content", "")
+    if role not in ("human", "user", "generic"):
+        return
+    if isinstance(content, str):
+        parts.append(content)
+    elif isinstance(content, list):
+        for part in content:
+            if isinstance(part, dict) and part.get("type") == "text":
+                parts.append(part.get("text", ""))
+
+
+def _apply_pii_redaction(messages: list[Any], redacted_input: Any) -> None:
+    """Apply PII redaction to messages in-place from guardrails response."""
+    redacted_text = None
+    if isinstance(redacted_input, list) and redacted_input:
+        first = redacted_input[0]
+        if isinstance(first, dict):
+            redacted_text = first.get("prompt")
+        elif isinstance(first, str):
+            redacted_text = first
+    elif isinstance(redacted_input, str):
+        redacted_text = redacted_input
+
+    if not redacted_text:
+        return
+
+    for i in range(len(messages) - 1, -1, -1):
+        msg = messages[i]
+        if hasattr(msg, "type") and msg.type in ("human", "generic"):
+            msg.content = redacted_text
+            break
+        elif isinstance(msg, dict) and msg.get("role") in ("user", "human"):
+            msg["content"] = redacted_text
+            break
+
+
+def _extract_response_metadata(response: Any) -> dict[str, Any]:
+    """Extract tokens, model name, completion from model response."""
+    result: dict[str, Any] = {}
+    ai_msg = response
+    if hasattr(response, "message"):
+        ai_msg = response.message
+
+    if hasattr(ai_msg, "response_metadata"):
+        meta = ai_msg.response_metadata or {}
+        result["llm_model"] = meta.get("model_name") or meta.get("model")
+
+    usage = getattr(ai_msg, "usage_metadata", None) or {}
+    if isinstance(usage, dict):
+        result["input_tokens"] = usage.get("input_tokens") or usage.get("prompt_tokens")
+        result["output_tokens"] = usage.get("output_tokens") or usage.get("completion_tokens")
+        inp = result.get("input_tokens") or 0
+        out = result.get("output_tokens") or 0
+        result["total_tokens"] = inp + out if (inp or out) else None
+
+    content = getattr(ai_msg, "content", None)
+    if isinstance(content, str):
+        result["completion"] = content
+    elif isinstance(content, list):
+        text_parts = [
+            p.get("text", "") for p in content
+            if isinstance(p, dict) and p.get("type") == "text"
+        ]
+        result["completion"] = " ".join(text_parts) if text_parts else None
+
+    result["has_tool_calls"] = bool(getattr(ai_msg, "tool_calls", None))
+    return result
+
+
+async def _run_with_otel_context(
+    mw: OpenBoxLangChainMiddleware, span_name: str, activity_id: str,
+    handler: Any, request: Any,
+) -> Any:
+    """Execute handler inside an OTel span for trace context propagation."""
+    parent_ctx = otel_context.get_current()
+    span = _tracer.start_span(span_name, context=parent_ctx, kind=otel_trace.SpanKind.INTERNAL)
+    token = otel_context.attach(otel_trace.set_span_in_context(span, parent_ctx))
+
+    trace_id = span.get_span_context().trace_id
+    if mw._span_processor and trace_id:
+        mw._span_processor.register_trace(trace_id, mw._workflow_id, activity_id)
+
+    try:
+        return await handler(request)
+    finally:
+        span.end()
+        try:
+            otel_context.detach(token)
+        except Exception:
+            pass

openbox_langchain/middleware_tool_hook.py

@@ -0,0 +1,144 @@
+"""Tool governance hook for OpenBoxLangChainMiddleware.
+
+Separated from middleware_hook_handlers.py to stay under 200 lines per file.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from openbox_langgraph.errors import GovernanceBlockedError, GovernanceHaltError
+from openbox_langgraph.types import LangChainGovernanceEvent, safe_serialize
+from openbox_langgraph.verdict_handler import enforce_verdict
+
+from openbox_langchain.middleware_hooks import (
+    _base_event_fields,
+    _evaluate,
+    _extract_governance_blocked,
+    _poll_approval_or_halt,
+    _run_with_otel_context,
+)
+
+_logger = logging.getLogger("openbox_langchain")
+
+if TYPE_CHECKING:
+    from openbox_langchain.middleware import OpenBoxLangChainMiddleware
+
+
+async def handle_wrap_tool_call(
+    mw: OpenBoxLangChainMiddleware, request: Any, handler: Any,
+) -> Any:
+    """Tool governance: ToolStarted → Tool (OTel spans) → ToolCompleted."""
+    tool_name = request.tool_call["name"]
+    tool_args = request.tool_call.get("args", {})
+
+    # Skip governance for excluded tools
+    if tool_name in mw._config.skip_tool_types:
+        return await handler(request)
+
+    activity_id = str(uuid.uuid4())
+    tool_type = mw._config.tool_type_map.get(tool_name)
+    base = _base_event_fields(mw)
+
+    # Register SpanProcessor context for Layer 2 hooks
+    if mw._span_processor:
+        mw._span_processor.set_activity_context(mw._workflow_id, activity_id, {
+            **base, "event_type": "ActivityStarted",
+            "activity_id": activity_id, "activity_type": tool_name,
+        })
+
+    # ToolStarted + verdict enforcement
+    if mw._config.send_tool_start_event:
+        gov = LangChainGovernanceEvent(
+            **base, event_type="ToolStarted", activity_id=activity_id,
+            activity_type=tool_name, activity_input=[safe_serialize(tool_args)],
+            tool_name=tool_name, tool_type=tool_type,
+        )
+        response = await _evaluate(mw, gov)
+        if response is not None:
+            result = enforce_verdict(response, "tool_start")
+            if result.requires_hitl:
+                try:
+                    await _poll_approval_or_halt(mw, activity_id, tool_name)
+                except GovernanceHaltError:
+                    if mw._span_processor:
+                        mw._span_processor.clear_activity_context(
+                            mw._workflow_id, activity_id
+                        )
+                    raise
+
+    # Execute tool with OTel span + HITL retry loop
+    start = time.monotonic()
+    while True:
+        try:
+            tool_result = await _run_with_otel_context(
+                mw, f"tool.{tool_name}", activity_id, handler, request,
+            )
+            break
+        except GovernanceBlockedError as hook_err:
+            if hook_err.verdict != "require_approval":
+                duration_ms = (time.monotonic() - start) * 1000
+                await _send_tool_failed(
+                    mw, activity_id, tool_name, tool_type, hook_err, duration_ms,
+                )
+                raise
+            await _poll_approval_or_halt(mw, activity_id, tool_name)
+        except Exception as exc:
+            hook_err = _extract_governance_blocked(exc)
+            if hook_err is not None and hook_err.verdict == "require_approval":
+                await _poll_approval_or_halt(mw, activity_id, tool_name)
+            else:
+                duration_ms = (time.monotonic() - start) * 1000
+                await _send_tool_failed(mw, activity_id, tool_name, tool_type, exc, duration_ms)
+                raise
+    duration_ms = (time.monotonic() - start) * 1000
+
+    # Clear SpanProcessor context
+    if mw._span_processor:
+        mw._span_processor.clear_activity_context(mw._workflow_id, activity_id)
+
+    # ToolCompleted + verdict enforcement
+    if mw._config.send_tool_end_event:
+        try:
+            serialized_output = (
+                safe_serialize({"result": tool_result})
+                if isinstance(tool_result, str)
+                else safe_serialize(tool_result)
+            )
+        except Exception:
+            serialized_output = {"result": str(tool_result)}
+        completed = LangChainGovernanceEvent(
+            **_base_event_fields(mw), event_type="ToolCompleted",
+            activity_id=f"{activity_id}-c", activity_type=tool_name,
+            activity_output=serialized_output, tool_name=tool_name,
+            tool_type=tool_type, status="completed", duration_ms=duration_ms,
+        )
+        resp = await _evaluate(mw, completed)
+        if resp is not None:
+            result = enforce_verdict(resp, "tool_end")
+            if result.requires_hitl:
+                await _poll_approval_or_halt(mw, f"{activity_id}-c", tool_name)
+
+    return tool_result
+
+
+async def _send_tool_failed(
+    mw: OpenBoxLangChainMiddleware,
+    activity_id: str, tool_name: str, tool_type: str | None,
+    error: Exception, duration_ms: float,
+) -> None:
+    """Send ToolCompleted with failed status."""
+    if mw._span_processor:
+        mw._span_processor.clear_activity_context(mw._workflow_id, activity_id)
+    if mw._config.send_tool_end_event:
+        failed_event = LangChainGovernanceEvent(
+            **_base_event_fields(mw), event_type="ToolCompleted",
+            activity_id=f"{activity_id}-c", activity_type=tool_name,
+            activity_output=safe_serialize({"error": str(error)}),
+            tool_name=tool_name, tool_type=tool_type,
+            status="failed", duration_ms=duration_ms,
+        )
+        await _evaluate(mw, failed_event)

openbox_langchain_sdk_python-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+openbox_langchain/__init__.py,sha256=ldOkI33_EGScEOBLuxSFjVac4nPNb5NVCO8MD50QMCI,3090
+openbox_langchain/middleware.py,sha256=PeUtlfaWEQveokqNejDBSjDvnbXcIOtE32RVRa9ishE,10212
+openbox_langchain/middleware_factory.py,sha256=6fl3lDfH9oO9-GMI2t0yQpkd--qnMLh_AQjFI_xkWHY,2302
+openbox_langchain/middleware_hook_handlers.py,sha256=H40_OUGvCIjRE-2YCPa0ZrvU12jm9mKoHdWCG__8mwA,9426
+openbox_langchain/middleware_hooks.py,sha256=k31ag4QMQnxgukwR3XX_VJP9HUpWcBQk-k_1bafemlI,8261
+openbox_langchain/middleware_tool_hook.py,sha256=_qa5oICzHLoi8vCgIZmV3ZkIAlMM3Ta7NR7j1eEIz_U,5587
+openbox_langchain_sdk_python-0.1.0.dist-info/METADATA,sha256=g3fLEL4TvkvcIIBDGmbLIw7Y9J2sKgitQmVz3E1ouOw,3799
+openbox_langchain_sdk_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+openbox_langchain_sdk_python-0.1.0.dist-info/RECORD,,

openbox_langchain_sdk_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any