bindable 0.1.3__tar.gz → 0.1.4__tar.gz

{bindable-0.1.3 → bindable-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindable
-Version: 0.1.3
+Version: 0.1.4
 Summary: Python client for the hosted Bindable Action Gate, with offline Receipt verification
 Author: Bindable AI LLC
 License-Expression: Apache-2.0

{bindable-0.1.3 → bindable-0.1.4}/bindable/__init__.py

@@ -6,10 +6,14 @@ receive an Outcome, and verify the returned Receipt offline with
 signed Receipt with ``decision_from``. The client is pure transport; all
 proof-rule evaluation happens on the hosted gate, and receipt verification
 is fully offline.
+
+Review resolves the governing Contract by stage. ``decide()`` takes an optional
+``stage`` — one of ``STAGES`` — and omits the field entirely when it is not
+given, leaving the platform's ``development`` default in force.
 """
 
 from ._version import __version__
-from .client import ActionGate
+from .client import STAGES, ActionGate
 from .crypto import load_public_key
 from .decision import BLOCKED, RELEASED, decision_from
 from .errors import BindableAPIError
@@ -18,6 +22,7 @@ from .verify import ReceiptVerification, verify_receipt
 __all__ = [
     "BLOCKED",
     "RELEASED",
+    "STAGES",
     "ActionGate",
     "BindableAPIError",
     "ReceiptVerification",

bindable-0.1.4/bindable/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.4"

{bindable-0.1.3 → bindable-0.1.4}/bindable/client.py

@@ -14,12 +14,38 @@ from __future__ import annotations
 import secrets
 from collections.abc import Mapping
 from types import TracebackType
-from typing import Any
+from typing import Any, Final
 
 import httpx
 
 from bindable.errors import BindableAPIError
 
+#: The stages a Contract can be resolved at, as the platform names them.
+#:
+#: Review resolves the governing Contract BY STAGE. Omitting the field lets the
+#: platform apply its own default, which is ``development`` — correct for
+#: Sandbox work and wrong for a promoted Contract, which exists only at
+#: ``production``. Callers targeting a promoted Contract must say so.
+#:
+#: Single-sourced here so that callers validating their own configuration —
+#: an environment variable, a config file — check against the same tuple
+#: rather than keeping a second copy that can drift.
+STAGES: Final[tuple[str, ...]] = ("development", "test", "production")
+
+
+def _validated_stage(stage: str) -> str:
+    """Return ``stage`` if the platform accepts it, else raise locally.
+
+    Checked here rather than sent hopefully: a bad stage is a caller's
+    configuration mistake, and a named ValueError at the call site is a better
+    answer than a 422 that has already cost a round trip.
+    """
+    if stage not in STAGES:
+        raise ValueError(
+            f"stage must be one of {', '.join(STAGES)}; got {stage!r}"
+        )
+    return stage
+
 
 class ActionGate:
     """Thin, token-authenticated httpx client for the hosted Bindable Action Gate.
@@ -54,13 +80,15 @@ class ActionGate:
         payload: Mapping[str, Any],
         proposed_action_id: str,
         nonce: str | None = None,
+        stage: str | None = None,
     ) -> dict[str, Any]:
         """Submit a Proposal to ``/v1/review`` and return the hosted Outcome dict.
 
-        Sends exactly the five wire fields (persistent_agent_id, action_type,
-        payload, proposed_action_id, nonce) with bearer-token auth. The Outcome
-        is returned verbatim; its ``receipt`` field (when present) can be passed
-        to ``verify_receipt`` for offline verification.
+        Sends the five frozen wire fields (persistent_agent_id, action_type,
+        payload, proposed_action_id, nonce) with bearer-token auth, plus
+        ``stage`` when — and only when — one is given. The Outcome is returned
+        verbatim; its ``receipt`` field (when present) can be passed to
+        ``verify_receipt`` for offline verification.
 
         The endpoint moved from ``/v1/decide`` to ``/v1/review`` in 0.1.2. The
         platform keeps BOTH paths live for a deprecation window, so an older
@@ -74,11 +102,19 @@ class ActionGate:
             proposed_action_id: The caller's id for this proposed action.
             nonce: Replay-protection nonce; a fresh ``secrets.token_hex(16)``
                 is generated when omitted.
+            stage: Which stage to resolve the governing Contract at — one of
+                :data:`STAGES`. Omitted from the request entirely when None,
+                which leaves the platform's own default (``development``) in
+                force and keeps the body byte-identical to a pre-0.1.4 call.
+                A promoted Contract exists only at ``production``, so a caller
+                targeting one must pass it.
 
         Returns:
             The parsed Outcome JSON object as a dict.
 
         Raises:
+            ValueError: If ``stage`` is given and is not one of :data:`STAGES`.
+                Raised before any request is sent.
             BindableAPIError: If the gate returns a non-2xx response. The
                 error carries ``.status`` and the ``detail`` from the JSON body.
         """
@@ -91,6 +127,8 @@ class ActionGate:
             "proposed_action_id": proposed_action_id,
             "nonce": nonce,
         }
+        if stage is not None:
+            body["stage"] = _validated_stage(stage)
         response = self._client.post(
             f"{self._base_url}/v1/review",
             json=body,

{bindable-0.1.3 → bindable-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bindable"
-version = "0.1.3"
+version = "0.1.4"
 requires-python = ">=3.10"
 description = "Python client for the hosted Bindable Action Gate, with offline Receipt verification"
 readme = "README.md"

bindable-0.1.4/tests/test_stage.py

@@ -0,0 +1,152 @@
+"""The stage parameter: sent when given, absent when not, refused when wrong.
+
+Review resolves the governing Contract BY STAGE, and a promoted Contract exists
+only at ``production``. A client that cannot say which stage it means can only
+ever reach the platform's default, so these tests pin three things: that a
+given stage reaches the wire, that an omitted one leaves the request
+byte-identical to a pre-0.1.4 call, and that a wrong one is refused here rather
+than spent on a round trip.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+
+from bindable import STAGES, ActionGate
+
+_BASE_URL = "https://gate.example.com"
+_TOKEN = "test-token"
+
+_OUTCOME: dict[str, Any] = {
+    "status": "released",
+    "verdict": "passed",
+    "reason": None,
+    "reason_code": None,
+    "receipt": None,
+    "action_result": None,
+}
+
+_FROZEN_FIVE = {
+    "persistent_agent_id",
+    "action_type",
+    "payload",
+    "proposed_action_id",
+    "nonce",
+}
+
+
+def _capture(captured: dict[str, Any]) -> Any:
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["body"] = json.loads(request.content)
+        captured["raw"] = request.content
+        return httpx.Response(200, json=_OUTCOME)
+
+    return handler
+
+
+def _gate_with(handler: Any) -> ActionGate:
+    gate = ActionGate(base_url=_BASE_URL, token=_TOKEN)
+    gate._client.close()
+    gate._client = httpx.Client(transport=httpx.MockTransport(handler), timeout=5.0)
+    return gate
+
+
+def _decide(gate: ActionGate, **extra: Any) -> dict[str, Any]:
+    return gate.decide(
+        persistent_agent_id="agent_1",
+        action_type="paid_data_call",
+        payload={"matter_id": "MER-2026-014", "call_cost_usd": 12},
+        proposed_action_id="claim_1",
+        nonce="fixednonce",
+        **extra,
+    )
+
+
+# ─── the vocabulary ────────────────────────────────────────────────────
+
+
+def test_the_stages_are_the_three_the_platform_resolves_against() -> None:
+    assert STAGES == ("development", "test", "production")
+
+
+# ─── sent when given ───────────────────────────────────────────────────
+
+
+@pytest.mark.parametrize("stage", STAGES)
+def test_a_given_stage_reaches_the_wire(stage: str) -> None:
+    captured: dict[str, Any] = {}
+    with _gate_with(_capture(captured)) as gate:
+        _decide(gate, stage=stage)
+
+    assert captured["body"]["stage"] == stage
+    assert set(captured["body"]) == _FROZEN_FIVE | {"stage"}
+
+
+def test_production_is_reachable_because_a_promoted_contract_lives_only_there() -> None:
+    """The reason this parameter exists, stated as a test."""
+    captured: dict[str, Any] = {}
+    with _gate_with(_capture(captured)) as gate:
+        _decide(gate, stage="production")
+
+    assert captured["body"]["stage"] == "production"
+
+
+# ─── omitted when None ─────────────────────────────────────────────────
+
+
+def test_an_omitted_stage_is_absent_from_the_wire_entirely() -> None:
+    """Not null, not empty — absent. The platform's default stays in force."""
+    captured: dict[str, Any] = {}
+    with _gate_with(_capture(captured)) as gate:
+        _decide(gate)
+
+    assert "stage" not in captured["body"]
+    assert set(captured["body"]) == _FROZEN_FIVE
+
+
+def test_omitting_the_stage_is_byte_identical_to_passing_none() -> None:
+    """Every pre-0.1.4 caller is untouched: same bytes, not merely same fields."""
+    without: dict[str, Any] = {}
+    explicit_none: dict[str, Any] = {}
+
+    with _gate_with(_capture(without)) as gate:
+        _decide(gate)
+    with _gate_with(_capture(explicit_none)) as gate:
+        _decide(gate, stage=None)
+
+    assert without["raw"] == explicit_none["raw"]
+    assert b"stage" not in without["raw"]
+
+
+# ─── refused when invalid ──────────────────────────────────────────────
+
+
+@pytest.mark.parametrize(
+    "bad", ["prod", "Production", "PRODUCTION", "staging", "dev", "", " development"]
+)
+def test_an_invalid_stage_is_refused_locally(bad: str) -> None:
+    """A configuration mistake, answered here — not spent on a 422."""
+    sent: list[Any] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:  # pragma: no cover
+        sent.append(request)
+        return httpx.Response(200, json=_OUTCOME)
+
+    with _gate_with(handler) as gate, pytest.raises(ValueError) as excinfo:
+        _decide(gate, stage=bad)
+
+    assert sent == []  # nothing left the process
+    message = str(excinfo.value)
+    assert repr(bad) in message
+    for allowed in STAGES:
+        assert allowed in message  # the error names what IS allowed
+
+
+def test_the_refusal_happens_before_the_request_is_built() -> None:
+    """No partial send, no retry ambiguity: the call never starts."""
+    with _gate_with(_capture({})) as gate, pytest.raises(ValueError, match="stage must be one of"):
+        _decide(gate, stage="nope")

{bindable-0.1.3 → bindable-0.1.4}/tests/test_version.py

@@ -2,4 +2,4 @@ import bindable
 
 
 def test_version() -> None:
-    assert bindable.__version__ == "0.1.3"
+    assert bindable.__version__ == "0.1.4"

bindable-0.1.3/bindable/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1.3"