openbox-sdk-python 1.0.0__tar.gz → 1.1.0__tar.gz

openbox_sdk_python-1.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-07-21
+
+### Added
+- `RetryPlan` and `RetryDirective` dataclasses in `openbox_core.contracts.results`.
+- Optional `retry_plan` directive parsing on both `EvaluationResult` and `ApprovalResult`.
+  A `_MISSING` sentinel keeps a present `new_input: null` distinct from an absent field; falsy
+  values (`null`, `""`, `0`, `[]`, `{}`) are preserved; a boolean `new_input` is rejected; and every
+  number (recursively) must be finite and, if integral, a JS-safe integer (`|n| <= 2^53 - 1`).
+- `handle_retryable_block(result)` — an opt-in, pure inspector that returns a `RetryDirective` only
+  for a `BLOCK` verdict carrying a valid plan. Returns `None` for a plain BLOCK, every non-BLOCK
+  verdict (including HALT), a pending verdict, and an expired `ApprovalResult`.
+
+### Notes
+- Default enforcement is unchanged: a `BLOCK` verdict still raises `GovernanceBlockedError`. The new
+  helper is opt-in and never triggers an automatic retry; malformed or ineligible plans are treated
+  as absent (never fail open).

{openbox_sdk_python-1.0.0 → openbox_sdk_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbox-sdk-python
-Version: 1.0.0
+Version: 1.1.0
 Summary: OpenBox base SDK - governance contracts, strict gate, identity/signing, evaluate client, context runtime, OTel span wire serialization, and generic instrumentation shared by every OpenBox framework SDK
 Author-email: OpenBox Team <tino@openbox.ai>
 License-Expression: MIT
@@ -15,7 +15,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: System :: Monitoring
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: cryptography<47,>=43
+Requires-Dist: cryptography<50,>=48.0.1
 Requires-Dist: httpx<1,>=0.28.0
 Requires-Dist: opentelemetry-api<1.40.0,>=1.38.0
 Requires-Dist: opentelemetry-sdk<1.40.0,>=1.38.0

{openbox_sdk_python-1.0.0 → openbox_sdk_python-1.1.0}/openbox_core/__init__.py

@@ -37,7 +37,7 @@ from .errors import (
 # governance; eagerly it can deadlock package init as a circular import, and
 # lazily it can recurse unboundedly when a per-request header builder resolves
 # the version. Keep in sync with pyproject.toml on release.
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "__version__",

{openbox_sdk_python-1.0.0 → openbox_sdk_python-1.1.0}/openbox_core/adapters/base.py

@@ -8,7 +8,8 @@ core error types directly.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 from ..contracts.results import EvaluationResult
 from ..errors import (
@@ -24,7 +25,7 @@ if TYPE_CHECKING:
     from ..approvals import ApprovalPoller
     from ..contracts.context import ActivityContext
 
-__all__ = ["FrameworkAdapter", "CoreAdapter"]
+__all__ = ["FrameworkAdapter", "CoreAdapter", "adapter_accepts_context"]
 
 
 @runtime_checkable
@@ -33,16 +34,27 @@ class FrameworkAdapter(Protocol):
 
     name: str
 
-    async def handle_approval(self, result: EvaluationResult) -> None:
+    async def handle_approval(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
         """Drive the framework's approval flow for REQUIRE_APPROVAL.
 
         Return normally when approved; raise the framework's native rejection/
         expiry error otherwise. Called BEFORE the real operation runs.
 
-        Adapters may ALSO define a plain-sync ``handle_approval_sync(result)``
-        (not part of the required protocol): when present, sync hook paths
-        delegate to it instead of driving the core inline poller. Frameworks
-        with retry-based HITL can raise their native pending error there.
+        ``context`` carries the workflow/run/activity IDs the approval poll
+        needs: Core's evaluate response does NOT echo them, so they cannot be
+        recovered from ``result.raw``. The runtime passes the originating
+        ``ActivityContext`` (lifecycle events build one from the event).
+        Optional — an adapter defined as ``handle_approval(self, result)`` still
+        conforms; the runtime passes ``context`` only when the signature accepts
+        it (see :func:`adapter_accepts_context`).
+
+        Adapters may ALSO define a plain-sync ``handle_approval_sync(result,
+        context)`` (not part of the required protocol): when present, sync hook
+        paths delegate to it instead of driving the core inline poller.
+        Frameworks with retry-based HITL can raise their native pending error
+        there.
         """
         ...
 
@@ -82,17 +94,16 @@ class CoreAdapter:
     def __init__(self, approval_poller: ApprovalPoller | None = None):
         self._poller = approval_poller
 
-    async def handle_approval(self, result: EvaluationResult) -> None:
+    async def handle_approval(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
         if self._poller is None or not result.approval_id:
             raise ApprovalRejectedError(
                 "REQUIRE_APPROVAL verdict but no approval flow is configured — "
                 "failing safe (operation not run)"
             )
-        approval = await self._poller.await_decision(
-            result.raw.get("workflow_id", ""),
-            result.raw.get("run_id", ""),
-            result.raw.get("activity_id", ""),
-        )
+        workflow_id, run_id, activity_id = _approval_poll_ids(result, context)
+        approval = await self._poller.await_decision(workflow_id, run_id, activity_id)
         if approval.allow_shaped:
             return
         if approval.expired:
@@ -121,3 +132,50 @@ class CoreAdapter:
         raise GovernanceBlockedError(
             result.verdict, result.reason or "Blocked by governance policy"
         )
+
+
+def _approval_poll_ids(
+    result: EvaluationResult, context: ActivityContext | None
+) -> tuple[str, str, str]:
+    """Resolve the (workflow_id, run_id, activity_id) the approval poll sends.
+
+    Core's evaluate response does not echo them, so the originating
+    ``ActivityContext`` is authoritative; ``result.raw`` is only a fallback for
+    a caller that predates the ``context`` argument (it is empty in real Core
+    traffic).
+    """
+    raw = result.raw
+    if context is None:
+        return (
+            raw.get("workflow_id", ""),
+            raw.get("run_id", ""),
+            raw.get("activity_id", ""),
+        )
+    return (
+        context.workflow_id or raw.get("workflow_id", ""),
+        context.run_id or raw.get("run_id", ""),
+        context.activity_id or raw.get("activity_id", ""),
+    )
+
+
+def adapter_accepts_context(callback: Callable[..., Any] | None) -> bool:
+    """True when an adapter callback accepts a ``context`` argument (an explicit
+    parameter or ``**kwargs``).
+
+    Checked by signature so a genuine ``TypeError`` raised inside the callback
+    body is never mistaken for an arity mismatch and silently dropped. Lets the
+    runtime stay backward-compatible with adapters written against the older
+    ``handle_approval(self, result)`` / ``on_completed_hook_result(self,
+    result)`` signatures.
+    """
+    import inspect
+
+    if callback is None:
+        return False
+    try:
+        params = inspect.signature(callback).parameters
+    except (TypeError, ValueError):
+        return False
+    return "context" in params or any(
+        p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()
+    )

{openbox_sdk_python-1.0.0 → openbox_sdk_python-1.1.0}/openbox_core/conformance/hook_preflight.py

@@ -39,10 +39,14 @@ class RecordingHookAdapter:
         self.completed_results: list[EvaluationResult] = []
         self.completed_contexts: list[ActivityContext | None] = []
         self.approvals: list[EvaluationResult] = []
+        self.approval_contexts: list[ActivityContext | None] = []
         self.approve_next = True
 
-    async def handle_approval(self, result: EvaluationResult) -> None:
+    async def handle_approval(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
         self.approvals.append(result)
+        self.approval_contexts.append(context)
         if not self.approve_next:
             raise ApprovalRejectedError("rejected by conformance adapter")
 

{openbox_sdk_python-1.0.0 → openbox_sdk_python-1.1.0}/openbox_core/contracts/results.py

@@ -10,6 +10,7 @@ tolerant of unknown keys (field-shape drift from Core must not crash SDKs).
 
 from __future__ import annotations
 
+import math
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
@@ -19,6 +20,9 @@ __all__ = [
     "GuardrailsResult",
     "EvaluationResult",
     "ApprovalResult",
+    "RetryPlan",
+    "RetryDirective",
+    "handle_retryable_block",
 ]
 
 
@@ -102,6 +106,87 @@ class GuardrailsResult:
         return [r.get("reason", "") for r in self.reasons if r.get("reason")]
 
 
+# Sentinel distinguishing an absent ``retry_plan`` field from a present JSON ``null``.
+# ``dict.get("retry_plan")`` would collapse both to None; membership via this sentinel does not.
+_MISSING = object()
+
+# JS Number.MAX_SAFE_INTEGER. Integral numbers must fit within +/- this bound so ``new_input`` can
+# never silently change across FE, backend, Core, and Python (json.loads yields arbitrary-precision
+# ``int`` and ``float('inf')``, both broader than JS).
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def _numbers_are_safe(value: Any) -> bool:
+    """Every number (recursively) must be finite and, if integral, within the JS-safe range.
+
+    ``bool`` is a subclass of ``int`` but is not a number here; a nested bool is a plain leaf
+    (top-level ``new_input`` booleans are rejected separately by :func:`_parse_retry_plan`).
+    """
+    if isinstance(value, bool):
+        return True
+    if isinstance(value, int):
+        return abs(value) <= _MAX_SAFE_INTEGER
+    if isinstance(value, float):
+        if math.isinf(value) or math.isnan(value):
+            return False
+        if value.is_integer():
+            return abs(value) <= _MAX_SAFE_INTEGER
+        return True
+    if isinstance(value, dict):
+        return all(_numbers_are_safe(v) for v in value.values())
+    if isinstance(value, (list, tuple)):
+        return all(_numbers_are_safe(v) for v in value)
+    return True
+
+
+@dataclass
+class RetryPlan:
+    """Optional remediation hint carried on a BLOCK verdict (policy-produced or admin-retry).
+
+    ``new_input`` may be null | str | number | list | dict (boolean rejected). A present
+    ``new_input`` of ``None`` is a valid plan (retry with the original input) and is distinct
+    from an absent ``retry_plan`` field.
+    """
+
+    new_input: Any = None
+
+
+@dataclass
+class RetryDirective:
+    """Caller-facing view of a retryable BLOCK, surfaced only via :func:`handle_retryable_block`.
+
+    It is a remediation hint, not proof that a retry was evaluated or executed.
+    """
+
+    new_input: Any = None
+    governance_event_id: str | None = None
+    reason: str | None = None
+
+
+def _parse_retry_plan(container: dict[str, Any]) -> RetryPlan | None:
+    """Parse an optional ``retry_plan`` from a result dict against the frozen wire contract.
+
+    Returns a plan only when ``retry_plan`` is present, is a dict whose ONLY key is ``new_input``,
+    and ``new_input`` is null/str/number/list/dict (boolean rejected) with every number finite and,
+    if integral, within the JS-safe integer range. An absent field, a JSON ``null`` field, or any
+    contract violation yields ``None`` (treated as absent — never an error). A present
+    ``new_input`` of ``None`` is preserved as a valid plan.
+    """
+    plan = container.get("retry_plan", _MISSING)
+    if plan is _MISSING or not isinstance(plan, dict):
+        return None
+    # Exactly the single key new_input (also guarantees new_input is present, not merely null).
+    if set(plan.keys()) != {"new_input"}:
+        return None
+    new_input = plan["new_input"]
+    # bool is a subclass of int — reject a boolean new_input BEFORE the number check.
+    if isinstance(new_input, bool):
+        return None
+    if not _numbers_are_safe(new_input):
+        return None
+    return RetryPlan(new_input=new_input)
+
+
 @dataclass
 class EvaluationResult:
     """Response from a governance evaluation.
@@ -130,6 +215,7 @@ class EvaluationResult:
     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)
+    retry_plan: RetryPlan | None = None  # Optional BLOCK remediation hint; None = absent
 
     @property
     def guardrails_result(self) -> GuardrailsResult | None:
@@ -180,6 +266,7 @@ class EvaluationResult:
             fallback_used=bool(data.get("fallback_used", False)),
             diagnostics=data.get("diagnostics") or [],
             raw=dict(data),
+            retry_plan=_parse_retry_plan(data),
         )
 
     @classmethod
@@ -212,6 +299,7 @@ class ApprovalResult:
     approval_expiration_time: str | None = None
     expired: bool = False
     raw: dict[str, Any] = field(default_factory=dict)
+    retry_plan: RetryPlan | None = None  # Present only on an admin-retry BLOCK
 
     # Known decision vocabulary for approvals (current values + accepted aliases).
     # Anything OUTSIDE this set parses to None (pending) — the evaluate-path
@@ -257,6 +345,7 @@ class ApprovalResult:
             approval_expiration_time=data.get("approval_expiration_time"),
             expired=bool(data.get("expired", False)),
             raw=dict(data),
+            retry_plan=_parse_retry_plan(data),
         )
 
     @property
@@ -285,3 +374,44 @@ class ApprovalResult:
         if self.verdict is None:
             return True
         return self.verdict in (Verdict.REQUIRE_APPROVAL, Verdict.CONSTRAIN)
+
+
+def handle_retryable_block(
+    result: EvaluationResult | ApprovalResult,
+) -> RetryDirective | None:
+    """Opt-in, pure inspector: surface a retry directive from a retryable BLOCK.
+
+    Returns a :class:`RetryDirective` ONLY for ``verdict == Verdict.BLOCK`` with a present, valid
+    ``retry_plan``. Returns ``None`` for plain BLOCK, every non-BLOCK verdict (including HALT),
+    a pending/``None`` verdict, and an expired :class:`ApprovalResult`.
+
+    This does NOT change enforcement: importing or exposing it never auto-retries. A caller must
+    invoke it explicitly, and it makes no claim that a replacement was evaluated or executed.
+
+    The gate is deliberately ``verdict == Verdict.BLOCK`` — NOT ``is_blocking()`` /
+    ``verdict.should_stop()``, which also match HALT (and, for approvals, expired results) and would
+    violate the wire-contract invariant that HALT always strips the plan.
+    """
+    # A stale/expired poll result must not surface a directive, even if verdict == BLOCK.
+    if isinstance(result, ApprovalResult) and result.expired:
+        return None
+    # ApprovalResult.verdict may be None (pending); the != BLOCK comparison handles that. Using
+    # getattr keeps this safe if a caller passes an unexpected object.
+    if getattr(result, "verdict", None) != Verdict.BLOCK:
+        return None
+
+    plan = result.retry_plan
+    if plan is None:
+        return None
+
+    # governance_event_id is typed on EvaluationResult; ApprovalResult carries it only in raw.
+    if isinstance(result, EvaluationResult):
+        governance_event_id = result.governance_event_id
+    else:
+        governance_event_id = result.raw.get("governance_event_id") or result.raw.get("id")
+
+    return RetryDirective(
+        new_input=plan.new_input,
+        governance_event_id=governance_event_id,
+        reason=result.reason,
+    )

{openbox_sdk_python-1.0.0 → openbox_sdk_python-1.1.0}/openbox_core/hooks/preflight.py

@@ -18,6 +18,7 @@ import logging
 from collections.abc import Mapping
 from typing import Any, NoReturn
 
+from ..adapters.base import adapter_accepts_context
 from ..approvals import ApprovalPoller
 from ..contracts.events import EventEnvelope
 from ..contracts.otel_spans import HookType, Stage
@@ -39,10 +40,13 @@ class HookRuntime:
         self._store = runtime.context_store
         self._gate = runtime.gate
         self._adapter = runtime.adapter
-        # Decide ONCE whether the adapter's completed callback takes ``context``,
-        # by inspecting its signature — so a genuine TypeError raised inside the
+        # Decide ONCE whether the adapter's callbacks take ``context``, by
+        # inspecting their signatures — so a genuine TypeError raised inside a
         # callback body is never mistaken for an arity mismatch and swallowed.
-        self._completed_accepts_context = self._adapter_accepts_context()
+        self._completed_accepts_context = adapter_accepts_context(
+            self._adapter.on_completed_hook_result
+        )
+        self._approval_accepts_context = adapter_accepts_context(self._adapter.handle_approval)
         hitl = runtime.config.hitl
         self._sync_poller: ApprovalPoller | None = None
         if hitl.enabled:
@@ -163,7 +167,14 @@ class HookRuntime:
             )
         if verdict.requires_approval():
             # Adapter drives its native approval flow; returning ⇒ approved.
-            await self._adapter.handle_approval(result)
+            # Core omits the workflow/run/activity IDs from the evaluate
+            # response, so hand the span-resolved context for the poll.
+            if self._approval_accepts_context:
+                await self._adapter.handle_approval(
+                    result, context=resolve_context(self._store, span)
+                )
+            else:
+                await self._adapter.handle_approval(result)
             return True
         return True
 
@@ -259,24 +270,6 @@ class HookRuntime:
             return
         self._after_completed(result, span)
 
-    def _adapter_accepts_context(self) -> bool:
-        """True when the adapter's ``on_completed_hook_result`` accepts a
-        ``context`` argument (checked once, by signature — not by catching a
-        TypeError from the call, which would mask real errors)."""
-        import inspect
-
-        callback = getattr(self._adapter, "on_completed_hook_result", None)
-        if callback is None:
-            return False
-        try:
-            params = inspect.signature(callback).parameters
-        except (TypeError, ValueError):
-            return False
-        # Accepts context via an explicit param or **kwargs.
-        return "context" in params or any(
-            p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()
-        )
-
     def _after_completed(self, result: EvaluationResult, span: Any) -> None:
         if result.verdict.should_stop():
             self._mark_stopped(result, span)  # future execution only

{openbox_sdk_python-1.0.0 → openbox_sdk_python-1.1.0}/openbox_core/runtime.py

@@ -17,10 +17,11 @@ from __future__ import annotations
 
 from typing import Any
 
-from .adapters.base import CoreAdapter, FrameworkAdapter
+from .adapters.base import CoreAdapter, FrameworkAdapter, adapter_accepts_context
 from .client import EvaluationClient
 from .config import OpenBoxConfig
 from .context import ContextStore, default_context_store
+from .contracts.context import ActivityContext
 from .contracts.events import EventEnvelope
 from .contracts.results import EvaluationResult, Verdict
 from .errors import GuardrailsValidationError
@@ -51,6 +52,9 @@ class OpenBoxRuntime:
     ):
         self.config = config
         self.adapter: FrameworkAdapter = adapter if adapter is not None else CoreAdapter()
+        # Decide ONCE whether the adapter's handle_approval accepts ``context``
+        # (older adapters take only ``result``) — see adapter_accepts_context.
+        self._approval_accepts_context = adapter_accepts_context(self.adapter.handle_approval)
         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,
@@ -104,7 +108,14 @@ class OpenBoxRuntime:
         result = await self.gate.aevaluate(event)
         if result.verdict.requires_approval():
             self._check_guardrails(result)
-            await self.adapter.handle_approval(result)
+            # Core omits workflow/run/activity IDs from the evaluate response, so
+            # build the approval context from the originating event for the poll.
+            if self._approval_accepts_context:
+                await self.adapter.handle_approval(
+                    result, context=_approval_context_from_event(event)
+                )
+            else:
+                await self.adapter.handle_approval(result)
             return result
         return self._enforce_lifecycle(result, drive_approval=False)
 
@@ -136,3 +147,25 @@ class OpenBoxRuntime:
         self.uninstall_instrumentation()
         self.context_store.clear()
         await self.client.aclose()
+
+
+def _approval_context_from_event(event: EventEnvelope) -> ActivityContext:
+    """Build the approval context for a lifecycle event.
+
+    ``workflow_id`` / ``run_id`` live in the flat wire ``payload``;
+    ``activity_id`` is a first-class envelope field (a workflow-level approval
+    legitimately has none). Core's evaluate response omits all three, so the
+    poll must be built from the originating event — see
+    ``CoreAdapter.handle_approval``.
+    """
+    payload = event.payload
+
+    def _s(value: Any) -> str | None:
+        return value if isinstance(value, str) else None
+
+    activity_id = event.activity_id if event.activity_id is not None else _s(payload.get("activity_id"))
+    return ActivityContext(
+        workflow_id=_s(payload.get("workflow_id")),
+        run_id=_s(payload.get("run_id")),
+        activity_id=activity_id,
+    )

{openbox_sdk_python-1.0.0 → openbox_sdk_python-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openbox-sdk-python"
-version = "1.0.0"
+version = "1.1.0"
 description = "OpenBox base SDK - governance contracts, strict gate, identity/signing, evaluate client, context runtime, OTel span wire serialization, and generic instrumentation shared by every OpenBox framework SDK"
 authors = [
     { name = "OpenBox Team", email = "tino@openbox.ai" },
@@ -26,7 +26,7 @@ dependencies = [
     "opentelemetry-api>=1.38.0,<1.40.0",
     "opentelemetry-sdk>=1.38.0,<1.40.0",
     "httpx>=0.28.0,<1",
-    "cryptography>=43,<47",
+    "cryptography>=48.0.1,<50",
 ]
 
 [project.optional-dependencies]