provecart-adk 0.1.0__tar.gz

provecart_adk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProveCart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

provecart_adk-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: provecart-adk
+Version: 0.1.0
+Summary: ProveCart pre-action hook for Google ADK: check an agent's order, booking or reservation against the customer's signed mandate before a purchase tool runs.
+License: MIT
+Project-URL: Homepage, https://provecart.com
+Project-URL: Repository, https://github.com/provecart/provecart
+Keywords: ai-agents,agent-commerce,google-adk,provecart,pre-payment-verification
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: adk
+Requires-Dist: google-adk; extra == "adk"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# provecart-adk
+
+A pre-action hook for Google ADK agents, from ProveCart.
+
+An agent that buys for someone needs one check in the right place:
+after it has built the order, and before any money moves. This
+package puts that check on ADK's tool boundary. When a purchase
+tool is about to run, the hook reads the pending order, booking or
+reservation out of the tool arguments, compares it with the
+customer's signed mandate, and only then decides whether the tool
+call goes ahead.
+
+```bash
+pip install provecart-adk
+pip install "provecart-adk[adk]"   # also installs google-adk
+```
+
+## How it works
+
+ProveCart returns one of three verdicts:
+
+- **MATCH** — the tool runs. The callback returns `None`, which is
+  ADK's signal to proceed as normal.
+- **BLOCK** — the tool does not run. ADK's documented refusal path
+  applies: a `before_tool_callback` that returns a dict skips the
+  tool call and that dict becomes the tool result. The dict carries
+  the verdict, the record id and the corrections, so the agent can
+  apply a fix that stays inside the customer's existing
+  authorization and check again.
+- **REVIEW** — the tool does not run, and the refusal dict tells
+  the agent to stop and ask the customer. A review is never turned
+  into a guess.
+
+A check that fails, a verdict that is not recognized, and a BLOCK
+whose corrections use an unknown action all escalate the same way.
+Nothing falls through to the purchase tool by accident.
+
+## Use it two ways
+
+As an agent callback:
+
+```python
+from provecart_adk import ProveCartGuard, make_before_tool_callback
+
+guard = ProveCartGuard(client=my_provecart_client)
+agent = LlmAgent(
+    name="shopper",
+    tools=[place_order],
+    before_tool_callback=make_before_tool_callback(guard),
+)
+```
+
+Or as a plugin, registered once so it covers every agent and tool
+in the app:
+
+```python
+from provecart_adk import ProveCartPlugin
+
+plugin = ProveCartPlugin(client=my_provecart_client)
+# Runner(..., plugins=[plugin]) or App(..., plugins=[plugin])
+```
+
+## The client is yours to inject
+
+This package does not hard-wire an HTTP client. Pass any object
+with these methods, each returning a dict with `verdict`,
+`corrections`, `record_id` and `max_attempts`:
+
+- `check_cart(**payload)`
+- `check_booking(**payload)`
+- `check_reservation(**payload)`
+
+If that object also provides
+`route_verdict(response) -> (decision, detail)`, with decision one
+of `proceed`, `fix` or `escalate`, the hook uses it. Otherwise the
+routing built into this package applies: MATCH proceeds; BLOCK
+becomes `fix` only when every correction is a known action; BLOCK
+without usable corrections, REVIEW and anything unknown escalate.
+A client exposing only `verify_cart` is adapted for cart checks.
+
+## Which tools are watched
+
+By default the guard watches common purchase names — `place_order`,
+`checkout`, `capture_payment` and friends for carts; `book_flight`,
+`create_booking` for bookings; `make_reservation`, `reserve_table`
+for reservations — and ignores every other tool without calling the
+client. Pass your own map to watch exactly your tool names:
+
+```python
+guard = ProveCartGuard(
+    client=my_provecart_client,
+    tool_kinds={"submit_payment": "cart", "hold_room": "booking"},
+)
+```
+
+Payloads are taken from the tool arguments as-is, or from a nested
+`cart` / `booking` / `reservation` dict when the tool wraps its
+order that way. Pass an `extractor(kind, args) -> dict` callable if
+your tools shape their arguments differently.
+
+## Offline example and tests
+
+```bash
+python examples/mock_example.py   # MOCK mode, injected fake client
+python -m pytest tests/ -q        # offline; ADK is stubbed if absent
+```
+
+The example defaults to mock mode and makes no network calls on
+import or on a normal run. Live use is an explicit opt-in: build
+your real client and inject it, as the example marks.
+
+## Notes
+
+Published by ProveCart, a verification service for agent commerce
+based in the Bay Area. Patent pending.
+
+Docs: https://provecart.com/portal/docs ·
+Source: https://github.com/provecart/provecart/tree/main/packages/provecart-adk

provecart_adk-0.1.0/README.md

@@ -0,0 +1,118 @@
+# provecart-adk
+
+A pre-action hook for Google ADK agents, from ProveCart.
+
+An agent that buys for someone needs one check in the right place:
+after it has built the order, and before any money moves. This
+package puts that check on ADK's tool boundary. When a purchase
+tool is about to run, the hook reads the pending order, booking or
+reservation out of the tool arguments, compares it with the
+customer's signed mandate, and only then decides whether the tool
+call goes ahead.
+
+```bash
+pip install provecart-adk
+pip install "provecart-adk[adk]"   # also installs google-adk
+```
+
+## How it works
+
+ProveCart returns one of three verdicts:
+
+- **MATCH** — the tool runs. The callback returns `None`, which is
+  ADK's signal to proceed as normal.
+- **BLOCK** — the tool does not run. ADK's documented refusal path
+  applies: a `before_tool_callback` that returns a dict skips the
+  tool call and that dict becomes the tool result. The dict carries
+  the verdict, the record id and the corrections, so the agent can
+  apply a fix that stays inside the customer's existing
+  authorization and check again.
+- **REVIEW** — the tool does not run, and the refusal dict tells
+  the agent to stop and ask the customer. A review is never turned
+  into a guess.
+
+A check that fails, a verdict that is not recognized, and a BLOCK
+whose corrections use an unknown action all escalate the same way.
+Nothing falls through to the purchase tool by accident.
+
+## Use it two ways
+
+As an agent callback:
+
+```python
+from provecart_adk import ProveCartGuard, make_before_tool_callback
+
+guard = ProveCartGuard(client=my_provecart_client)
+agent = LlmAgent(
+    name="shopper",
+    tools=[place_order],
+    before_tool_callback=make_before_tool_callback(guard),
+)
+```
+
+Or as a plugin, registered once so it covers every agent and tool
+in the app:
+
+```python
+from provecart_adk import ProveCartPlugin
+
+plugin = ProveCartPlugin(client=my_provecart_client)
+# Runner(..., plugins=[plugin]) or App(..., plugins=[plugin])
+```
+
+## The client is yours to inject
+
+This package does not hard-wire an HTTP client. Pass any object
+with these methods, each returning a dict with `verdict`,
+`corrections`, `record_id` and `max_attempts`:
+
+- `check_cart(**payload)`
+- `check_booking(**payload)`
+- `check_reservation(**payload)`
+
+If that object also provides
+`route_verdict(response) -> (decision, detail)`, with decision one
+of `proceed`, `fix` or `escalate`, the hook uses it. Otherwise the
+routing built into this package applies: MATCH proceeds; BLOCK
+becomes `fix` only when every correction is a known action; BLOCK
+without usable corrections, REVIEW and anything unknown escalate.
+A client exposing only `verify_cart` is adapted for cart checks.
+
+## Which tools are watched
+
+By default the guard watches common purchase names — `place_order`,
+`checkout`, `capture_payment` and friends for carts; `book_flight`,
+`create_booking` for bookings; `make_reservation`, `reserve_table`
+for reservations — and ignores every other tool without calling the
+client. Pass your own map to watch exactly your tool names:
+
+```python
+guard = ProveCartGuard(
+    client=my_provecart_client,
+    tool_kinds={"submit_payment": "cart", "hold_room": "booking"},
+)
+```
+
+Payloads are taken from the tool arguments as-is, or from a nested
+`cart` / `booking` / `reservation` dict when the tool wraps its
+order that way. Pass an `extractor(kind, args) -> dict` callable if
+your tools shape their arguments differently.
+
+## Offline example and tests
+
+```bash
+python examples/mock_example.py   # MOCK mode, injected fake client
+python -m pytest tests/ -q        # offline; ADK is stubbed if absent
+```
+
+The example defaults to mock mode and makes no network calls on
+import or on a normal run. Live use is an explicit opt-in: build
+your real client and inject it, as the example marks.
+
+## Notes
+
+Published by ProveCart, a verification service for agent commerce
+based in the Bay Area. Patent pending.
+
+Docs: https://provecart.com/portal/docs ·
+Source: https://github.com/provecart/provecart/tree/main/packages/provecart-adk

provecart_adk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provecart-adk"
+version = "0.1.0"
+description = "ProveCart pre-action hook for Google ADK: check an agent's order, booking or reservation against the customer's signed mandate before a purchase tool runs."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+keywords = ["ai-agents", "agent-commerce", "google-adk", "provecart", "pre-payment-verification"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+adk = ["google-adk"]
+test = ["pytest"]
+
+[project.urls]
+Homepage = "https://provecart.com"
+Repository = "https://github.com/provecart/provecart"
+
+[tool.setuptools.packages.find]
+where = ["src"]

provecart_adk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

provecart_adk-0.1.0/src/provecart_adk/__init__.py

@@ -0,0 +1,283 @@
+"""ProveCart pre-action hook for Google ADK.
+
+Intercepts the moment before a purchase tool runs, checks the
+pending order, booking or reservation against the customer's signed
+mandate, and lets the tool run only on a MATCH.
+
+Verdict routing (same semantics as the shared ProveCart client):
+
+  MATCH              -> proceed (return None; ADK runs the tool)
+  BLOCK + known fixes -> do not run the tool; return a refusal dict
+                        carrying the corrections, so the agent can
+                        apply only fixes inside the customer's
+                        existing authorization and re-check
+  BLOCK otherwise,
+  REVIEW, unknown    -> do not run the tool; return a refusal dict
+                        that escalates to the customer
+
+In ADK, returning a dict from ``before_tool_callback`` skips the
+tool call and uses that dict as the tool result. That documented
+refusal path is what this package uses for every non-proceed case.
+
+The client is injected and duck-typed. Any object with
+``check_cart`` / ``check_booking`` / ``check_reservation`` methods
+returning a dict with ``verdict``, ``corrections``, ``record_id``
+and ``max_attempts`` works, as does an object exposing
+``route_verdict(response) -> (decision, detail)``. If the client
+supplies its own ``route_verdict`` it is used; otherwise the routing
+in this module is used. A client with only the older
+``verify_cart`` shape is adapted for cart checks.
+
+No network call happens on import.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple
+
+__version__ = "0.1.0"
+__all__ = [
+    "KNOWN_ACTIONS",
+    "DEFAULT_TOOL_KINDS",
+    "ProveCartGuard",
+    "FakeProveCartClient",
+    "make_before_tool_callback",
+    "route_verdict",
+]
+
+KNOWN_ACTIONS = {
+    "remove_item", "replace_item", "change_variant", "reduce_quantity",
+    "reduce_total", "change_currency", "correct_traveler_name",
+    "change_airport", "change_travel_date", "change_departure_time",
+    "add_itinerary", "rebuild_itinerary", "change_cabin",
+    "change_fare_terms", "add_hotel_stay", "change_room",
+    "change_provider", "change_location", "change_date", "change_time",
+    "change_party_size", "correct_reservation_name", "reduce_deposit",
+    "change_cancellation_terms",
+}
+
+# Default purchase-tool names -> check kind. Override per guard.
+DEFAULT_TOOL_KINDS: Dict[str, str] = {
+    "place_order": "cart",
+    "checkout": "cart",
+    "create_order": "cart",
+    "capture_payment": "cart",
+    "pay": "cart",
+    "purchase": "cart",
+    "buy": "cart",
+    "create_booking": "booking",
+    "book_flight": "booking",
+    "book_hotel": "booking",
+    "book": "booking",
+    "make_reservation": "reservation",
+    "create_reservation": "reservation",
+    "reserve_table": "reservation",
+    "reserve": "reservation",
+}
+
+_CHECK_METHOD = {
+    "cart": "check_cart",
+    "booking": "check_booking",
+    "reservation": "check_reservation",
+}
+_PAYLOAD_KEYS = {"cart": "cart", "booking": "booking", "reservation": "reservation"}
+
+
+def route_verdict(response: Mapping[str, Any]) -> Tuple[str, Dict[str, Any]]:
+    """Return (decision, detail); decision in {proceed, fix, escalate}.
+
+    'fix' is returned only when the verdict is BLOCK and every
+    correction is a known action. Anything else non-MATCH escalates.
+    """
+    verdict = (response or {}).get("verdict")
+    if verdict == "MATCH":
+        return "proceed", {"record_id": response.get("record_id")}
+    if verdict == "BLOCK":
+        corrections = response.get("corrections") or []
+        if corrections and all(
+            isinstance(c, Mapping) and c.get("action") in KNOWN_ACTIONS
+            for c in corrections
+        ):
+            return "fix", {
+                "corrections": list(corrections),
+                "record_id": response.get("record_id"),
+                "max_attempts": response.get("max_attempts"),
+            }
+        return "escalate", {
+            "reason": "BLOCK without usable corrections",
+            "record_id": response.get("record_id"),
+        }
+    return "escalate", {
+        "reason": f"verdict {verdict} needs the buyer",
+        "record_id": response.get("record_id"),
+    }
+
+
+def _tool_name(tool: Any) -> str:
+    if isinstance(tool, str):
+        return tool
+    return getattr(tool, "name", "") or str(tool)
+
+
+class ProveCartGuard:
+    """Framework-agnostic core; the ADK adapters below call it."""
+
+    def __init__(
+        self,
+        client: Any,
+        tool_kinds: Optional[Mapping[str, str]] = None,
+        extractor: Optional[Callable[[str, Dict[str, Any]], Dict[str, Any]]] = None,
+    ):
+        if client is None:
+            raise ValueError("ProveCartGuard requires an injected client")
+        self.client = client
+        self.tool_kinds = dict(tool_kinds) if tool_kinds is not None else dict(DEFAULT_TOOL_KINDS)
+        self.extractor = extractor
+
+    def kind_for(self, tool: Any) -> Optional[str]:
+        return self.tool_kinds.get(_tool_name(tool))
+
+    def extract(self, kind: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        if self.extractor is not None:
+            return dict(self.extractor(kind, dict(args)))
+        nested = args.get(_PAYLOAD_KEYS[kind])
+        if isinstance(nested, Mapping):
+            payload = dict(nested)
+            # Mandate / linkage fields may sit beside the nested payload.
+            for key in ("mandate_id", "previous_record_id"):
+                if key in args and key not in payload:
+                    payload[key] = args[key]
+            return payload
+        return dict(args)
+
+    def check(self, kind: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        method_name = _CHECK_METHOD[kind]
+        method = getattr(self.client, method_name, None)
+        if callable(method):
+            return dict(method(**payload))
+        if kind == "cart" and callable(getattr(self.client, "verify_cart", None)):
+            return dict(self.client.verify_cart(**payload))
+        raise TypeError(f"client does not provide {method_name}()")
+
+    def route(self, response: Dict[str, Any]) -> Tuple[str, Dict[str, Any]]:
+        client_route = getattr(self.client, "route_verdict", None)
+        if callable(client_route):
+            decision, detail = client_route(response)
+            return str(decision), dict(detail or {})
+        return route_verdict(response)
+
+    def before_tool(self, tool: Any, args: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+        """Return None to let the tool run, or a refusal dict to skip it."""
+        kind = self.kind_for(tool)
+        if kind is None:
+            return None
+        payload = self.extract(kind, dict(args or {}))
+        try:
+            response = self.check(kind, payload)
+        except Exception as exc:  # a failed check never lets a purchase through
+            return self._refusal(kind, tool, None, "escalate",
+                                 {"reason": f"check failed: {exc}"})
+        decision, detail = self.route(response)
+        if decision == "proceed":
+            return None
+        return self._refusal(kind, tool, response, decision, detail)
+
+    @staticmethod
+    def _refusal(kind, tool, response, decision, detail):
+        response = response or {}
+        return {
+            "provecart_blocked": True,
+            "provecart_decision": decision,
+            "verdict": response.get("verdict"),
+            "check_kind": kind,
+            "tool": _tool_name(tool),
+            "corrections": response.get("corrections") or detail.get("corrections") or [],
+            "record_id": response.get("record_id") or detail.get("record_id"),
+            "max_attempts": response.get("max_attempts") or detail.get("max_attempts"),
+            "detail": detail,
+            "error": (
+                "ProveCart check did not return MATCH, so the purchase "
+                "tool was not run. On 'fix', apply only the listed "
+                "corrections inside the customer's existing authorization "
+                "and re-check with previous_record_id. On 'escalate', "
+                "stop and ask the customer."
+            ),
+        }
+
+
+def make_before_tool_callback(guard: ProveCartGuard):
+    """Build an ADK agent-level ``before_tool_callback``.
+
+    Documented ADK signature:
+    ``(tool, args, tool_context) -> Optional[dict]`` — returning None
+    lets the tool run; returning a dict skips the tool and that dict
+    becomes the tool result.
+    """
+    def before_tool_callback(tool=None, args=None, tool_context=None, **_kw):
+        return guard.before_tool(tool, args or {})
+
+    return before_tool_callback
+
+
+try:  # Real plugin base when google-adk is installed; stub-safe otherwise.
+    from google.adk.plugins.base_plugin import BasePlugin as _BasePlugin
+    _HAS_ADK = True
+except Exception:  # pragma: no cover - exercised in stubbed environments
+    _BasePlugin = object  # type: ignore
+    _HAS_ADK = False
+
+
+class ProveCartPlugin(_BasePlugin):  # type: ignore[misc]
+    """ADK plugin form. Register once on the Runner / App.
+
+    Plugin signature in current ADK:
+    ``async before_tool_callback(*, tool, tool_args, tool_context)``
+    returning None to proceed or a dict to skip the tool. Older /
+    alternate callers may pass ``args`` instead of ``tool_args``;
+    both are accepted.
+    """
+
+    def __init__(self, guard: Optional[ProveCartGuard] = None, *,
+                 client: Any = None, **guard_kwargs):
+        if _HAS_ADK:
+            try:
+                super().__init__(name="provecart")
+            except TypeError:
+                super().__init__()
+        self.guard = guard or ProveCartGuard(client, **guard_kwargs)
+
+    async def before_tool_callback(self, *, tool=None, tool_args=None,
+                                   args=None, tool_context=None, **_kw):
+        payload = tool_args if tool_args is not None else args
+        return self.guard.before_tool(tool, payload or {})
+
+
+class FakeProveCartClient:
+    """Offline fake for examples and tests. No network, ever.
+
+    Pass a fixed response dict, or a callable payload -> response.
+    Records every call in ``.calls`` as (kind, payload).
+    """
+
+    def __init__(self, response=None):
+        self._response = response if response is not None else {
+            "verdict": "MATCH", "corrections": [], "record_id": "rec_mock_1",
+            "max_attempts": 3,
+        }
+        self.calls = []
+
+    def _handle(self, kind, **payload):
+        self.calls.append((kind, payload))
+        if callable(self._response):
+            return dict(self._response(payload))
+        return dict(self._response)
+
+    def check_cart(self, **payload):
+        return self._handle("cart", **payload)
+
+    def check_booking(self, **payload):
+        return self._handle("booking", **payload)
+
+    def check_reservation(self, **payload):
+        return self._handle("reservation", **payload)
+
+    # Deliberately no route_verdict: exercises this module's routing.

provecart_adk-0.1.0/src/provecart_adk.egg-info/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: provecart-adk
+Version: 0.1.0
+Summary: ProveCart pre-action hook for Google ADK: check an agent's order, booking or reservation against the customer's signed mandate before a purchase tool runs.
+License: MIT
+Project-URL: Homepage, https://provecart.com
+Project-URL: Repository, https://github.com/provecart/provecart
+Keywords: ai-agents,agent-commerce,google-adk,provecart,pre-payment-verification
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: adk
+Requires-Dist: google-adk; extra == "adk"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# provecart-adk
+
+A pre-action hook for Google ADK agents, from ProveCart.
+
+An agent that buys for someone needs one check in the right place:
+after it has built the order, and before any money moves. This
+package puts that check on ADK's tool boundary. When a purchase
+tool is about to run, the hook reads the pending order, booking or
+reservation out of the tool arguments, compares it with the
+customer's signed mandate, and only then decides whether the tool
+call goes ahead.
+
+```bash
+pip install provecart-adk
+pip install "provecart-adk[adk]"   # also installs google-adk
+```
+
+## How it works
+
+ProveCart returns one of three verdicts:
+
+- **MATCH** — the tool runs. The callback returns `None`, which is
+  ADK's signal to proceed as normal.
+- **BLOCK** — the tool does not run. ADK's documented refusal path
+  applies: a `before_tool_callback` that returns a dict skips the
+  tool call and that dict becomes the tool result. The dict carries
+  the verdict, the record id and the corrections, so the agent can
+  apply a fix that stays inside the customer's existing
+  authorization and check again.
+- **REVIEW** — the tool does not run, and the refusal dict tells
+  the agent to stop and ask the customer. A review is never turned
+  into a guess.
+
+A check that fails, a verdict that is not recognized, and a BLOCK
+whose corrections use an unknown action all escalate the same way.
+Nothing falls through to the purchase tool by accident.
+
+## Use it two ways
+
+As an agent callback:
+
+```python
+from provecart_adk import ProveCartGuard, make_before_tool_callback
+
+guard = ProveCartGuard(client=my_provecart_client)
+agent = LlmAgent(
+    name="shopper",
+    tools=[place_order],
+    before_tool_callback=make_before_tool_callback(guard),
+)
+```
+
+Or as a plugin, registered once so it covers every agent and tool
+in the app:
+
+```python
+from provecart_adk import ProveCartPlugin
+
+plugin = ProveCartPlugin(client=my_provecart_client)
+# Runner(..., plugins=[plugin]) or App(..., plugins=[plugin])
+```
+
+## The client is yours to inject
+
+This package does not hard-wire an HTTP client. Pass any object
+with these methods, each returning a dict with `verdict`,
+`corrections`, `record_id` and `max_attempts`:
+
+- `check_cart(**payload)`
+- `check_booking(**payload)`
+- `check_reservation(**payload)`
+
+If that object also provides
+`route_verdict(response) -> (decision, detail)`, with decision one
+of `proceed`, `fix` or `escalate`, the hook uses it. Otherwise the
+routing built into this package applies: MATCH proceeds; BLOCK
+becomes `fix` only when every correction is a known action; BLOCK
+without usable corrections, REVIEW and anything unknown escalate.
+A client exposing only `verify_cart` is adapted for cart checks.
+
+## Which tools are watched
+
+By default the guard watches common purchase names — `place_order`,
+`checkout`, `capture_payment` and friends for carts; `book_flight`,
+`create_booking` for bookings; `make_reservation`, `reserve_table`
+for reservations — and ignores every other tool without calling the
+client. Pass your own map to watch exactly your tool names:
+
+```python
+guard = ProveCartGuard(
+    client=my_provecart_client,
+    tool_kinds={"submit_payment": "cart", "hold_room": "booking"},
+)
+```
+
+Payloads are taken from the tool arguments as-is, or from a nested
+`cart` / `booking` / `reservation` dict when the tool wraps its
+order that way. Pass an `extractor(kind, args) -> dict` callable if
+your tools shape their arguments differently.
+
+## Offline example and tests
+
+```bash
+python examples/mock_example.py   # MOCK mode, injected fake client
+python -m pytest tests/ -q        # offline; ADK is stubbed if absent
+```
+
+The example defaults to mock mode and makes no network calls on
+import or on a normal run. Live use is an explicit opt-in: build
+your real client and inject it, as the example marks.
+
+## Notes
+
+Published by ProveCart, a verification service for agent commerce
+based in the Bay Area. Patent pending.
+
+Docs: https://provecart.com/portal/docs ·
+Source: https://github.com/provecart/provecart/tree/main/packages/provecart-adk

provecart_adk-0.1.0/src/provecart_adk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/provecart_adk/__init__.py
+src/provecart_adk.egg-info/PKG-INFO
+src/provecart_adk.egg-info/SOURCES.txt
+src/provecart_adk.egg-info/dependency_links.txt
+src/provecart_adk.egg-info/requires.txt
+src/provecart_adk.egg-info/top_level.txt
+tests/test_provecart_adk.py

provecart_adk-0.1.0/src/provecart_adk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

provecart_adk-0.1.0/src/provecart_adk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[adk]
+google-adk
+
+[test]
+pytest

provecart_adk-0.1.0/src/provecart_adk.egg-info/top_level.txt

@@ -0,0 +1 @@
+provecart_adk

provecart_adk-0.1.0/tests/test_provecart_adk.py

@@ -0,0 +1,137 @@
+"""Offline tests for provecart-adk. No network; ADK stubbed if absent."""
+import asyncio
+import sys
+import types
+
+# Stub google.adk plugin base if the real package is not installed,
+# so the plugin class can be imported and exercised offline.
+try:
+    import google.adk.plugins.base_plugin  # noqa: F401
+    HAS_ADK = True
+except Exception:
+    HAS_ADK = False
+    google = types.ModuleType("google")
+    adk = types.ModuleType("google.adk")
+    plugins = types.ModuleType("google.adk.plugins")
+    base_plugin = types.ModuleType("google.adk.plugins.base_plugin")
+
+    class BasePlugin:
+        def __init__(self, name=None):
+            self.name = name
+
+    base_plugin.BasePlugin = BasePlugin
+    plugins.base_plugin = base_plugin
+    adk.plugins = plugins
+    google.adk = adk
+    sys.modules.setdefault("google", google)
+    sys.modules["google.adk"] = adk
+    sys.modules["google.adk.plugins"] = plugins
+    sys.modules["google.adk.plugins.base_plugin"] = base_plugin
+
+sys.path.insert(0, "src")
+
+from provecart_adk import (  # noqa: E402
+    FakeProveCartClient, ProveCartGuard, ProveCartPlugin,
+    make_before_tool_callback, route_verdict,
+)
+
+
+class Tool:
+    def __init__(self, name):
+        self.name = name
+
+
+CART_ARGS = {"mandate_id": "m1", "merchant": {"name": "Shop"},
+             "items": [{"name": "Chair"}], "total_price": 10}
+
+
+def test_route_match_proceeds():
+    assert route_verdict({"verdict": "MATCH", "record_id": "r1"})[0] == "proceed"
+
+
+def test_route_block_known_fix():
+    d, detail = route_verdict({"verdict": "BLOCK", "record_id": "r",
+                               "corrections": [{"action": "remove_item"}],
+                               "max_attempts": 3})
+    assert d == "fix" and detail["max_attempts"] == 3
+
+
+def test_route_block_unknown_escalates():
+    d, _ = route_verdict({"verdict": "BLOCK",
+                          "corrections": [{"action": "widen_budget"}]})
+    assert d == "escalate"
+
+
+def test_route_review_and_unknown_escalate():
+    assert route_verdict({"verdict": "REVIEW"})[0] == "escalate"
+    assert route_verdict({"verdict": "???"})[0] == "escalate"
+    assert route_verdict({})[0] == "escalate"
+
+
+def test_non_purchase_tool_passes_without_check():
+    fake = FakeProveCartClient()
+    guard = ProveCartGuard(fake)
+    assert guard.before_tool(Tool("search_catalog"), {"q": "x"}) is None
+    assert fake.calls == []
+
+
+def test_match_lets_tool_run():
+    fake = FakeProveCartClient()
+    cb = make_before_tool_callback(ProveCartGuard(fake))
+    assert cb(tool=Tool("place_order"), args=CART_ARGS, tool_context=None) is None
+    assert fake.calls and fake.calls[0][0] == "cart"
+
+
+def test_block_returns_refusal_dict_with_corrections():
+    fake = FakeProveCartClient({"verdict": "BLOCK", "record_id": "r9",
+                                "max_attempts": 2,
+                                "corrections": [{"action": "reduce_quantity"}]})
+    cb = make_before_tool_callback(ProveCartGuard(fake))
+    out = cb(tool=Tool("checkout"), args=CART_ARGS, tool_context=None)
+    assert out["provecart_blocked"] is True
+    assert out["provecart_decision"] == "fix"
+    assert out["corrections"] == [{"action": "reduce_quantity"}]
+    assert out["record_id"] == "r9"
+
+
+def test_review_escalates_and_booking_and_reservation_kinds():
+    fake = FakeProveCartClient({"verdict": "REVIEW", "record_id": "r2",
+                                "corrections": []})
+    guard = ProveCartGuard(fake)
+    out = guard.before_tool(Tool("book_flight"), {"booking": {"mandate_id": "m"}})
+    assert out["provecart_decision"] == "escalate" and out["check_kind"] == "booking"
+    out = guard.before_tool(Tool("reserve_table"), {"mandate_id": "m"})
+    assert out["check_kind"] == "reservation"
+    assert [c[0] for c in fake.calls] == ["booking", "reservation"]
+
+
+def test_check_failure_escalates_not_proceeds():
+    class Boom:
+        def check_cart(self, **kw):
+            raise RuntimeError("down")
+    guard = ProveCartGuard(Boom())
+    out = guard.before_tool(Tool("place_order"), CART_ARGS)
+    assert out["provecart_decision"] == "escalate"
+
+
+def test_client_route_verdict_is_preferred():
+    class Own:
+        def check_cart(self, **kw):
+            return {"verdict": "MATCH", "record_id": "x"}
+        def route_verdict(self, response):
+            return "escalate", {"reason": "house rule"}
+    guard = ProveCartGuard(Own())
+    out = guard.before_tool(Tool("place_order"), CART_ARGS)
+    assert out["provecart_decision"] == "escalate"
+
+
+def test_plugin_callback_signature_both_arg_names():
+    fake = FakeProveCartClient()
+    plugin = ProveCartPlugin(client=fake)
+    run = asyncio.get_event_loop().run_until_complete
+    assert run(plugin.before_tool_callback(
+        tool=Tool("place_order"), tool_args=CART_ARGS, tool_context=None)) is None
+    assert run(plugin.before_tool_callback(
+        tool=Tool("place_order"), args=CART_ARGS, tool_context=None)) is None
+    assert len(fake.calls) == 2
+    print("HAS_REAL_ADK:", HAS_ADK)