openbox-sdk-python 0.2.0__py3-none-any.whl

openbox_core/instrumentation/llm.py

@@ -0,0 +1,3 @@
+"""LLM provider instrumentation placeholder."""
+
+__all__: list[str] = []

openbox_core/instrumentation/manager.py

@@ -0,0 +1,135 @@
+"""InstrumentationManager — idempotent install/uninstall of all wrappers.
+
+Owned by OpenBoxRuntime. Install order matters:
+
+1. OTel provider + passive span processor (``install_opentelemetry`` toggle)
+2. cross-thread ContextVar executor patch (best-effort; needs a running loop)
+3. publish the HookRuntime to the shared instrumentation state
+4. HTTP / DB / file wrappers per config toggles (each deferral is LOGGED)
+
+The evaluate call must never instrument itself: the ignored-URL set always
+contains the configured ``api_url``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from ..otel.propagation import install_context_propagating_executor
+from ..otel.setup import install_opentelemetry, shutdown_opentelemetry
+from . import db as db_instrumentation
+from . import file as file_instrumentation
+from . import http as http_instrumentation
+from .shared import get_hook_runtime, set_hook_runtime
+
+if TYPE_CHECKING:
+    from ..runtime import OpenBoxRuntime
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["InstrumentationManager"]
+
+
+class InstrumentationManager:
+    """Install/uninstall lifecycle with per-target guard flags."""
+
+    def __init__(self, runtime: OpenBoxRuntime, *, extra_ignored_urls: set[str] | None = None):
+        self._runtime = runtime
+        self._installed = False
+        self._provider: Any = None
+        self._installed_targets: list[str] = []
+        self._extra_ignored_urls = set(extra_ignored_urls or ())
+
+    @property
+    def installed_targets(self) -> list[str]:
+        return list(self._installed_targets)
+
+    def install(self) -> None:
+        """Idempotent — a second install() is a no-op."""
+        if self._installed:
+            return
+        config = self._runtime.config
+        instrumentation = config.instrumentation
+
+        if instrumentation.install_opentelemetry:
+            self._provider, _ = install_opentelemetry(self._runtime.context_store)
+
+        # ContextVars → executor threads (no running loop ⇒ skipped, logged).
+        if not install_context_propagating_executor():
+            logger.info("executor ContextVar patch deferred (no running event loop)")
+
+        # Self-instrumentation guard: never govern our own evaluate calls.
+        http_instrumentation.set_ignored_url_prefixes(
+            {config.api_url, *self._extra_ignored_urls}
+        )
+
+        from ..hooks.preflight import HookRuntime
+
+        set_hook_runtime(HookRuntime(self._runtime))
+
+        if instrumentation.http_enabled:
+            if http_instrumentation.install_requests():
+                self._installed_targets.append("requests")
+            if http_instrumentation.install_httpx():
+                self._installed_targets.append("httpx")
+                # Body capture patches Client.send AFTER OTel instrumentation so
+                # the captured original send already carries the request hook.
+                if http_instrumentation.install_httpx_body_capture():
+                    self._installed_targets.append("httpx_body_capture")
+            if http_instrumentation.install_urllib3():
+                self._installed_targets.append("urllib3")
+            if http_instrumentation.install_urllib():
+                self._installed_targets.append("urllib")
+        else:
+            logger.info("HTTP instrumentation disabled by config")
+
+        if instrumentation.db_enabled:
+            if db_instrumentation.install_sqlalchemy():
+                self._installed_targets.append("sqlalchemy")
+            if db_instrumentation.install_dbapi():
+                self._installed_targets.append("dbapi")
+            if db_instrumentation.install_asyncpg():
+                self._installed_targets.append("asyncpg")
+            if db_instrumentation.install_redis():
+                self._installed_targets.append("redis")
+            if db_instrumentation.install_pymongo():
+                self._installed_targets.append("pymongo")
+        else:
+            logger.info("DB instrumentation disabled by config")
+
+        if instrumentation.file_enabled:
+            if file_instrumentation.install_file_io():
+                self._installed_targets.append("file")
+        else:
+            logger.info("file instrumentation disabled by config (opt-in)")
+
+        # Function instrumentation is decorator-based (@governed) — nothing to
+        # patch; it activates through the published hook runtime.
+        logger.info(f"OpenBox instrumentation installed: {self._installed_targets}")
+        self._installed = True
+
+    def uninstall(self) -> None:
+        """Restore every original and flush OTel (idempotent, safe shutdown)."""
+        if not self._installed:
+            return
+        file_instrumentation.uninstall_file_io()
+        db_instrumentation.uninstall_pymongo()
+        db_instrumentation.uninstall_redis()
+        db_instrumentation.uninstall_asyncpg()
+        db_instrumentation.uninstall_dbapi()
+        db_instrumentation.uninstall_sqlalchemy()
+        # Reverse install order: unwind the send patch before OTel httpx.
+        http_instrumentation.uninstall_urllib()
+        http_instrumentation.uninstall_urllib3()
+        http_instrumentation.uninstall_httpx_body_capture()
+        http_instrumentation.uninstall_httpx()
+        http_instrumentation.uninstall_requests()
+        if get_hook_runtime() is not None:
+            set_hook_runtime(None)
+        if self._provider is not None:
+            shutdown_opentelemetry(self._provider)
+            self._provider = None
+        self._installed_targets.clear()
+        self._installed = False
+        logger.info("OpenBox instrumentation uninstalled")

openbox_core/instrumentation/shared.py

@@ -0,0 +1,27 @@
+"""Shared instrumentation state — the active HookRuntime.
+
+Patched call sites (module-level hooks, builtins patches) can't hold instance
+references, so the manager publishes the active runtime here on install and
+clears it on uninstall. One active runtime per process (matching the
+one-global-config model of the existing SDKs).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..hooks.preflight import HookRuntime
+
+__all__ = ["set_hook_runtime", "get_hook_runtime"]
+
+_hook_runtime: HookRuntime | None = None
+
+
+def set_hook_runtime(runtime: HookRuntime | None) -> None:
+    global _hook_runtime
+    _hook_runtime = runtime
+
+
+def get_hook_runtime() -> HookRuntime | None:
+    return _hook_runtime

openbox_core/otel/__init__.py

@@ -0,0 +1,3 @@
+"""OTel provider/exporter lifecycle, span processing, trace context, and propagation."""
+
+__all__: list[str] = []

openbox_core/otel/propagation.py

@@ -0,0 +1,45 @@
+"""Cross-thread ContextVar propagation for run_in_executor threads.
+
+Python < 3.12 does NOT copy ContextVars into default-executor threads: the
+HTTP/DB instrumentors then create spans with trace_id=0 in the worker thread
+and the hook runtime can't find the bound ActivityContext. Installing a
+context-propagating executor fixes both on Python 3.11, the pinned floor.
+"""
+
+from __future__ import annotations
+
+import concurrent.futures
+import contextvars
+import functools
+import logging
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["ContextPropagatingExecutor", "install_context_propagating_executor"]
+
+
+class ContextPropagatingExecutor(concurrent.futures.ThreadPoolExecutor):
+    """ThreadPoolExecutor that copies ContextVars into spawned threads."""
+
+    def submit(self, fn, /, *args, **kwargs):
+        ctx = contextvars.copy_context()
+        return super().submit(ctx.run, functools.partial(fn, *args, **kwargs))
+
+
+def install_context_propagating_executor(max_workers: int = 32) -> bool:
+    """Install a ContextVar-propagating default executor on the running loop.
+
+    Only the DEFAULT executor (``run_in_executor(None, ...)``) is patched;
+    explicit user executors are untouched. Returns True when installed,
+    False when no loop is running (callers may retry from async context).
+    """
+    import asyncio
+
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        logger.debug("No running event loop — executor patch skipped")
+        return False
+    loop.set_default_executor(ContextPropagatingExecutor(max_workers=max_workers))
+    logger.info("Installed context-propagating default executor")
+    return True

openbox_core/otel/provider.py

@@ -0,0 +1,35 @@
+"""Create-or-reuse TracerProvider — never clobber a user-installed provider."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["get_or_create_tracer_provider", "get_tracer"]
+
+
+def get_or_create_tracer_provider() -> Any:
+    """Return the process TracerProvider, creating one only if none exists.
+
+    Attaches to an existing SDK provider (user-installed providers are
+    reused, never replaced); only the no-op default is upgraded to a real
+    ``opentelemetry.sdk.trace.TracerProvider``.
+    """
+    from opentelemetry import trace
+    from opentelemetry.sdk.trace import TracerProvider
+
+    provider = trace.get_tracer_provider()
+    if not isinstance(provider, TracerProvider):
+        provider = TracerProvider()
+        trace.set_tracer_provider(provider)
+        logger.info("Created OpenBox TracerProvider (no SDK provider was set)")
+    return provider
+
+
+def get_tracer(name: str = "openbox_core") -> Any:
+    """Tracer for spans the SDK creates itself (db/file/function wrappers)."""
+    from opentelemetry import trace
+
+    return trace.get_tracer(name)

openbox_core/otel/setup.py

@@ -0,0 +1,36 @@
+"""install_opentelemetry()/shutdown_opentelemetry() — OTel lifecycle."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..context import ContextStore
+from .provider import get_or_create_tracer_provider
+from .span_processor import OpenBoxSpanProcessor
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["install_opentelemetry", "shutdown_opentelemetry"]
+
+
+def install_opentelemetry(context_store: ContextStore) -> tuple[Any, OpenBoxSpanProcessor]:
+    """Attach the passive OpenBox span processor to the process provider.
+
+    Reuses an existing user provider; returns (provider, processor) so the
+    caller can flush/detach on shutdown.
+    """
+    provider = get_or_create_tracer_provider()
+    processor = OpenBoxSpanProcessor(context_store)
+    provider.add_span_processor(processor)
+    logger.info("Registered OpenBoxSpanProcessor with the TracerProvider")
+    return provider, processor
+
+
+def shutdown_opentelemetry(provider: Any) -> None:
+    """Flush pending spans. The provider itself is left running — it may be
+    user-owned; the SDK only ever ADDS a processor, so it only flushes."""
+    try:
+        provider.force_flush(timeout_millis=5000)
+    except Exception:
+        logger.debug("TracerProvider force_flush failed", exc_info=True)

openbox_core/otel/span_processor.py

@@ -0,0 +1,62 @@
+"""OpenBoxSpanProcessor — a PASSIVE SpanProcessor.
+
+It registers trace -> ActivityContext correlations so hook code can resolve
+the bound context from any child span, and nothing else. It MUST NOT perform
+preflight blocking: ``on_end`` fires after the operation already ran, so hard
+blocking lives exclusively in the wrapper call path (hooks/wrappers.py).
+Abort/halt registries live in the ContextStore/runtime — not here.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from opentelemetry.sdk.trace import SpanProcessor
+
+from ..context import ContextStore
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["OpenBoxSpanProcessor"]
+
+
+class OpenBoxSpanProcessor(SpanProcessor):
+    """Passive correlation processor bound to a ContextStore."""
+
+    def __init__(self, context_store: ContextStore):
+        self._store = context_store
+
+    def on_start(self, span: Any, parent_context: Any = None) -> None:
+        """Register the span's trace to the CURRENTLY BOUND context (if any).
+
+        Frameworks register the activity root trace explicitly via
+        ``activity_scope``; this passive hook additionally catches spans whose
+        traces were minted after binding. No bound context ⇒ no-op.
+        """
+        try:
+            ctx = self._store.current_activity_context()
+            if ctx is None:
+                return
+            span_context = span.get_span_context()
+            trace_id = getattr(span_context, "trace_id", None)
+            if isinstance(trace_id, int) and trace_id != 0:
+                if self._store.context_for_trace(trace_id) is None:
+                    self._store.register_trace(trace_id, ctx)
+        except Exception:  # correlation must never break user spans
+            logger.debug("OpenBoxSpanProcessor.on_start correlation failed", exc_info=True)
+
+    def on_end(self, span: Any) -> None:
+        """PASSIVE by contract — never evaluates, never blocks, never raises.
+
+        ``on_end`` fires after the operation completed; a verdict here could
+        not stop anything. Hard preflight blocking happens in the wrapper
+        call path before the real operation.
+        """
+        return None
+
+    def shutdown(self) -> None:
+        return None
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True

openbox_core/otel/trace_context.py

@@ -0,0 +1,71 @@
+"""Span-context extraction and hex-id formatting for wire payloads.
+
+Two representations, never confused:
+- INTERNAL: raw OTel integers (trace correlation keys — see context.py).
+- WIRE: lowercase hex strings — ``span_id`` 16 chars, ``trace_id`` 32 chars,
+  ``parent_span_id`` 16 chars. Raw integers must NEVER reach the wire.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "format_span_id",
+    "format_trace_id",
+    "extract_span_context",
+    "raw_trace_id",
+]
+
+
+def format_span_id(span_id: int) -> str:
+    """16-char lowercase hex."""
+    return format(span_id, "016x")
+
+
+def format_trace_id(trace_id: int) -> str:
+    """32-char lowercase hex."""
+    return format(trace_id, "032x")
+
+
+def _span_context_of(span: Any) -> Any:
+    if hasattr(span, "get_span_context"):
+        try:
+            return span.get_span_context()
+        except Exception:
+            return None
+    return getattr(span, "context", None)
+
+
+def extract_span_context(span: Any) -> tuple[str, str, str | None]:
+    """(span_id_hex16, trace_id_hex32, parent_span_id_hex16 | None).
+
+    Handles NonRecordingSpan, mocks, and missing attributes safely — degraded
+    ids become all-zero hex, never an exception.
+    """
+    span_context = _span_context_of(span)
+    try:
+        span_id_value = getattr(span_context, "span_id", None)
+        span_id = format_span_id(span_id_value) if isinstance(span_id_value, int) else "0" * 16
+    except (AttributeError, TypeError):
+        span_id = "0" * 16
+    try:
+        trace_id_value = getattr(span_context, "trace_id", None)
+        trace_id = format_trace_id(trace_id_value) if isinstance(trace_id_value, int) else "0" * 32
+    except (AttributeError, TypeError):
+        trace_id = "0" * 32
+
+    parent_span_id = None
+    parent = getattr(span, "parent", None)
+    parent_id_value = getattr(parent, "span_id", None) if parent is not None else None
+    if isinstance(parent_id_value, int):
+        parent_span_id = format_span_id(parent_id_value)
+
+    return span_id, trace_id, parent_span_id
+
+
+def raw_trace_id(span: Any) -> int | None:
+    """The raw integer trace id for context-store lookups (or None)."""
+    span_context = _span_context_of(span)
+    trace_id = getattr(span_context, "trace_id", None)
+    return trace_id if isinstance(trace_id, int) else None

openbox_core/runtime.py

@@ -0,0 +1,138 @@
+"""OpenBoxRuntime — owns config, adapter, gate, client, context store, and
+(from the instrumentation phase) the instrumentation manager.
+
+The runtime is the composition root for non-sandbox code:
+
+    config  = OpenBoxConfig.resolve(...)
+    runtime = OpenBoxRuntime(config, adapter=MyFrameworkAdapter())
+    runtime.install_instrumentation()
+    ...
+    runtime.close()
+
+Lifecycle helpers evaluate through the strict gate and delegate native
+enforcement (block/halt/approval) to the adapter callbacks.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .adapters.base import CoreAdapter, FrameworkAdapter
+from .client import EvaluationClient
+from .config import OpenBoxConfig
+from .context import ContextStore, default_context_store
+from .contracts.events import EventEnvelope
+from .contracts.results import EvaluationResult, Verdict
+from .errors import GuardrailsValidationError
+from .gate import GovernanceGate
+
+__all__ = ["OpenBoxRuntime"]
+
+
+def _default_payload_builder(config: OpenBoxConfig) -> Any:
+    """Wire the hook evaluate-body assembler (the single body-shape owner),
+    binding the runtime's privacy config into the gate's one-argument seam."""
+    from .wire.evaluate_payload import make_payload_builder
+
+    return make_payload_builder(config.privacy)
+
+
+class OpenBoxRuntime:
+    """Composition root wiring config → identity → client → gate → adapter."""
+
+    def __init__(
+        self,
+        config: OpenBoxConfig,
+        adapter: FrameworkAdapter | None = None,
+        *,
+        client: EvaluationClient | None = None,
+        context_store: ContextStore | None = None,
+        payload_builder: Any = None,
+    ):
+        self.config = config
+        self.adapter: FrameworkAdapter = adapter if adapter is not None else CoreAdapter()
+        self.context_store = context_store if context_store is not None else default_context_store()
+        self.client = client if client is not None else EvaluationClient(
+            config.api_url,
+            config.api_key,
+            timeout_seconds=config.timeout_seconds,
+            on_api_error=config.on_api_error,
+            identity=config.load_identity(),
+            sdk_version=config.sdk_version,
+            sdk_engine=config.sdk_engine,
+            sdk_language=config.sdk_language,
+        )
+        self.gate = GovernanceGate(
+            self.client,
+            config,
+            payload_builder=payload_builder if payload_builder is not None else _default_payload_builder(config),
+        )
+        self._instrumentation_manager: Any = None  # set by install_instrumentation
+
+    # ── Instrumentation lifecycle (real body lands with the manager) ──────
+
+    def install_instrumentation(self) -> None:
+        """Install generic instrumentation per InstrumentationConfig."""
+        if not self.config.instrumentation.enabled:
+            return
+        if self._instrumentation_manager is None:
+            from .instrumentation.manager import InstrumentationManager
+
+            self._instrumentation_manager = InstrumentationManager(self)
+        self._instrumentation_manager.install()
+
+    def uninstall_instrumentation(self) -> None:
+        """Uninstall instrumentation and restore originals (idempotent)."""
+        if self._instrumentation_manager is not None:
+            self._instrumentation_manager.uninstall()
+
+    # ── Lifecycle evaluation helpers ──────────────────────────────────────
+
+    def evaluate_lifecycle(self, event: EventEnvelope) -> EvaluationResult:
+        """Evaluate + enforce a lifecycle event (sync).
+
+        BLOCK/HALT delegate to ``adapter.raise_lifecycle_blocked``; a
+        guardrails failure raises before any approval flow. REQUIRE_APPROVAL
+        is returned to the caller on the sync path (approval flows are async —
+        use :meth:`aevaluate_lifecycle` to drive the adapter's approval flow).
+        """
+        result = self.gate.evaluate(event)
+        return self._enforce_lifecycle(result, drive_approval=False)
+
+    async def aevaluate_lifecycle(self, event: EventEnvelope) -> EvaluationResult:
+        """Async evaluate + enforce, including the adapter approval flow."""
+        result = await self.gate.aevaluate(event)
+        if result.verdict.requires_approval():
+            self._check_guardrails(result)
+            await self.adapter.handle_approval(result)
+            return result
+        return self._enforce_lifecycle(result, drive_approval=False)
+
+    def _enforce_lifecycle(self, result: EvaluationResult, *, drive_approval: bool) -> EvaluationResult:
+        if result.verdict.should_stop():
+            if result.verdict is Verdict.HALT:
+                self.context_store.request_halt()
+            self.adapter.raise_lifecycle_blocked(result)
+        self._check_guardrails(result)
+        return result
+
+    @staticmethod
+    def _check_guardrails(result: EvaluationResult) -> None:
+        # Guardrails failure outranks approval so it is never swallowed by HITL.
+        if result.guardrails and not result.guardrails.validation_passed:
+            reasons = result.guardrails.get_reason_strings()
+            raise GuardrailsValidationError(reasons or ["Guardrails validation failed"])
+
+    # ── Shutdown ──────────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Uninstall instrumentation, clear correlation state, close transports."""
+        self.uninstall_instrumentation()
+        self.context_store.clear()
+        self.client.close()
+
+    async def aclose(self) -> None:
+        """Async :meth:`close` (also closes the async transport)."""
+        self.uninstall_instrumentation()
+        self.context_store.clear()
+        await self.client.aclose()

openbox_core/sdk_version.py

@@ -0,0 +1,79 @@
+"""SDK identifier formatting for OpenBox request headers.
+
+The wire value is intentionally framework-branded rather than just a package
+version so Core can distinguish SDK families:
+
+    openbox-{engine}-{language}-v{version}
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = [
+    "DEFAULT_SDK_ENGINE",
+    "DEFAULT_SDK_LANGUAGE",
+    "SDK_IDENTIFIER_PATTERN",
+    "build_sdk_identifier",
+    "normalize_sdk_version",
+]
+
+DEFAULT_SDK_ENGINE = "base"
+DEFAULT_SDK_LANGUAGE = "python"
+
+_SLUG_PART_RE = re.compile(r"[^a-z0-9]+")
+_VERSION_RE = re.compile(r"^\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?$")
+
+SDK_IDENTIFIER_PATTERN = re.compile(
+    r"^openbox-[a-z0-9]+(?:-[a-z0-9]+)*-[a-z0-9]+-v"
+    r"\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?$"
+)
+
+
+def _slug(value: str, field_name: str) -> str:
+    text = str(value).strip().lower()
+    slug = _SLUG_PART_RE.sub("-", text).strip("-")
+    if not slug:
+        raise ValueError(f"{field_name} must not be empty")
+    return slug
+
+
+def normalize_sdk_version(version: str) -> str:
+    """Return a canonical ``v``-prefixed SDK version component."""
+
+    raw = str(version).strip()
+    if raw.startswith(("v", "V")):
+        raw = raw[1:]
+    if not _VERSION_RE.fullmatch(raw):
+        raise ValueError(
+            "sdk version must look like '1.1' or '1.2.3' "
+            f"(optionally with a suffix), got {version!r}"
+        )
+    return f"v{raw}"
+
+
+def build_sdk_identifier(
+    *,
+    engine: str = DEFAULT_SDK_ENGINE,
+    language: str = DEFAULT_SDK_LANGUAGE,
+    version: str | None = None,
+) -> str:
+    """Build ``openbox-{engine}-{language}-v{version}``.
+
+    ``version`` may be a raw package version (``1.2.3``), a ``v``-prefixed
+    version (``v1.2.3``), or an already formatted OpenBox SDK identifier.
+    """
+
+    if version is None:
+        from . import __version__ as version
+
+    raw = str(version).strip()
+    if raw.startswith("openbox-"):
+        if not SDK_IDENTIFIER_PATTERN.fullmatch(raw):
+            raise ValueError(f"invalid OpenBox SDK identifier: {version!r}")
+        return raw
+
+    return (
+        f"openbox-{_slug(engine, 'sdk engine')}-"
+        f"{_slug(language, 'sdk language')}-{normalize_sdk_version(raw)}"
+    )