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

openbox_core/contracts/otel_spans.py

@@ -0,0 +1,325 @@
+"""Span contracts — Stage, HookType, and flat OpenBox hook spans.
+
+OTel spans are the INTERNAL source of truth (there are no fixed
+HttpSpan/DbSpan/... dataclasses), but ``from_otel_span`` returns the flat Core
+``SpanData`` shape immediately. There is no SDK-visible
+``{"otel": ..., "openbox": ...}`` span envelope.
+
+Pure module: span access is DUCK-TYPED (plain getattr) so importing this never
+pulls in opentelemetry — the import-safety harness holds.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import Enum
+from typing import Any
+
+from ..otel.trace_context import format_span_id, format_trace_id
+
+__all__ = [
+    "Stage",
+    "HookType",
+    "serialize_readable_span",
+    "from_otel_span",
+    "OpenBoxSpanAdapter",
+]
+
+
+class Stage(str, Enum):
+    """Hook evaluation stage."""
+
+    STARTED = "started"
+    COMPLETED = "completed"
+
+
+class HookType(str, Enum):
+    """Operation category of a hook span (Core root field ``hook_type``)."""
+
+    HTTP_REQUEST = "http_request"
+    DB_QUERY = "db_query"
+    FILE_OPERATION = "file_operation"
+    FUNCTION_CALL = "function_call"
+    LLM_CALL = "llm_call"  # reserved; disabled until provider hooks are implemented
+
+
+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 _enum_name(value: Any) -> str | None:
+    """'SpanKind.CLIENT' -> 'CLIENT'; plain strings pass through."""
+    if value is None:
+        return None
+    name = getattr(value, "name", None)
+    if isinstance(name, str):
+        return name
+    text = str(value)
+    return text.split(".")[-1] if text else None
+
+
+def _attributes_of(obj: Any) -> dict[str, Any]:
+    attributes = getattr(obj, "attributes", None)
+    if attributes is None:
+        return {}
+    try:
+        return dict(attributes)
+    except Exception:
+        return {}
+
+
+# Best-effort semantic attribute mapping: wire field -> OTel keys (new, legacy).
+_SEMANTIC_ATTR_MAP: dict[str, tuple[str, ...]] = {
+    "http_url": ("url.full", "http.url"),
+    "http_method": ("http.request.method", "http.method"),
+    "http_status_code": ("http.response.status_code", "http.status_code"),
+    "db_system": ("db.system.name", "db.system"),
+    "db_name": ("db.namespace", "db.name"),
+    "db_operation": ("db.operation.name", "db.operation"),
+    "db_statement": ("db.query.text", "db.statement"),
+    "server_address": ("server.address", "net.peer.name"),
+    "server_port": ("server.port", "net.peer.port"),
+    "file_path": ("file.path",),
+    "file_mode": ("file.mode",),
+    "file_operation": ("file.operation",),
+    "function": ("code.function.name", "code.function"),
+    "module": ("code.namespace", "code.module"),
+}
+
+_DEFAULT_KIND_BY_HOOK: dict[str, str] = {
+    "http_request": "CLIENT",
+    "db_query": "CLIENT",
+    "file_operation": "INTERNAL",
+    "function_call": "INTERNAL",
+    "llm_call": "CLIENT",
+}
+
+# Family-specific root fields that must exist, null-valued when unavailable, so
+# hook spans have the same flat key contract in memory and on the wire.
+_ROOT_FIELDS_BY_HOOK_TYPE: dict[str, tuple[str, ...]] = {
+    "http_request": (
+        "http_method",
+        "http_url",
+        "http_status_code",
+        "request_headers",
+        "response_headers",
+        "request_body",
+        "response_body",
+    ),
+    "db_query": (
+        "db_system",
+        "db_name",
+        "db_operation",
+        "db_statement",
+        "server_address",
+        "server_port",
+        "rowcount",
+    ),
+    "file_operation": (
+        "file_path",
+        "file_mode",
+        "file_operation",
+        "bytes_read",
+        "bytes_written",
+    ),
+    "function_call": ("function", "module", "args", "result"),
+}
+
+
+def _attr(attributes: Mapping[str, Any], keys: tuple[str, ...]) -> Any:
+    for key in keys:
+        value = attributes.get(key)
+        if value is not None:
+            return value
+    return None
+
+
+def serialize_readable_span(span: Any) -> dict[str, Any]:
+    """Preserve the OTel surface the SDK exposes, via duck-typed access.
+
+    Ids stay RAW INTEGERS here (internal representation; the wire projection
+    formats hex strings). Missing pieces degrade to None/empty — a span is
+    never rejected during serialization.
+    """
+    span_context = _span_context_of(span)
+    context_part = None
+    if span_context is not None:
+        span_id = getattr(span_context, "span_id", None)
+        trace_id = getattr(span_context, "trace_id", None)
+        context_part = {
+            "span_id": span_id if isinstance(span_id, int) else None,
+            "trace_id": trace_id if isinstance(trace_id, int) else None,
+        }
+
+    parent = getattr(span, "parent", None)
+    parent_part = None
+    if parent is not None:
+        parent_span_id = getattr(parent, "span_id", None)
+        if isinstance(parent_span_id, int):
+            parent_part = {"span_id": parent_span_id}
+
+    status = getattr(span, "status", None)
+    status_part = None
+    if status is not None:
+        status_part = {
+            "code": _enum_name(getattr(status, "status_code", None)) or "UNSET",
+            "description": getattr(status, "description", None),
+        }
+
+    events = []
+    for event in getattr(span, "events", None) or ():
+        events.append(
+            {
+                "name": getattr(event, "name", None),
+                "timestamp": getattr(event, "timestamp", None),
+                "attributes": _attributes_of(event),
+            }
+        )
+
+    links = []
+    for link in getattr(span, "links", None) or ():
+        link_context = getattr(link, "context", None)
+        links.append(
+            {
+                "context": {
+                    "span_id": getattr(link_context, "span_id", None),
+                    "trace_id": getattr(link_context, "trace_id", None),
+                },
+                "attributes": _attributes_of(link),
+            }
+        )
+
+    resource = getattr(span, "resource", None)
+    resource_part = _attributes_of(resource) if resource is not None else None
+
+    scope = getattr(span, "instrumentation_scope", None)
+    scope_part = None
+    if scope is not None:
+        scope_part = {
+            "name": getattr(scope, "name", None),
+            "version": getattr(scope, "version", None),
+        }
+
+    start_time = getattr(span, "start_time", None)
+    end_time = getattr(span, "end_time", None)
+    return {
+        "context": context_part,
+        "parent": parent_part,
+        "name": getattr(span, "name", None),
+        "kind": _enum_name(getattr(span, "kind", None)),
+        "start_time": start_time if isinstance(start_time, int) else None,
+        "end_time": end_time if isinstance(end_time, int) else None,
+        "attributes": _attributes_of(span),
+        "events": events,
+        "links": links,
+        "status": status_part,
+        "resource": resource_part,
+        "instrumentation_scope": scope_part,
+    }
+
+
+def from_otel_span(
+    span: Any,
+    *,
+    stage: Stage | str,
+    hook_type: HookType | str | None = None,
+    activity_context: Any = None,
+    fields: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build one flat Core ``SpanData`` dict from an OTel span.
+
+    Args:
+        span: OTel span (Span/ReadableSpan/NonRecordingSpan — duck-typed).
+        stage: started/completed.
+        hook_type: Operation category (None for non-hook telemetry spans).
+        activity_context: Accepted for backward-compatible call sites; context is
+            stored on the surrounding event, not inside the span.
+        fields: Wrapper-supplied Core root fields (request_body, rowcount,
+            args, ...) merged at the span root. These carry data OTel attributes
+            don't (bodies, results).
+    """
+    _ = activity_context
+    stage_value = stage.value if isinstance(stage, Stage) else str(stage)
+    hook_value = hook_type.value if isinstance(hook_type, HookType) else hook_type
+    otel = serialize_readable_span(span)
+    context = otel.get("context") or {}
+    parent = otel.get("parent") or {}
+    span_id_int = context.get("span_id")
+    trace_id_int = context.get("trace_id")
+    parent_id_int = parent.get("span_id")
+    attributes = dict(otel.get("attributes") or {})
+
+    start_time = otel.get("start_time")
+    end_time = otel.get("end_time")
+    if stage_value == Stage.STARTED.value:
+        end_time = None
+        duration_ns = None
+    else:
+        duration_ns = (
+            end_time - start_time
+            if isinstance(end_time, int) and isinstance(start_time, int)
+            else None
+        )
+
+    wire: dict[str, Any] = {
+        "span_id": format_span_id(span_id_int) if isinstance(span_id_int, int) else "0" * 16,
+        "trace_id": format_trace_id(trace_id_int) if isinstance(trace_id_int, int) else "0" * 32,
+        "parent_span_id": format_span_id(parent_id_int) if isinstance(parent_id_int, int) else None,
+        "name": otel.get("name") or (hook_value or "span"),
+        "kind": otel.get("kind") or _DEFAULT_KIND_BY_HOOK.get(hook_value or "", "INTERNAL"),
+        "stage": stage_value,
+        "start_time": start_time,
+        "end_time": end_time,
+        "duration_ns": duration_ns,
+        "attributes": attributes,
+        "status": otel.get("status") or {"code": "UNSET", "description": None},
+        "events": otel.get("events") or [],
+        "error": None,
+    }
+    if hook_value:
+        wire["hook_type"] = hook_value
+
+    for wire_field, attr_keys in _SEMANTIC_ATTR_MAP.items():
+        value = _attr(attributes, attr_keys)
+        if value is not None:
+            wire[wire_field] = value
+
+    for field_name, value in dict(fields or {}).items():
+        if value is not None:
+            wire[field_name] = value
+
+    for field_name in _ROOT_FIELDS_BY_HOOK_TYPE.get(hook_value or "", ()):
+        wire.setdefault(field_name, None)
+
+    if stage_value != Stage.STARTED.value and wire.get("end_time") is None:
+        measured = wire.get("duration_ns")
+        if isinstance(start_time, int) and isinstance(measured, int):
+            wire["end_time"] = start_time + measured
+
+    return wire
+
+
+class OpenBoxSpanAdapter:
+    """Adapter object form of :func:`from_otel_span` (protocol-compatible)."""
+
+    @staticmethod
+    def from_otel_span(
+        span: Any,
+        *,
+        stage: Stage | str,
+        hook_type: HookType | str | None = None,
+        activity_context: Any = None,
+        fields: Mapping[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return from_otel_span(
+            span,
+            stage=stage,
+            hook_type=hook_type,
+            activity_context=activity_context,
+            fields=fields,
+        )

openbox_core/contracts/results.py

@@ -0,0 +1,287 @@
+"""Result contracts — Verdict, GuardrailsResult, EvaluationResult, ApprovalResult.
+
+Pure, import-safe module: no network, crypto, OTel, logging, wall-clock, or
+random. Strict dataclass constructors AND loose ``from_dict()`` parsers are
+both public so callers can work with typed values or raw backend dicts.
+
+Parsing preserves ``raw`` so nothing the backend sent is ever lost, and stays
+tolerant of unknown keys (field-shape drift from Core must not crash SDKs).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+__all__ = [
+    "Verdict",
+    "GuardrailsResult",
+    "EvaluationResult",
+    "ApprovalResult",
+]
+
+
+class Verdict(str, Enum):
+    """5-tier graduated response. Priority: HALT > BLOCK > REQUIRE_APPROVAL > CONSTRAIN > ALLOW."""
+
+    ALLOW = "allow"
+    CONSTRAIN = "constrain"
+    REQUIRE_APPROVAL = "require_approval"
+    BLOCK = "block"
+    HALT = "halt"
+
+    @classmethod
+    def from_string(cls, value: str | None) -> Verdict:
+        """Parse with v1.0 compat: 'continue'→ALLOW, 'stop'→HALT, 'require-approval'→REQUIRE_APPROVAL."""
+        if value is None:
+            return cls.ALLOW
+        normalized = value.lower().replace("-", "_")
+        if normalized == "continue":
+            return cls.ALLOW
+        if normalized == "stop":
+            return cls.HALT
+        if normalized in ("require_approval", "request_approval"):
+            return cls.REQUIRE_APPROVAL
+        try:
+            return cls(normalized)
+        except ValueError:
+            return cls.ALLOW
+
+    @property
+    def priority(self) -> int:
+        """Priority for aggregation: HALT=5, BLOCK=4, REQUIRE_APPROVAL=3, CONSTRAIN=2, ALLOW=1."""
+        return {
+            Verdict.ALLOW: 1,
+            Verdict.CONSTRAIN: 2,
+            Verdict.REQUIRE_APPROVAL: 3,
+            Verdict.BLOCK: 4,
+            Verdict.HALT: 5,
+        }[self]
+
+    @classmethod
+    def highest_priority(cls, verdicts: list[Verdict]) -> Verdict:
+        """Get highest priority verdict from list. Returns ALLOW if empty."""
+        return max(verdicts, key=lambda v: v.priority) if verdicts else cls.ALLOW
+
+    def should_stop(self) -> bool:
+        """True if BLOCK or HALT."""
+        return self in (Verdict.BLOCK, Verdict.HALT)
+
+    def requires_approval(self) -> bool:
+        """True if REQUIRE_APPROVAL."""
+        return self == Verdict.REQUIRE_APPROVAL
+
+
+@dataclass
+class GuardrailsResult:
+    """Guardrails check result from the governance API.
+
+    Contains redacted input/output that should replace the original activity
+    data, plus validation results that can block execution.
+    """
+
+    redacted_input: Any = None  # Redacted activity_input/activity_output (JSON-decoded)
+    input_type: str = ""  # "activity_input" or "activity_output"
+    raw_logs: dict[str, Any] | None = None  # Raw logs from guardrails evaluation
+    validation_passed: bool = True  # If False, execution should be stopped
+    reasons: list[dict[str, str]] = field(default_factory=list)  # [{type, field, reason}]
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> GuardrailsResult:
+        return cls(
+            redacted_input=data.get("redacted_input"),
+            input_type=data.get("input_type", ""),
+            raw_logs=data.get("raw_logs"),
+            validation_passed=data.get("validation_passed", True),
+            reasons=data.get("reasons") or [],
+        )
+
+    def get_reason_strings(self) -> list[str]:
+        """Extract just the 'reason' field from each reason object."""
+        return [r.get("reason", "") for r in self.reasons if r.get("reason")]
+
+
+@dataclass
+class EvaluationResult:
+    """Response from a governance evaluation.
+
+    ``guardrails`` and ``guardrails_result`` are the SAME object —
+    ``guardrails_result`` is a read-only compatibility alias; there is no way
+    for the two to diverge.
+
+    Optional transport/diagnostic fields default to falsy values so strict
+    construction stays terse.
+    """
+
+    verdict: Verdict
+    reason: str | None = None
+    policy_id: str | None = None
+    risk_score: float = 0.0
+    metadata: dict[str, Any] | None = None
+    governance_event_id: str | None = None
+    guardrails: GuardrailsResult | None = None
+    approval_id: str | None = None
+    approval_expiration_time: str | None = None
+    trust_tier: str | None = None
+    alignment_score: float | None = None
+    behavioral_violations: list[str] | None = None
+    constraints: list[dict[str, Any]] | None = None
+    fallback_used: bool = False  # True when fail-open produced this result
+    diagnostics: list[Any] = field(default_factory=list)
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def guardrails_result(self) -> GuardrailsResult | None:
+        """Alias of ``guardrails`` (same object)."""
+        return self.guardrails
+
+    @property
+    def action(self) -> str:
+        """Backward compat: return the v1.0 action string derived from verdict."""
+        if self.verdict == Verdict.ALLOW:
+            return "continue"
+        if self.verdict == Verdict.HALT:
+            return "stop"
+        if self.verdict == Verdict.REQUIRE_APPROVAL:
+            return "require-approval"
+        return self.verdict.value
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> EvaluationResult:
+        """Parse a governance response dict (v1.0 and v1.1 compatible).
+
+        Verdict-first with v1.0 ``action`` fallback — the approval
+        *action-precedence* change applies to :class:`ApprovalResult` only.
+        Unknown keys are preserved in ``raw``, never an error.
+        """
+        guardrails = None
+        if data.get("guardrails_result"):
+            guardrails = GuardrailsResult.from_dict(data["guardrails_result"])
+        elif data.get("guardrails"):
+            guardrails = GuardrailsResult.from_dict(data["guardrails"])
+
+        verdict = Verdict.from_string(data.get("verdict") or data.get("action", "continue"))
+
+        return cls(
+            verdict=verdict,
+            reason=data.get("reason"),
+            policy_id=data.get("policy_id"),
+            risk_score=data.get("risk_score", 0.0),
+            metadata=data.get("metadata"),
+            governance_event_id=data.get("governance_event_id"),
+            guardrails=guardrails,
+            approval_id=data.get("approval_id"),
+            approval_expiration_time=data.get("approval_expiration_time"),
+            trust_tier=data.get("trust_tier"),
+            alignment_score=data.get("alignment_score"),
+            behavioral_violations=data.get("behavioral_violations"),
+            constraints=data.get("constraints"),
+            fallback_used=bool(data.get("fallback_used", False)),
+            diagnostics=data.get("diagnostics") or [],
+            raw=dict(data),
+        )
+
+    @classmethod
+    def fallback_allow(cls, reason: str) -> EvaluationResult:
+        """Allow-shaped result for fail-open network-error paths.
+
+        ``fallback_used=True`` marks it as a fallback so callers can tell a
+        policy ALLOW from an unreachable-Core ALLOW. A network error must never
+        silently flip BLOCK→ALLOW without this marker.
+        """
+        return cls(verdict=Verdict.ALLOW, reason=reason, fallback_used=True)
+
+
+@dataclass
+class ApprovalResult:
+    """Normalized HITL approval-poll response.
+
+    Decision-source precedence: **``action`` wins over ``verdict``** when both
+    are present.
+
+    When NEITHER field is present, ``verdict`` is ``None`` (pending-unknown) —
+    never auto-ALLOW. Expired approvals block unless the backend explicitly
+    returned an allow-shaped verdict/action.
+    """
+
+    verdict: Verdict | None = None
+    action: str | None = None
+    reason: str | None = None
+    approval_id: str | None = None
+    approval_expiration_time: str | None = None
+    expired: bool = False
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    # Known decision vocabulary for approvals (current values + accepted aliases).
+    # Anything OUTSIDE this set parses to None (pending) — the evaluate-path
+    # leniency of Verdict.from_string (unknown -> ALLOW) is too loose at the
+    # human-approval trust boundary and is not used here.
+    _DECISION_VOCABULARY = frozenset(
+        {
+            "allow",
+            "constrain",
+            "require_approval",
+            "request_approval",
+            "block",
+            "halt",
+            "continue",
+            "stop",
+        }
+    )
+
+    @staticmethod
+    def _parse_decision(value: Any) -> Verdict | None:
+        """Strict, fail-safe decision parsing: empty/unknown -> None (pending)."""
+        if not isinstance(value, str) or not value.strip():
+            return None
+        normalized = value.strip().lower().replace("-", "_")
+        if normalized not in ApprovalResult._DECISION_VOCABULARY:
+            return None
+        return Verdict.from_string(normalized)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ApprovalResult:
+        action = data.get("action")
+        # Empty/whitespace action is absent; it must not shadow ``verdict``.
+        if not isinstance(action, str) or not action.strip():
+            action = None
+        verdict_source = action if action is not None else data.get("verdict")
+        verdict = cls._parse_decision(verdict_source)
+        return cls(
+            verdict=verdict,
+            action=action,
+            reason=data.get("reason"),
+            # Normalize ``id`` → ``approval_id``.
+            approval_id=data.get("approval_id") or data.get("id"),
+            approval_expiration_time=data.get("approval_expiration_time"),
+            expired=bool(data.get("expired", False)),
+            raw=dict(data),
+        )
+
+    @property
+    def allow_shaped(self) -> bool:
+        """True when the backend explicitly returned an allow verdict/action."""
+        return self.verdict == Verdict.ALLOW
+
+    def is_blocking(self) -> bool:
+        """True when this response must stop the operation.
+
+        Expired approvals are blocking unless explicitly allow-shaped; an
+        explicit BLOCK/HALT verdict is blocking regardless of expiry.
+        """
+        if self.expired:
+            return not self.allow_shaped
+        return self.verdict is not None and self.verdict.should_stop()
+
+    def is_pending(self) -> bool:
+        """True while the approval decision is still outstanding.
+
+        Absent verdict/action (``None``) is pending — never auto-ALLOW.
+        REQUIRE_APPROVAL and CONSTRAIN keep polling.
+        """
+        if self.expired:
+            return False
+        if self.verdict is None:
+            return True
+        return self.verdict in (Verdict.REQUIRE_APPROVAL, Verdict.CONSTRAIN)