provecart 0.1.0__tar.gz

provecart-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: provecart
+Version: 0.1.0
+Summary: ProveCart client: check an AI agent's cart, booking, or reservation against the buyer's signed instructions before payment is captured.
+License: MIT
+Project-URL: Homepage, https://provecart.com
+Project-URL: Documentation, https://provecart.com/agents
+Project-URL: Correction format, https://provecart.com/standards/correction-format
+Keywords: ai-agents,agent-commerce,verification,payments,provecart
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# provecart
+
+Your agent put the wrong variant in the cart — the wrong size, the wrong model, a quantity nobody asked for — and your user paid for it. By the time anyone noticed, the order had shipped, and the return came out of somebody's pocket. That is the failure this package exists to stop: one check, between what the agent built and the payment, that compares the transaction against what the buyer actually said.
+
+ProveCart is a neutral verification API for agent commerce. You record the buyer's instruction as a signed mandate, send what the agent actually built, and get back a signed verdict — `MATCH`, `REVIEW`, or `BLOCK` — before payment is captured (or, for bookings, before a ticket is issued). A `BLOCK` or `REVIEW` answer carries machine-readable corrections, so the agent can fix what it built and resubmit instead of losing the sale or guessing. Every check is written to a sealed evidence record. ProveCart never holds or moves money.
+
+```bash
+pip install provecart
+```
+
+Standard library only. No dependencies.
+
+## Check a cart
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_cart(merchant={"name": "Example Shop", "domain": "shop.example.com"}, items=[{"name": "Wireless Headphones", "variant": "black", "quantity": 1, "unit_price": 249.99}], total_price=249.99, mandate={"user_id": "user-123", "item_description": "Wireless noise cancelling over-ear headphones", "item_keywords": ["wireless", "headphones"], "category": "electronics", "max_total_price": 300.00, "currency": "USD", "max_quantity": 1, "expires_at": "2027-01-01T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # proceed / fix / escalate
+```
+
+Already holding a mandate id? Pass `mandate_id=` instead of `mandate=` — `check_cart` takes either. The lower-level pair is also there when you want the steps separate: `create_mandate(**fields)` returns the signed mandate, and `verify_cart(mandate_id, merchant, items, total_price, ...)` runs the check.
+
+## Check a booking
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_booking(merchant={"name": "Example Air", "domain": "air.example.com"}, price={"total": 412.00}, travelers=["Alex Rivera"], legs=[{"from_airport": "SFO", "to_airport": "JFK", "depart_at": "2027-03-10T08:00:00Z", "arrive_at": "2027-03-10T16:30:00Z"}], mandate={"user_id": "user-123", "travelers": [{"name": "Alex Rivera"}], "origin": {"airport": "SFO"}, "destination": {"airport": "JFK"}, "departure_date": "2027-03-10", "max_total_price": 500.00, "currency": "USD", "expires_at": "2027-03-01T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # gate both capture and ticket issuance on MATCH
+```
+
+The separate steps are `create_booking_mandate(**fields)` and `verify_booking(mandate_id, merchant, price, travelers=..., legs=..., stays=..., fare=...)`.
+
+## Check a reservation
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_reservation(merchant={"name": "Example Table", "domain": "table.example.com"}, date="2027-03-10", time="19:00", party_size=2, name_on_reservation="Alex Rivera", total_amount=40.00, mandate={"user_id": "user-123", "service_description": "Dinner reservation for two", "date": "2027-03-10", "time": "19:00", "party_size": 2, "name_on_reservation": "Alex Rivera", "max_total_price": 60.00, "currency": "USD", "expires_at": "2027-03-09T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # proceed / fix / escalate
+```
+
+The separate steps are `create_reservation_mandate(**fields)` and `verify_reservation(mandate_id, merchant, date, time, party_size, name_on_reservation, total_amount, ...)`.
+
+## What to do with the verdict
+
+`route_verdict` encodes the consumer rules of the Agent Correction Format, and they are deliberately strict:
+
+- **MATCH → proceed.** Capture the payment (or issue the ticket).
+- **BLOCK → fix, narrowly.** Fix only when every correction in the response is a known action that brings the transaction back inside the buyer's existing authorization. Apply exactly those corrections, then resubmit as a new check carrying the earlier check's `record_id` as `previous_record_id`, within the response's `max_attempts` budget.
+- **REVIEW, unknown verdict, unknown action → escalate.** Stop and ask the buyer. Never guess, and never widen the buyer's authorization to make a verdict go away.
+
+```python
+decision, detail = route_verdict(first_verdict)
+if decision == "fix":
+    # ... apply detail["corrections"] to the transaction, nothing else ...
+    second = client.check_cart(..., mandate_id=same_id, previous_record_id=detail["record_id"])
+```
+
+## Offline and mock runs
+
+The client takes an optional `transport` callable, `(path, body) -> (status, dict)`, that replaces the HTTP layer entirely. Point it at canned verdicts and the full mandate → check → route → resubmit loop runs with no network and no API key traffic — that is how this package's own test suite works, and it is the recommended way to rehearse an integration before wiring a real key:
+
+```python
+def stub(path, body):
+    return 200, {"id": "m-1"} if "mandates" in path else {"verdict": "MATCH", "record_id": "r-1"}
+client = ProveCartClient(api_key="test", transport=stub)
+```
+
+Calls made with a sandbox key against the live API behave exactly as in production and stay sealed under that key, separate from live data.
+
+## Links
+
+- Agents and certification: https://provecart.com/agents
+- Correction format standard: https://provecart.com/standards/correction-format
+- API reference: https://api.provecart.com/docs
+
+ProveCart. Prove the cart. Patent pending.

provecart-0.1.0/README.md

@@ -0,0 +1,79 @@
+# provecart
+
+Your agent put the wrong variant in the cart — the wrong size, the wrong model, a quantity nobody asked for — and your user paid for it. By the time anyone noticed, the order had shipped, and the return came out of somebody's pocket. That is the failure this package exists to stop: one check, between what the agent built and the payment, that compares the transaction against what the buyer actually said.
+
+ProveCart is a neutral verification API for agent commerce. You record the buyer's instruction as a signed mandate, send what the agent actually built, and get back a signed verdict — `MATCH`, `REVIEW`, or `BLOCK` — before payment is captured (or, for bookings, before a ticket is issued). A `BLOCK` or `REVIEW` answer carries machine-readable corrections, so the agent can fix what it built and resubmit instead of losing the sale or guessing. Every check is written to a sealed evidence record. ProveCart never holds or moves money.
+
+```bash
+pip install provecart
+```
+
+Standard library only. No dependencies.
+
+## Check a cart
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_cart(merchant={"name": "Example Shop", "domain": "shop.example.com"}, items=[{"name": "Wireless Headphones", "variant": "black", "quantity": 1, "unit_price": 249.99}], total_price=249.99, mandate={"user_id": "user-123", "item_description": "Wireless noise cancelling over-ear headphones", "item_keywords": ["wireless", "headphones"], "category": "electronics", "max_total_price": 300.00, "currency": "USD", "max_quantity": 1, "expires_at": "2027-01-01T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # proceed / fix / escalate
+```
+
+Already holding a mandate id? Pass `mandate_id=` instead of `mandate=` — `check_cart` takes either. The lower-level pair is also there when you want the steps separate: `create_mandate(**fields)` returns the signed mandate, and `verify_cart(mandate_id, merchant, items, total_price, ...)` runs the check.
+
+## Check a booking
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_booking(merchant={"name": "Example Air", "domain": "air.example.com"}, price={"total": 412.00}, travelers=["Alex Rivera"], legs=[{"from_airport": "SFO", "to_airport": "JFK", "depart_at": "2027-03-10T08:00:00Z", "arrive_at": "2027-03-10T16:30:00Z"}], mandate={"user_id": "user-123", "travelers": [{"name": "Alex Rivera"}], "origin": {"airport": "SFO"}, "destination": {"airport": "JFK"}, "departure_date": "2027-03-10", "max_total_price": 500.00, "currency": "USD", "expires_at": "2027-03-01T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # gate both capture and ticket issuance on MATCH
+```
+
+The separate steps are `create_booking_mandate(**fields)` and `verify_booking(mandate_id, merchant, price, travelers=..., legs=..., stays=..., fare=...)`.
+
+## Check a reservation
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_reservation(merchant={"name": "Example Table", "domain": "table.example.com"}, date="2027-03-10", time="19:00", party_size=2, name_on_reservation="Alex Rivera", total_amount=40.00, mandate={"user_id": "user-123", "service_description": "Dinner reservation for two", "date": "2027-03-10", "time": "19:00", "party_size": 2, "name_on_reservation": "Alex Rivera", "max_total_price": 60.00, "currency": "USD", "expires_at": "2027-03-09T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # proceed / fix / escalate
+```
+
+The separate steps are `create_reservation_mandate(**fields)` and `verify_reservation(mandate_id, merchant, date, time, party_size, name_on_reservation, total_amount, ...)`.
+
+## What to do with the verdict
+
+`route_verdict` encodes the consumer rules of the Agent Correction Format, and they are deliberately strict:
+
+- **MATCH → proceed.** Capture the payment (or issue the ticket).
+- **BLOCK → fix, narrowly.** Fix only when every correction in the response is a known action that brings the transaction back inside the buyer's existing authorization. Apply exactly those corrections, then resubmit as a new check carrying the earlier check's `record_id` as `previous_record_id`, within the response's `max_attempts` budget.
+- **REVIEW, unknown verdict, unknown action → escalate.** Stop and ask the buyer. Never guess, and never widen the buyer's authorization to make a verdict go away.
+
+```python
+decision, detail = route_verdict(first_verdict)
+if decision == "fix":
+    # ... apply detail["corrections"] to the transaction, nothing else ...
+    second = client.check_cart(..., mandate_id=same_id, previous_record_id=detail["record_id"])
+```
+
+## Offline and mock runs
+
+The client takes an optional `transport` callable, `(path, body) -> (status, dict)`, that replaces the HTTP layer entirely. Point it at canned verdicts and the full mandate → check → route → resubmit loop runs with no network and no API key traffic — that is how this package's own test suite works, and it is the recommended way to rehearse an integration before wiring a real key:
+
+```python
+def stub(path, body):
+    return 200, {"id": "m-1"} if "mandates" in path else {"verdict": "MATCH", "record_id": "r-1"}
+client = ProveCartClient(api_key="test", transport=stub)
+```
+
+Calls made with a sandbox key against the live API behave exactly as in production and stay sealed under that key, separate from live data.
+
+## Links
+
+- Agents and certification: https://provecart.com/agents
+- Correction format standard: https://provecart.com/standards/correction-format
+- API reference: https://api.provecart.com/docs
+
+ProveCart. Prove the cart. Patent pending.

provecart-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provecart"
+version = "0.1.0"
+description = "ProveCart client: check an AI agent's cart, booking, or reservation against the buyer's signed instructions before payment is captured."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {text = "MIT"}
+keywords = ["ai-agents", "agent-commerce", "verification", "payments", "provecart"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://provecart.com"
+Documentation = "https://provecart.com/agents"
+"Correction format" = "https://provecart.com/standards/correction-format"
+
+[tool.setuptools.packages.find]
+where = ["src"]

provecart-0.1.0/setup.cfg

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

provecart-0.1.0/src/provecart/__init__.py

@@ -0,0 +1,21 @@
+"""ProveCart client: verify an agent's cart, booking, or reservation
+against the buyer's signed instructions before payment is captured.
+"""
+from .client import (
+    KNOWN_ACTIONS,
+    Client,
+    ProveCartClient,
+    ProveCartError,
+    route_verdict,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "KNOWN_ACTIONS",
+    "Client",
+    "ProveCartClient",
+    "ProveCartError",
+    "route_verdict",
+    "__version__",
+]

provecart-0.1.0/src/provecart/client.py

@@ -0,0 +1,286 @@
+"""ProveCart client + verdict routing.
+
+Self-contained (standard library only). Implements the consumer rules
+of the Agent Correction Format (ACF v0.2, com.provecart.conformity):
+
+  MATCH             -> proceed to payment (or ticket issuance).
+  BLOCK + fixes     -> apply ONLY repairs that bring the transaction
+                       INTO the buyer's existing authorization, then
+                       resubmit as a new check carrying
+                       previous_record_id, within max_attempts.
+  REVIEW / unknown  -> stop and escalate to the buyer. Never guess,
+  action               never widen the authorization.
+
+API contract (https://api.provecart.com, X-API-Key header):
+  POST /mandates              -> signed cart mandate (use its "id")
+  POST /verify                -> cart verdict
+  POST /booking-mandates      -> signed booking mandate
+  POST /verify-booking        -> booking verdict
+  POST /reservation-mandates  -> signed reservation mandate
+  POST /verify-reservation    -> reservation verdict
+
+Every verify response carries {verdict, corrections[], max_attempts,
+record_id, verdict_token, ...}. A corrected resubmission is a new
+verify call against the same mandate with previous_record_id set to
+the earlier check's record_id.
+"""
+import json
+import urllib.error
+import urllib.request
+
+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_BASE_URL = "https://api.provecart.com"
+
+
+class ProveCartError(RuntimeError):
+    """Raised when the ProveCart API returns a non-200 status."""
+
+
+class ProveCartClient:
+    """Client for the ProveCart verification API.
+
+    Parameters:
+        api_key: integrator API key, sent as the X-API-Key header.
+        base_url: API base URL (default https://api.provecart.com).
+        transport: optional callable ``(path, body) -> (status, dict)``
+            replacing the HTTP layer. Intended for offline tests and
+            rehearsal runs; when supplied, no network call is made.
+        timeout: HTTP timeout in seconds for the default transport.
+    """
+
+    def __init__(self, api_key, base_url=DEFAULT_BASE_URL,
+                 transport=None, timeout=20):
+        self.api_key = api_key
+        self.base = base_url.rstrip("/")
+        self._transport = transport
+        self.timeout = timeout
+
+    # -- transport ---------------------------------------------------
+    def _post(self, path, body, extra_headers=None):
+        if self._transport is not None:
+            return self._transport(path, body)
+        headers = {"Content-Type": "application/json",
+                   "X-API-Key": self.api_key}
+        if extra_headers:
+            headers.update(extra_headers)
+        req = urllib.request.Request(
+            self.base + path,
+            data=json.dumps(body).encode(),
+            method="POST",
+            headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.status, json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            try:
+                return e.code, json.loads(e.read() or b"{}")
+            except Exception:
+                return e.code, {}
+
+    def _post_ok(self, path, body, what, idempotency_key=None):
+        extra = ({"Idempotency-Key": idempotency_key}
+                 if idempotency_key else None)
+        status, out = self._post(path, body, extra_headers=extra) \
+            if extra else self._post(path, body)
+        if status != 200:
+            raise ProveCartError(f"{what} failed: {status} {out}")
+        return out
+
+    # -- mandate creation ---------------------------------------------
+    def create_mandate(self, **fields):
+        """Create a signed cart mandate: POST /mandates.
+
+        Required fields include user_id, item_description, category,
+        max_total_price and expires_at; item_keywords, currency,
+        max_quantity, merchant_allowlist/blocklist, brand and
+        variant_constraints are also accepted. Returns the signed
+        mandate dict; use its "id" as mandate_id.
+        """
+        return self._post_ok("/mandates", fields, "mandate creation")
+
+    # Backwards-compatible alias: the cart mandate is the original kind.
+    create_cart_mandate = create_mandate
+
+    def create_booking_mandate(self, **fields):
+        """Create a signed booking mandate: POST /booking-mandates.
+
+        Required fields include user_id, travelers, origin,
+        destination, departure_date, max_total_price and expires_at.
+        Returns the signed mandate dict; use its "id".
+        """
+        return self._post_ok("/booking-mandates", fields,
+                             "booking mandate creation")
+
+    def create_reservation_mandate(self, **fields):
+        """Create a signed reservation mandate:
+        POST /reservation-mandates.
+
+        Required fields include user_id, service_description, date,
+        time, party_size, name_on_reservation, max_total_price and
+        expires_at. Returns the signed mandate dict; use its "id".
+        """
+        return self._post_ok("/reservation-mandates", fields,
+                             "reservation mandate creation")
+
+    # -- verification ---------------------------------------------------
+    def verify_cart(self, mandate_id, merchant, items, total_price,
+                    currency="USD", tax=0.0, shipping=0.0, fees=0.0,
+                    previous_record_id=None, cart_changed=False,
+                    idempotency_key=None):
+        """Verify a cart: POST /verify. Returns the verdict dict."""
+        body = {"mandate_id": mandate_id, "merchant": merchant,
+                "items": items, "total_price": total_price,
+                "currency": currency, "tax": tax, "shipping": shipping,
+                "fees": fees, "cart_changed": cart_changed}
+        if previous_record_id:
+            body["previous_record_id"] = previous_record_id
+        return self._post_ok("/verify", body, "verify",
+                             idempotency_key=idempotency_key)
+
+    def verify_booking(self, mandate_id, merchant, price,
+                       travelers=None, legs=None, stays=None, fare=None,
+                       currency="USD", previous_record_id=None,
+                       booking_changed=False, idempotency_key=None):
+        """Verify a booking: POST /verify-booking.
+
+        ``price`` is a dict with at least {"total": ...}; ``legs``
+        items carry from_airport, to_airport, depart_at, arrive_at;
+        ``travelers`` is a list of traveler names. Returns the
+        verdict dict.
+        """
+        body = {"mandate_id": mandate_id, "merchant": merchant,
+                "price": price, "currency": currency,
+                "booking_changed": booking_changed}
+        if travelers is not None:
+            body["travelers"] = travelers
+        if legs is not None:
+            body["legs"] = legs
+        if stays is not None:
+            body["stays"] = stays
+        if fare is not None:
+            body["fare"] = fare
+        if previous_record_id:
+            body["previous_record_id"] = previous_record_id
+        return self._post_ok("/verify-booking", body, "verify-booking",
+                             idempotency_key=idempotency_key)
+
+    def verify_reservation(self, mandate_id, merchant, date, time,
+                           party_size, name_on_reservation, total_amount,
+                           provider_name=None, location=None,
+                           deposit_amount=0.0, currency="USD",
+                           cancellation=None, previous_record_id=None,
+                           reservation_changed=False,
+                           idempotency_key=None):
+        """Verify a reservation: POST /verify-reservation.
+        Returns the verdict dict."""
+        body = {"mandate_id": mandate_id, "merchant": merchant,
+                "date": date, "time": time, "party_size": party_size,
+                "name_on_reservation": name_on_reservation,
+                "deposit_amount": deposit_amount,
+                "total_amount": total_amount, "currency": currency,
+                "reservation_changed": reservation_changed}
+        if provider_name is not None:
+            body["provider_name"] = provider_name
+        if location is not None:
+            body["location"] = location
+        if cancellation is not None:
+            body["cancellation"] = cancellation
+        if previous_record_id:
+            body["previous_record_id"] = previous_record_id
+        return self._post_ok("/verify-reservation", body,
+                             "verify-reservation",
+                             idempotency_key=idempotency_key)
+
+    # -- one-call checks: create-or-take a mandate, then verify --------
+    def _resolve_mandate_id(self, mandate_id, mandate, creator):
+        if mandate is not None:
+            created = creator(**mandate)
+            return created["id"]
+        if not mandate_id:
+            raise ValueError(
+                "pass mandate_id= or mandate={...} so the check has a "
+                "signed instruction to compare against")
+        return mandate_id
+
+    def check_cart(self, merchant, items, total_price, *,
+                   mandate_id=None, mandate=None, **verify_kwargs):
+        """Check a cart, creating the mandate first when ``mandate``
+        (a dict of mandate fields) is given instead of ``mandate_id``.
+        Returns the verdict response dict."""
+        mid = self._resolve_mandate_id(mandate_id, mandate,
+                                       self.create_mandate)
+        return self.verify_cart(mid, merchant, items, total_price,
+                                **verify_kwargs)
+
+    def check_booking(self, merchant, price, *, mandate_id=None,
+                      mandate=None, **verify_kwargs):
+        """Check a booking, creating the booking mandate first when
+        ``mandate`` is given instead of ``mandate_id``.
+        Returns the verdict response dict."""
+        mid = self._resolve_mandate_id(mandate_id, mandate,
+                                       self.create_booking_mandate)
+        return self.verify_booking(mid, merchant, price, **verify_kwargs)
+
+    def check_reservation(self, merchant, date, time, party_size,
+                          name_on_reservation, total_amount, *,
+                          mandate_id=None, mandate=None, **verify_kwargs):
+        """Check a reservation, creating the reservation mandate
+        first when ``mandate`` is given instead of ``mandate_id``.
+        Returns the verdict response dict."""
+        mid = self._resolve_mandate_id(mandate_id, mandate,
+                                       self.create_reservation_mandate)
+        return self.verify_reservation(
+            mid, merchant, date, time, party_size, name_on_reservation,
+            total_amount, **verify_kwargs)
+
+
+# Short alias.
+Client = ProveCartClient
+
+
+def route_verdict(response, attempt=1):
+    """Return (decision, detail): decision is 'proceed', 'fix' or
+    'escalate'.
+
+    'fix' is returned only when the verdict is BLOCK, every
+    correction is a known action, no correction is marked
+    non-correctable, and the retry budget (max_attempts) has not
+    been spent. A fix never widens the buyer's authorization: apply
+    only the listed corrections, then resubmit carrying the
+    response's record_id as previous_record_id. Anything else —
+    REVIEW, an unknown verdict, an unknown action — escalates to
+    the buyer.
+    """
+    verdict = response.get("verdict")
+    if verdict == "MATCH":
+        return "proceed", {"record_id": response.get("record_id")}
+    if verdict == "BLOCK":
+        corrections = response.get("corrections") or []
+        max_attempts = response.get("max_attempts")
+        budget_ok = max_attempts is None or attempt < max_attempts
+        usable = (
+            bool(corrections)
+            and all(c.get("action") in KNOWN_ACTIONS for c in corrections)
+            and all(c.get("correctable", True) for c in corrections)
+        )
+        if usable and budget_ok:
+            return "fix", {"corrections": corrections,
+                           "record_id": response.get("record_id"),
+                           "max_attempts": max_attempts}
+        reason = "BLOCK without usable corrections"
+        if usable and not budget_ok:
+            reason = "BLOCK retry budget (max_attempts) spent"
+        return "escalate", {"reason": reason,
+                            "record_id": response.get("record_id")}
+    return "escalate", {"reason": f"verdict {verdict} needs the buyer",
+                        "record_id": response.get("record_id")}

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

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: provecart
+Version: 0.1.0
+Summary: ProveCart client: check an AI agent's cart, booking, or reservation against the buyer's signed instructions before payment is captured.
+License: MIT
+Project-URL: Homepage, https://provecart.com
+Project-URL: Documentation, https://provecart.com/agents
+Project-URL: Correction format, https://provecart.com/standards/correction-format
+Keywords: ai-agents,agent-commerce,verification,payments,provecart
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# provecart
+
+Your agent put the wrong variant in the cart — the wrong size, the wrong model, a quantity nobody asked for — and your user paid for it. By the time anyone noticed, the order had shipped, and the return came out of somebody's pocket. That is the failure this package exists to stop: one check, between what the agent built and the payment, that compares the transaction against what the buyer actually said.
+
+ProveCart is a neutral verification API for agent commerce. You record the buyer's instruction as a signed mandate, send what the agent actually built, and get back a signed verdict — `MATCH`, `REVIEW`, or `BLOCK` — before payment is captured (or, for bookings, before a ticket is issued). A `BLOCK` or `REVIEW` answer carries machine-readable corrections, so the agent can fix what it built and resubmit instead of losing the sale or guessing. Every check is written to a sealed evidence record. ProveCart never holds or moves money.
+
+```bash
+pip install provecart
+```
+
+Standard library only. No dependencies.
+
+## Check a cart
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_cart(merchant={"name": "Example Shop", "domain": "shop.example.com"}, items=[{"name": "Wireless Headphones", "variant": "black", "quantity": 1, "unit_price": 249.99}], total_price=249.99, mandate={"user_id": "user-123", "item_description": "Wireless noise cancelling over-ear headphones", "item_keywords": ["wireless", "headphones"], "category": "electronics", "max_total_price": 300.00, "currency": "USD", "max_quantity": 1, "expires_at": "2027-01-01T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # proceed / fix / escalate
+```
+
+Already holding a mandate id? Pass `mandate_id=` instead of `mandate=` — `check_cart` takes either. The lower-level pair is also there when you want the steps separate: `create_mandate(**fields)` returns the signed mandate, and `verify_cart(mandate_id, merchant, items, total_price, ...)` runs the check.
+
+## Check a booking
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_booking(merchant={"name": "Example Air", "domain": "air.example.com"}, price={"total": 412.00}, travelers=["Alex Rivera"], legs=[{"from_airport": "SFO", "to_airport": "JFK", "depart_at": "2027-03-10T08:00:00Z", "arrive_at": "2027-03-10T16:30:00Z"}], mandate={"user_id": "user-123", "travelers": [{"name": "Alex Rivera"}], "origin": {"airport": "SFO"}, "destination": {"airport": "JFK"}, "departure_date": "2027-03-10", "max_total_price": 500.00, "currency": "USD", "expires_at": "2027-03-01T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # gate both capture and ticket issuance on MATCH
+```
+
+The separate steps are `create_booking_mandate(**fields)` and `verify_booking(mandate_id, merchant, price, travelers=..., legs=..., stays=..., fare=...)`.
+
+## Check a reservation
+
+```python
+from provecart import ProveCartClient, route_verdict
+client = ProveCartClient(api_key="YOUR_API_KEY")
+verdict = client.check_reservation(merchant={"name": "Example Table", "domain": "table.example.com"}, date="2027-03-10", time="19:00", party_size=2, name_on_reservation="Alex Rivera", total_amount=40.00, mandate={"user_id": "user-123", "service_description": "Dinner reservation for two", "date": "2027-03-10", "time": "19:00", "party_size": 2, "name_on_reservation": "Alex Rivera", "max_total_price": 60.00, "currency": "USD", "expires_at": "2027-03-09T00:00:00Z"})
+decision, detail = route_verdict(verdict)  # proceed / fix / escalate
+```
+
+The separate steps are `create_reservation_mandate(**fields)` and `verify_reservation(mandate_id, merchant, date, time, party_size, name_on_reservation, total_amount, ...)`.
+
+## What to do with the verdict
+
+`route_verdict` encodes the consumer rules of the Agent Correction Format, and they are deliberately strict:
+
+- **MATCH → proceed.** Capture the payment (or issue the ticket).
+- **BLOCK → fix, narrowly.** Fix only when every correction in the response is a known action that brings the transaction back inside the buyer's existing authorization. Apply exactly those corrections, then resubmit as a new check carrying the earlier check's `record_id` as `previous_record_id`, within the response's `max_attempts` budget.
+- **REVIEW, unknown verdict, unknown action → escalate.** Stop and ask the buyer. Never guess, and never widen the buyer's authorization to make a verdict go away.
+
+```python
+decision, detail = route_verdict(first_verdict)
+if decision == "fix":
+    # ... apply detail["corrections"] to the transaction, nothing else ...
+    second = client.check_cart(..., mandate_id=same_id, previous_record_id=detail["record_id"])
+```
+
+## Offline and mock runs
+
+The client takes an optional `transport` callable, `(path, body) -> (status, dict)`, that replaces the HTTP layer entirely. Point it at canned verdicts and the full mandate → check → route → resubmit loop runs with no network and no API key traffic — that is how this package's own test suite works, and it is the recommended way to rehearse an integration before wiring a real key:
+
+```python
+def stub(path, body):
+    return 200, {"id": "m-1"} if "mandates" in path else {"verdict": "MATCH", "record_id": "r-1"}
+client = ProveCartClient(api_key="test", transport=stub)
+```
+
+Calls made with a sandbox key against the live API behave exactly as in production and stay sealed under that key, separate from live data.
+
+## Links
+
+- Agents and certification: https://provecart.com/agents
+- Correction format standard: https://provecart.com/standards/correction-format
+- API reference: https://api.provecart.com/docs
+
+ProveCart. Prove the cart. Patent pending.

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

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/provecart/__init__.py
+src/provecart/client.py
+src/provecart.egg-info/PKG-INFO
+src/provecart.egg-info/SOURCES.txt
+src/provecart.egg-info/dependency_links.txt
+src/provecart.egg-info/top_level.txt
+tests/test_client.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+provecart

provecart-0.1.0/tests/test_client.py

@@ -0,0 +1,259 @@
+"""Offline unit tests for the provecart client.
+
+A stub transport replaces the HTTP layer: no network, no live calls.
+Covers MATCH / BLOCK-fix / REVIEW routing and previous_record_id
+chaining for carts, bookings, and reservations.
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from provecart import ProveCartClient, route_verdict  # noqa: E402
+
+
+class StubTransport:
+    """Records every (path, body) call and replays queued responses."""
+
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.calls = []
+
+    def __call__(self, path, body):
+        self.calls.append((path, dict(body)))
+        return self.responses.pop(0)
+
+
+def mandate_ok(mid="m-1"):
+    return (200, {"id": mid, "signature": "sig"})
+
+
+MERCHANT = {"name": "Example Shop", "domain": "shop.example.com"}
+CART_MANDATE = {
+    "user_id": "user-123",
+    "item_description": "Wireless noise cancelling over-ear headphones",
+    "item_keywords": ["wireless", "headphones"],
+    "category": "electronics",
+    "max_total_price": 300.00,
+    "currency": "USD",
+    "max_quantity": 1,
+    "expires_at": "2027-01-01T00:00:00Z",
+}
+ITEMS = [{"name": "Wireless Headphones", "variant": "black",
+          "quantity": 1, "unit_price": 249.99}]
+
+
+def test_match_routes_proceed():
+    stub = StubTransport([mandate_ok(),
+                          (200, {"verdict": "MATCH", "record_id": "r-1"})])
+    client = ProveCartClient("test-key", transport=stub)
+    out = client.check_cart(MERCHANT, ITEMS, 249.99, mandate=CART_MANDATE)
+    assert out["verdict"] == "MATCH"
+    assert stub.calls[0][0] == "/mandates"
+    assert stub.calls[1][0] == "/verify"
+    assert stub.calls[1][1]["mandate_id"] == "m-1"
+    decision, detail = route_verdict(out)
+    assert decision == "proceed"
+    assert detail["record_id"] == "r-1"
+
+
+def test_check_cart_with_existing_mandate_id_skips_creation():
+    stub = StubTransport([(200, {"verdict": "MATCH", "record_id": "r-9"})])
+    client = ProveCartClient("test-key", transport=stub)
+    out = client.check_cart(MERCHANT, ITEMS, 249.99, mandate_id="m-42")
+    assert out["verdict"] == "MATCH"
+    assert len(stub.calls) == 1
+    assert stub.calls[0][1]["mandate_id"] == "m-42"
+
+
+def test_block_with_known_corrections_routes_fix():
+    resp = {"verdict": "BLOCK", "record_id": "r-2", "max_attempts": 3,
+            "corrections": [
+                {"action": "change_variant", "dimension": "variant",
+                 "expected": "black", "actual": "white"},
+                {"action": "reduce_quantity", "dimension": "quantity",
+                 "expected": 1, "actual": 2}]}
+    decision, detail = route_verdict(resp)
+    assert decision == "fix"
+    assert detail["record_id"] == "r-2"
+    assert detail["max_attempts"] == 3
+    assert detail["corrections"] == resp["corrections"]
+
+
+def test_block_fix_then_resubmit_chains_previous_record_id():
+    blocked = (200, {"verdict": "BLOCK", "record_id": "r-2",
+                     "max_attempts": 3,
+                     "corrections": [{"action": "change_variant"}]})
+    matched = (200, {"verdict": "MATCH", "record_id": "r-3"})
+    stub = StubTransport([blocked, matched])
+    client = ProveCartClient("test-key", transport=stub)
+    first = client.verify_cart("m-1", MERCHANT, ITEMS, 249.99)
+    decision, detail = route_verdict(first)
+    assert decision == "fix"
+    fixed = [{"name": "Wireless Headphones", "variant": "black",
+              "quantity": 1, "unit_price": 249.99}]
+    second = client.verify_cart(
+        "m-1", MERCHANT, fixed, 249.99,
+        previous_record_id=detail["record_id"], cart_changed=True)
+    assert second["verdict"] == "MATCH"
+    assert stub.calls[1][1]["previous_record_id"] == "r-2"
+    assert stub.calls[1][1]["cart_changed"] is True
+    assert "previous_record_id" not in stub.calls[0][1]
+
+
+def test_review_routes_escalate():
+    decision, detail = route_verdict(
+        {"verdict": "REVIEW", "record_id": "r-4"})
+    assert decision == "escalate"
+    assert detail["record_id"] == "r-4"
+
+
+def test_unknown_verdict_routes_escalate():
+    decision, _ = route_verdict({"verdict": "SOMETHING_ELSE"})
+    assert decision == "escalate"
+    decision, _ = route_verdict({})
+    assert decision == "escalate"
+
+
+def test_block_with_unknown_action_routes_escalate():
+    resp = {"verdict": "BLOCK", "record_id": "r-5", "max_attempts": 3,
+            "corrections": [{"action": "raise_the_budget"}]}
+    decision, _ = route_verdict(resp)
+    assert decision == "escalate"
+
+
+def test_block_without_corrections_routes_escalate():
+    decision, _ = route_verdict(
+        {"verdict": "BLOCK", "record_id": "r-6", "corrections": []})
+    assert decision == "escalate"
+
+
+def test_block_non_correctable_routes_escalate():
+    resp = {"verdict": "BLOCK", "record_id": "r-7", "max_attempts": 3,
+            "corrections": [{"action": "remove_item",
+                             "correctable": False}]}
+    decision, _ = route_verdict(resp)
+    assert decision == "escalate"
+
+
+def test_block_after_budget_spent_routes_escalate():
+    resp = {"verdict": "BLOCK", "record_id": "r-8", "max_attempts": 3,
+            "corrections": [{"action": "remove_item"}]}
+    decision, detail = route_verdict(resp, attempt=3)
+    assert decision == "escalate"
+    assert "max_attempts" in detail["reason"]
+
+
+def test_booking_check_creates_mandate_and_verifies():
+    stub = StubTransport([mandate_ok("bm-1"),
+                          (200, {"verdict": "MATCH", "record_id": "br-1"})])
+    client = ProveCartClient("test-key", transport=stub)
+    mandate = {
+        "user_id": "user-123",
+        "travelers": [{"name": "Alex Rivera"}],
+        "origin": {"airport": "SFO"},
+        "destination": {"airport": "JFK"},
+        "departure_date": "2027-03-10",
+        "max_total_price": 500.00,
+        "expires_at": "2027-03-01T00:00:00Z",
+    }
+    legs = [{"from_airport": "SFO", "to_airport": "JFK",
+             "depart_at": "2027-03-10T08:00:00Z",
+             "arrive_at": "2027-03-10T16:30:00Z"}]
+    out = client.check_booking(
+        MERCHANT, {"total": 412.00}, mandate=mandate,
+        travelers=["Alex Rivera"], legs=legs)
+    assert out["verdict"] == "MATCH"
+    assert stub.calls[0][0] == "/booking-mandates"
+    assert stub.calls[1][0] == "/verify-booking"
+    assert stub.calls[1][1]["mandate_id"] == "bm-1"
+    assert stub.calls[1][1]["price"] == {"total": 412.00}
+    decision, _ = route_verdict(out)
+    assert decision == "proceed"
+
+
+def test_booking_resubmit_chains_previous_record_id():
+    stub = StubTransport([
+        (200, {"verdict": "BLOCK", "record_id": "br-2", "max_attempts": 3,
+               "corrections": [{"action": "change_airport"}]}),
+        (200, {"verdict": "MATCH", "record_id": "br-3"})])
+    client = ProveCartClient("test-key", transport=stub)
+    first = client.verify_booking("bm-1", MERCHANT, {"total": 412.00})
+    decision, detail = route_verdict(first)
+    assert decision == "fix"
+    client.verify_booking("bm-1", MERCHANT, {"total": 399.00},
+                          previous_record_id=detail["record_id"],
+                          booking_changed=True)
+    assert stub.calls[1][1]["previous_record_id"] == "br-2"
+    assert stub.calls[1][1]["booking_changed"] is True
+
+
+def test_reservation_check_creates_mandate_and_verifies():
+    stub = StubTransport([mandate_ok("rm-1"),
+                          (200, {"verdict": "MATCH", "record_id": "rr-1"})])
+    client = ProveCartClient("test-key", transport=stub)
+    mandate = {
+        "user_id": "user-123",
+        "service_description": "Dinner reservation for two",
+        "date": "2027-03-10", "time": "19:00", "party_size": 2,
+        "name_on_reservation": "Alex Rivera",
+        "max_total_price": 60.00,
+        "expires_at": "2027-03-09T00:00:00Z",
+    }
+    out = client.check_reservation(
+        MERCHANT, "2027-03-10", "19:00", 2, "Alex Rivera", 40.00,
+        mandate=mandate)
+    assert out["verdict"] == "MATCH"
+    assert stub.calls[0][0] == "/reservation-mandates"
+    assert stub.calls[1][0] == "/verify-reservation"
+    assert stub.calls[1][1]["mandate_id"] == "rm-1"
+    assert stub.calls[1][1]["total_amount"] == 40.00
+
+
+def test_reservation_block_routes_fix_and_chains():
+    stub = StubTransport([
+        (200, {"verdict": "BLOCK", "record_id": "rr-2", "max_attempts": 3,
+               "corrections": [{"action": "change_party_size"}]}),
+        (200, {"verdict": "REVIEW", "record_id": "rr-3"})])
+    client = ProveCartClient("test-key", transport=stub)
+    first = client.verify_reservation(
+        "rm-1", MERCHANT, "2027-03-10", "19:00", 4, "Alex Rivera", 40.00)
+    decision, detail = route_verdict(first)
+    assert decision == "fix"
+    second = client.verify_reservation(
+        "rm-1", MERCHANT, "2027-03-10", "19:00", 2, "Alex Rivera", 40.00,
+        previous_record_id=detail["record_id"], reservation_changed=True)
+    assert stub.calls[1][1]["previous_record_id"] == "rr-2"
+    decision2, _ = route_verdict(second)
+    assert decision2 == "escalate"
+
+
+def test_create_mandate_helpers_hit_the_three_endpoints():
+    stub = StubTransport([mandate_ok("a"), mandate_ok("b"),
+                          mandate_ok("c")])
+    client = ProveCartClient("test-key", transport=stub)
+    assert client.create_mandate(**CART_MANDATE)["id"] == "a"
+    assert client.create_booking_mandate(user_id="u")["id"] == "b"
+    assert client.create_reservation_mandate(user_id="u")["id"] == "c"
+    paths = [c[0] for c in stub.calls]
+    assert paths == ["/mandates", "/booking-mandates",
+                     "/reservation-mandates"]
+
+
+def test_api_error_raises():
+    stub = StubTransport([(403, {"detail": "bad key"})])
+    client = ProveCartClient("test-key", transport=stub)
+    try:
+        client.create_mandate(**CART_MANDATE)
+    except RuntimeError:
+        return
+    raise AssertionError("expected RuntimeError on non-200")
+
+
+def test_check_requires_mandate_or_id():
+    client = ProveCartClient("test-key", transport=StubTransport([]))
+    try:
+        client.check_cart(MERCHANT, ITEMS, 249.99)
+    except ValueError:
+        return
+    raise AssertionError("expected ValueError without a mandate")