colvo 0.1.0__tar.gz

colvo-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: colvo
+Version: 0.1.0
+Summary: COLVO SDK — propose agent actions through Guard, report observations, read decisions. Standard library only.
+License: MIT
+Project-URL: Homepage, https://colvo.app/docs/move-to-guard
+Keywords: colvo,ai agents,guardrails,stripe,refunds,human in the loop
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# colvo (Python)
+
+The agent proposes, COLVO decides (ALLOW / REVIEW / HOLD / DENY), executes exactly once and verifies against the provider.
+Standard library only, Python 3.9+. Guide: https://colvo.app/docs/move-to-guard
+
+```python
+import os
+from colvo import Colvo, ColvoError, message_for
+
+colvo = Colvo(os.environ["COLVO_AGENT_KEY"])
+op = colvo.operations.propose({
+    "mandate_id": mandate_id, "source_request_id": ticket_id, "action": "refund.create",
+    "parameters": {"payment_id": "pi_…", "amount_minor": 5000, "currency": "eur"},
+})
+reply(message_for(op))
+```
+
+- `operations.propose(proposal, idempotency_key=None)` — safe retries with a deterministic idempotency key.
+- `operations.get(id)`, `operations.wait_for(id, until="verified")`, `observations.report(obs)`, `mandates.create(m)` (backend key).
+- Errors raise `ColvoError(status, code, message, details)`.
+
+Tests: `python3 -m unittest discover -s sdks/python/tests`.

colvo-0.1.0/README.md

@@ -0,0 +1,22 @@
+# colvo (Python)
+
+The agent proposes, COLVO decides (ALLOW / REVIEW / HOLD / DENY), executes exactly once and verifies against the provider.
+Standard library only, Python 3.9+. Guide: https://colvo.app/docs/move-to-guard
+
+```python
+import os
+from colvo import Colvo, ColvoError, message_for
+
+colvo = Colvo(os.environ["COLVO_AGENT_KEY"])
+op = colvo.operations.propose({
+    "mandate_id": mandate_id, "source_request_id": ticket_id, "action": "refund.create",
+    "parameters": {"payment_id": "pi_…", "amount_minor": 5000, "currency": "eur"},
+})
+reply(message_for(op))
+```
+
+- `operations.propose(proposal, idempotency_key=None)` — safe retries with a deterministic idempotency key.
+- `operations.get(id)`, `operations.wait_for(id, until="verified")`, `observations.report(obs)`, `mandates.create(m)` (backend key).
+- Errors raise `ColvoError(status, code, message, details)`.
+
+Tests: `python3 -m unittest discover -s sdks/python/tests`.

colvo-0.1.0/colvo/__init__.py

@@ -0,0 +1,8 @@
+"""COLVO SDK — the agent proposes, COLVO decides, executes exactly once and verifies.
+
+Standard library only (Python 3.9+). Docs: https://colvo.app/docs/move-to-guard
+"""
+from .client import Colvo, ColvoError, idempotency_key_for, message_for
+
+__all__ = ["Colvo", "ColvoError", "idempotency_key_for", "message_for"]
+__version__ = "0.1.0"

colvo-0.1.0/colvo/client.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Optional
+
+Json = Dict[str, Any]
+
+
+class ColvoError(Exception):
+    """An API error: ``status`` (0 = network), ``code`` (e.g. ``business_key_conflict``), ``details``."""
+
+    def __init__(self, status: int, code: str, message: str, details: Optional[Json] = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = details or {}
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"ColvoError(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+def idempotency_key_for(proposal: Json) -> str:
+    """Same effect -> same key: a retry returns the original operation instead of doubling it."""
+    p = proposal.get("parameters", {})
+    target = p.get("payment_id") or p.get("subscription_id") or "target"
+    if proposal["action"] == "refund.create":
+        detail = f"{p.get('amount_minor')}{p.get('currency', '')}"
+    else:
+        detail = p.get("mode", "period_end")
+    return f"{proposal['source_request_id']}:{proposal['action']}:{target}:{detail}"
+
+
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], "tuple[int, Dict[str, str], bytes]"]
+
+
+def _urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float):
+    req = urllib.request.Request(url, data=body, method=method, headers=headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:  # noqa: S310 (https base URL by default)
+            return res.status, dict(res.headers), res.read()
+    except urllib.error.HTTPError as e:
+        return e.code, dict(e.headers or {}), e.read()
+
+
+class _Section:
+    def __init__(self, client: "Colvo"):
+        self._c = client
+
+
+class _Mandates(_Section):
+    def create(self, mandate: Json) -> Json:
+        """Your trusted backend registers authority (backend key). Not retried: a mandate is not idempotent."""
+        return self._c._request("POST", "/v1/mandates", body=mandate)
+
+
+class _Operations(_Section):
+    def propose(self, proposal: Json, idempotency_key: Optional[str] = None) -> Json:
+        """The agent proposes; the response carries the decision. Safe to retry (same effect, same key)."""
+        return self._c._request("POST", "/v1/operations", body=proposal, idempotency_key=idempotency_key or idempotency_key_for(proposal), retry=True)
+
+    def get(self, operation_id: str) -> Json:
+        return self._c._request("GET", f"/v1/operations/{urllib.parse.quote(operation_id)}", retry=True)
+
+    def wait_for(self, operation_id: str, until: str = "verified", timeout: float = 60.0, interval: float = 1.0) -> Json:
+        """Poll until ``decided`` | ``executed`` | ``verified``; returns the last state on timeout."""
+        deadline = time.monotonic() + timeout
+        while True:
+            op = self.get(operation_id)
+            if _reached(op, until) or time.monotonic() >= deadline:
+                return op
+            time.sleep(interval)
+
+
+class _Observations(_Section):
+    def report(self, observation: Json) -> Json:
+        """Observation mode: report an action the agent took itself (or chose not to). Not retried."""
+        return self._c._request("POST", "/v1/observations", body=observation)
+
+    def get(self, observation_id: str) -> Json:
+        return self._c._request("GET", f"/v1/observations/{urllib.parse.quote(observation_id)}", retry=True)
+
+
+class Colvo:
+    """``Colvo(api_key="cak_...")``. Backend key for mandates, agent key for proposals and observations."""
+
+    def __init__(self, api_key: str, base_url: str = "https://colvo.app", timeout: float = 15.0, max_retries: int = 2, transport: Optional[Transport] = None):
+        if not api_key:
+            raise ValueError("Colvo: api_key is required")
+        self._key = api_key
+        self._base = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._transport = transport or _urllib_transport
+        self.mandates = _Mandates(self)
+        self.operations = _Operations(self)
+        self.observations = _Observations(self)
+
+    def _request(self, method: str, path: str, body: Optional[Json] = None, idempotency_key: Optional[str] = None, retry: bool = False) -> Json:
+        headers = {"authorization": f"Bearer {self._key}", "accept": "application/json", "user-agent": "colvo-sdk-python/0.1.0"}
+        data = None
+        if body is not None:
+            headers["content-type"] = "application/json"
+            data = json.dumps(body).encode()
+        if idempotency_key:
+            headers["idempotency-key"] = idempotency_key
+        retries = self._max_retries if retry else 0
+        attempt = 0
+        while True:
+            try:
+                status, res_headers, raw = self._transport(method, f"{self._base}{path}", headers, data, self._timeout)
+            except Exception as e:  # network error, timeout
+                if attempt < retries:
+                    time.sleep(0.3 * 2 ** attempt)
+                    attempt += 1
+                    continue
+                raise ColvoError(0, "network_error", f"COLVO unreachable: {e}") from e
+            try:
+                payload = json.loads(raw.decode() or "{}")
+            except ValueError:
+                payload = {"message": raw.decode(errors="replace")}
+            if 200 <= status < 300:
+                return payload
+            if (status == 429 or status >= 500) and attempt < retries:
+                wait = res_headers.get("retry-after") or res_headers.get("Retry-After")
+                time.sleep(float(wait) if wait else 0.3 * 2 ** attempt)
+                attempt += 1
+                continue
+            code = payload.pop("error", f"http_{status}")
+            message = payload.pop("message", f"HTTP {status}")
+            raise ColvoError(status, code, message, payload)
+
+
+def _reached(op: Json, until: str) -> bool:
+    approval = op.get("approval") or {}
+    if op.get("decision") in ("DENY", "HOLD"):
+        return True
+    if approval and approval.get("decision") not in ("PENDING", "APPROVED"):
+        return True
+    if until == "decided":
+        return op.get("decision") == "ALLOW" or approval.get("decision") == "APPROVED"
+    executed = op.get("exec_state") in ("ACKNOWLEDGED", "FAILED", "CANCELED_BEFORE_SEND", "PROVIDER_REVIEW")
+    if until == "executed":
+        return executed
+    return op.get("verify_state") in ("VERIFIED", "MISMATCH", "UNVERIFIABLE") or op.get("exec_state") in ("FAILED", "CANCELED_BEFORE_SEND")
+
+
+def _money(minor: Any, currency: Any) -> str:
+    cur = str(currency or "").lower()
+    amount = f"{(int(minor or 0)) / 100:.2f}"
+    return f"€{amount}" if cur == "eur" else f"{amount} {cur.upper()}".strip()
+
+
+def message_for(op: Json, **overrides: str) -> str:
+    """What the agent may honestly tell the customer. Map it in code, not in the prompt."""
+    refund = op.get("action") == "refund.create"
+    params = op.get("parameters") or {}
+    amt = _money(params.get("amount_minor"), params.get("currency"))
+    thing = f"{amt} refund" if refund else "cancellation"
+    approval = op.get("approval") or {}
+    decision, exec_state, verify = op.get("decision"), op.get("exec_state"), op.get("verify_state")
+    if approval.get("decision") == "REJECTED":
+        return overrides.get("rejected", f"A colleague reviewed your request and couldn’t approve the {thing} — they’ll follow up by email.")
+    if approval.get("decision") == "EXPIRED" or exec_state == "CANCELED_BEFORE_SEND":
+        return overrides.get("expired", "I’ve passed your request to a colleague; they’ll follow up by email.")
+    if decision == "DENY":
+        return overrides.get("deny", "I can’t make that refund myself — I’ve passed it to a colleague who will follow up." if refund else "I can’t make that change myself — I’ve passed it to a colleague who will follow up.")
+    if decision == "HOLD":
+        return overrides.get("hold", "I’ve logged your request; it will be processed shortly.")
+    if decision == "REVIEW" and approval.get("decision") == "PENDING":
+        return overrides.get("review", f"I’ve asked a colleague to approve your {thing} — you’ll get an email as soon as it’s done.")
+    if verify in ("MISMATCH", "UNVERIFIABLE") or exec_state == "FAILED":
+        return overrides.get("problem", f"There was a problem processing your {thing}; a colleague is looking into it.")
+    if verify == "VERIFIED":
+        return overrides.get("verified", f"Your {amt} refund is confirmed — it will reach your card in a few days." if refund else "Your cancellation is confirmed.")
+    return overrides.get("allow", f"Your {amt} refund is on its way back to your card." if refund else "Your cancellation is being processed.")

colvo-0.1.0/colvo.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: colvo
+Version: 0.1.0
+Summary: COLVO SDK — propose agent actions through Guard, report observations, read decisions. Standard library only.
+License: MIT
+Project-URL: Homepage, https://colvo.app/docs/move-to-guard
+Keywords: colvo,ai agents,guardrails,stripe,refunds,human in the loop
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# colvo (Python)
+
+The agent proposes, COLVO decides (ALLOW / REVIEW / HOLD / DENY), executes exactly once and verifies against the provider.
+Standard library only, Python 3.9+. Guide: https://colvo.app/docs/move-to-guard
+
+```python
+import os
+from colvo import Colvo, ColvoError, message_for
+
+colvo = Colvo(os.environ["COLVO_AGENT_KEY"])
+op = colvo.operations.propose({
+    "mandate_id": mandate_id, "source_request_id": ticket_id, "action": "refund.create",
+    "parameters": {"payment_id": "pi_…", "amount_minor": 5000, "currency": "eur"},
+})
+reply(message_for(op))
+```
+
+- `operations.propose(proposal, idempotency_key=None)` — safe retries with a deterministic idempotency key.
+- `operations.get(id)`, `operations.wait_for(id, until="verified")`, `observations.report(obs)`, `mandates.create(m)` (backend key).
+- Errors raise `ColvoError(status, code, message, details)`.
+
+Tests: `python3 -m unittest discover -s sdks/python/tests`.

colvo-0.1.0/colvo.egg-info/SOURCES.txt

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

colvo-0.1.0/colvo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

colvo-0.1.0/colvo.egg-info/top_level.txt

@@ -0,0 +1 @@
+colvo

colvo-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "colvo"
+version = "0.1.0"
+description = "COLVO SDK — propose agent actions through Guard, report observations, read decisions. Standard library only."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["colvo", "ai agents", "guardrails", "stripe", "refunds", "human in the loop"]
+classifiers = ["Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent"]
+
+[project.urls]
+Homepage = "https://colvo.app/docs/move-to-guard"
+
+[tool.setuptools]
+packages = ["colvo"]

colvo-0.1.0/setup.cfg

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

colvo-0.1.0/tests/test_client.py

@@ -0,0 +1,74 @@
+import json
+import unittest.mock
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from colvo import Colvo, ColvoError, idempotency_key_for, message_for  # noqa: E402
+
+PROPOSE = {"mandate_id": "m", "source_request_id": "ticket_1", "action": "refund.create", "parameters": {"payment_id": "pi_1", "amount_minor": 5000, "currency": "eur"}}
+
+
+def op(**kw):
+    base = {"operation_id": "op1", "action": "refund.create", "parameters": PROPOSE["parameters"], "decision": "ALLOW", "exec_state": "QUEUED", "verify_state": "NOT_DUE", "approval": None}
+    base.update(kw)
+    return base
+
+
+class FakeTransport:
+    def __init__(self, responses):
+        self.responses = list(responses)
+        self.calls = []
+
+    def __call__(self, method, url, headers, body, timeout):
+        self.calls.append((method, url, headers, body))
+        r = self.responses.pop(0)
+        if isinstance(r, Exception):
+            raise r
+        status, payload = r
+        return status, {}, json.dumps(payload).encode()
+
+
+class ClientTest(unittest.TestCase):
+    def test_propose_retries_with_same_idempotency_key(self):
+        t = FakeTransport([(503, {"error": "internal_error"}), (202, op())])
+        c = Colvo("cak_x", base_url="https://c.test/", transport=t)
+        with unittest.mock.patch("time.sleep"):
+            r = c.operations.propose(PROPOSE)
+        self.assertEqual(r["decision"], "ALLOW")
+        self.assertEqual(len(t.calls), 2)
+        self.assertEqual(t.calls[0][1], "https://c.test/v1/operations")
+        self.assertEqual(t.calls[0][2]["authorization"], "Bearer cak_x")
+        self.assertEqual(t.calls[0][2]["idempotency-key"], "ticket_1:refund.create:pi_1:5000eur")
+        self.assertEqual(t.calls[1][2]["idempotency-key"], t.calls[0][2]["idempotency-key"])
+
+    def test_errors_are_typed_and_mandates_not_retried(self):
+        t = FakeTransport([(500, {"error": "internal_error", "message": "boom"})])
+        with self.assertRaises(ColvoError) as ctx:
+            Colvo("k", transport=t).mandates.create({"project_id": "p"})
+        self.assertEqual((ctx.exception.status, ctx.exception.code, ctx.exception.message), (500, "internal_error", "boom"))
+        self.assertEqual(len(t.calls), 1)
+        t2 = FakeTransport([(409, {"error": "business_key_conflict", "message": "x", "existing": "op9"})])
+        with self.assertRaises(ColvoError) as ctx2:
+            Colvo("k", transport=t2).operations.propose(PROPOSE)
+        self.assertEqual(ctx2.exception.details, {"existing": "op9"})
+        with self.assertRaises(ColvoError) as ctx3:
+            Colvo("k", max_retries=0, transport=FakeTransport([OSError("reset")])).operations.get("op1")
+        self.assertEqual(ctx3.exception.code, "network_error")
+
+    def test_wait_for_and_idempotency_key(self):
+        t = FakeTransport([(200, op(exec_state="SENDING")), (200, op(exec_state="ACKNOWLEDGED", verify_state="VERIFIED"))])
+        self.assertEqual(Colvo("k", transport=t).operations.wait_for("op1", interval=0)["verify_state"], "VERIFIED")
+        self.assertEqual(idempotency_key_for({**PROPOSE, "action": "subscription.cancel", "parameters": {"subscription_id": "sub_1"}}), "ticket_1:subscription.cancel:sub_1:period_end")
+
+    def test_message_for_is_honest(self):
+        self.assertIn("€50.00 refund is on its way", message_for(op()))
+        self.assertIn("asked a colleague to approve", message_for(op(decision="REVIEW", exec_state="NOT_SENT", approval={"decision": "PENDING"})))
+        self.assertNotIn("on its way", message_for(op(decision="DENY", exec_state="NOT_SENT")))
+        self.assertEqual(message_for(op(decision="HOLD"), hold="custom"), "custom")
+
+
+if __name__ == "__main__":
+    import unittest.mock  # noqa: F401
+    unittest.main()