onceonly-sdk 2.0.0__py3-none-any.whl → 2.0.2__py3-none-any.whl

onceonly/ai.py

@@ -22,13 +22,17 @@ class AiClient:
     """
     AI helpers for long-running backend tasks.
 
-    Typical usage for agents:
-        result = client.ai.run_and_wait(key="job:123", metadata={...})
-
-    Endpoints:
-    - POST /ai/run    => start/attach to a run (idempotent by key)
-    - GET  /ai/status => poll status
-    - GET  /ai/result => fetch final result (completed/failed)
+    High-level:
+      - POST /ai/run    => start/attach to a run (idempotent by key)
+      - GET  /ai/status => poll status
+      - GET  /ai/result => fetch final result (completed/failed)
+
+    Low-level lease API (for local side effects / agent tools):
+      - POST /ai/lease
+      - POST /ai/extend
+      - POST /ai/complete
+      - POST /ai/fail
+      - POST /ai/cancel
     """
 
     def __init__(
@@ -47,7 +51,9 @@ class AiClient:
         self._retry_backoff = float(retry_backoff)
         self._retry_max_backoff = float(retry_max_backoff)
 
-    # ---- sync ----
+    # ------------------------------------------------------------------
+    # High-level: /ai/run + /ai/status + /ai/result
+    # ------------------------------------------------------------------
 
     def run(self, key: str, ttl: Optional[int] = None, metadata: Optional[MetadataLike] = None) -> AiRun:
         payload: Dict[str, Any] = {"key": key}
@@ -92,7 +98,21 @@ class AiClient:
         logger.debug("ai.result key=%s status=%s", key, data.get("status"))
         return AiResult.from_dict(data)
 
-    def wait(self, key: str, timeout: float = 60.0, poll_min: float = 0.5, poll_max: float = 5.0) -> AiResult:
+    def wait(
+        self,
+        key: str,
+        *,
+        timeout: float = 60.0,
+        poll_min: float = 0.5,
+        poll_max: float = 5.0,
+    ) -> AiResult:
+        """
+        Polls /ai/status until completed/failed or timeout.
+
+        NOTE: We do NOT return status="timeout" because backend model statuses
+        are usually limited to: not_found|in_progress|completed|failed.
+        Instead we return status="failed" with error_code="timeout".
+        """
         t0 = time.time()
         while True:
             st = self.status(key)
@@ -100,7 +120,7 @@ class AiClient:
                 return self.result(key)
 
             if time.time() - t0 >= timeout:
-                return AiResult(ok=False, status="timeout", key=key, error_code="timeout")
+                return AiResult(ok=False, status="failed", key=key, error_code="timeout")
 
             sleep_s = st.retry_after_sec if isinstance(st.retry_after_sec, int) else poll_min
             sleep_s = max(poll_min, min(poll_max, float(sleep_s)))
@@ -119,7 +139,7 @@ class AiClient:
         self.run(key=key, ttl=ttl, metadata=metadata)
         return self.wait(key=key, timeout=timeout, poll_min=poll_min, poll_max=poll_max)
 
-    # ---- async ----
+    # -------------------- async high-level --------------------
 
     async def run_async(self, key: str, ttl: Optional[int] = None, metadata: Optional[MetadataLike] = None) -> AiRun:
         payload: Dict[str, Any] = {"key": key}
@@ -167,7 +187,14 @@ class AiClient:
         logger.debug("ai.result_async key=%s status=%s", key, data.get("status"))
         return AiResult.from_dict(data)
 
-    async def wait_async(self, key: str, timeout: float = 60.0, poll_min: float = 0.5, poll_max: float = 5.0) -> AiResult:
+    async def wait_async(
+        self,
+        key: str,
+        *,
+        timeout: float = 60.0,
+        poll_min: float = 0.5,
+        poll_max: float = 5.0,
+    ) -> AiResult:
         t0 = time.time()
         while True:
             st = await self.status_async(key)
@@ -175,7 +202,7 @@ class AiClient:
                 return await self.result_async(key)
 
             if time.time() - t0 >= timeout:
-                return AiResult(ok=False, status="timeout", key=key, error_code="timeout")
+                return AiResult(ok=False, status="failed", key=key, error_code="timeout")
 
             sleep_s = st.retry_after_sec if isinstance(st.retry_after_sec, int) else poll_min
             sleep_s = max(poll_min, min(poll_max, float(sleep_s)))
@@ -193,3 +220,184 @@ class AiClient:
     ) -> AiResult:
         await self.run_async(key=key, ttl=ttl, metadata=metadata)
         return await self.wait_async(key=key, timeout=timeout, poll_min=poll_min, poll_max=poll_max)
+
+    # ------------------------------------------------------------------
+    # Low-level lease API (sync) - returns raw dicts (backend models)
+    # ------------------------------------------------------------------
+
+    def lease(self, key: str, ttl: Optional[int] = None, metadata: Optional[MetadataLike] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key}
+        if ttl is not None:
+            payload["ttl"] = int(ttl)
+        md = to_metadata_dict(metadata)
+        if md is not None:
+            payload["metadata"] = md
+
+        resp = request_with_retries_sync(
+            lambda: self._c.post("/ai/lease", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    def extend(self, key: str, lease_id: str, ttl: Optional[int] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key, "lease_id": lease_id}
+        if ttl is not None:
+            payload["ttl"] = int(ttl)
+
+        resp = request_with_retries_sync(
+            lambda: self._c.post("/ai/extend", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    def complete(
+        self,
+        key: str,
+        lease_id: str,
+        *,
+        result: Optional[Dict[str, Any]] = None,
+        result_hash: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key, "lease_id": lease_id}
+        if result_hash is not None:
+            payload["result_hash"] = str(result_hash)
+        if result is not None:
+            payload["result"] = result
+
+        resp = request_with_retries_sync(
+            lambda: self._c.post("/ai/complete", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    def fail(
+        self,
+        key: str,
+        lease_id: str,
+        *,
+        error_code: str,
+        error_hash: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key, "lease_id": lease_id, "error_code": str(error_code)}
+        if error_hash is not None:
+            payload["error_hash"] = str(error_hash)
+
+        resp = request_with_retries_sync(
+            lambda: self._c.post("/ai/fail", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    def cancel(self, key: str, lease_id: str, reason: Optional[str] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key, "lease_id": lease_id}
+        if reason:
+            payload["reason"] = str(reason)
+
+        resp = request_with_retries_sync(
+            lambda: self._c.post("/ai/cancel", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    # ------------------------------------------------------------------
+    # Low-level lease API (async) - returns raw dicts (backend models)
+    # ------------------------------------------------------------------
+
+    async def lease_async(self, key: str, ttl: Optional[int] = None, metadata: Optional[MetadataLike] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key}
+        if ttl is not None:
+            payload["ttl"] = int(ttl)
+        md = to_metadata_dict(metadata)
+        if md is not None:
+            payload["metadata"] = md
+
+        c = await self._get_ac()
+        resp = await request_with_retries_async(
+            lambda: c.post("/ai/lease", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    async def extend_async(self, key: str, lease_id: str, ttl: Optional[int] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key, "lease_id": lease_id}
+        if ttl is not None:
+            payload["ttl"] = int(ttl)
+
+        c = await self._get_ac()
+        resp = await request_with_retries_async(
+            lambda: c.post("/ai/extend", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    async def complete_async(
+        self,
+        key: str,
+        lease_id: str,
+        *,
+        result: Optional[Dict[str, Any]] = None,
+        result_hash: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key, "lease_id": lease_id}
+        if result_hash is not None:
+            payload["result_hash"] = str(result_hash)
+        if result is not None:
+            payload["result"] = result
+
+        c = await self._get_ac()
+        resp = await request_with_retries_async(
+            lambda: c.post("/ai/complete", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    async def fail_async(
+        self,
+        key: str,
+        lease_id: str,
+        *,
+        error_code: str,
+        error_hash: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key, "lease_id": lease_id, "error_code": str(error_code)}
+        if error_hash is not None:
+            payload["error_hash"] = str(error_hash)
+
+        c = await self._get_ac()
+        resp = await request_with_retries_async(
+            lambda: c.post("/ai/fail", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)
+
+    async def cancel_async(self, key: str, lease_id: str, reason: Optional[str] = None) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": key, "lease_id": lease_id}
+        if reason:
+            payload["reason"] = str(reason)
+
+        c = await self._get_ac()
+        resp = await request_with_retries_async(
+            lambda: c.post("/ai/cancel", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        return parse_json_or_raise(resp)

onceonly/version.py

@@ -1 +1 @@
-__version__ = "2.0.0"
+__version__ = "2.0.2"

{onceonly_sdk-2.0.0.dist-info → onceonly_sdk-2.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onceonly-sdk
-Version: 2.0.0
+Version: 2.0.2
 Summary: Python SDK for OnceOnly idempotency API
 Author-email: OnceOnly <support@onceonly.tech>
 License: MIT
@@ -31,9 +31,27 @@ OnceOnly is a high-performance Python SDK that ensures **exactly-once execution*
 It prevents duplicate actions (payments, emails, tool calls) in unstable environments like
 AI agents, webhooks, retries, or background workers.
 
+
 Website: https://onceonly.tech/ai/  
 Documentation: https://onceonly.tech/docs/
 
+[![PyPI version](https://img.shields.io/pypi/v/onceonly-sdk.svg)](https://pypi.org/project/onceonly-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+---
+
+## Why duplicates happen
+
+Duplicate actions are common in modern systems because:
+- AI agents retry or re-plan tool calls
+- Webhooks are delivered more than once
+- Workers crash after side-effects
+- Distributed systems replay events
+
+Without an idempotency layer, the same action may run multiple times.
+
+OnceOnly is designed to guard side-effects in non-deterministic AI agent loops,
+where the same tool call may be executed multiple times.
+
 ---
 
 ## Features
@@ -41,9 +59,21 @@ Documentation: https://onceonly.tech/docs/
 - Sync + Async client (httpx-based)
 - Fail-open mode for production safety
 - Stable idempotency keys (supports Pydantic & dataclasses)
-- Decorator for zero-boilerplate usage
+- Decorators for zero-boilerplate usage
+- Native AI API (long-running jobs, local side-effects)
 - Optional AI / LangChain integrations
 
+---
+
+## FAQ
+
+**Does this prevent duplicate payments or emails?**  
+Yes. OnceOnly guarantees exactly-once execution for side-effects.
+
+**Is this a retry library?**  
+No. Retries still happen — OnceOnly ensures the action itself runs only once.
+
+
 ---
 
 ## Installation
@@ -60,7 +90,7 @@ pip install "onceonly-sdk[langchain]"
 
 ---
 
-## Quick Start
+## Quick Start (Webhooks / Automations)
 
 ```python
 from onceonly import OnceOnly
@@ -78,11 +108,54 @@ else:
     print("First execution")
 ```
 
+Use `check_lock()` for:
+- Webhooks
+- Make / Zapier scenarios
+- Cron jobs
+- Distributed workers
+
 ---
 
-## AI Agents / LangChain Integration 🤖
+## AI Jobs (Server-side)
 
-OnceOnly integrates cleanly with AI-agent frameworks like LangChain.
+Use the AI API for long-running or asynchronous jobs.
+
+```python
+result = client.ai.run_and_wait(
+    key="ai:job:daily_summary:2026-01-09",
+    metadata={"task": "daily_summary", "model": "gpt-4.1"},
+    timeout=60,
+)
+
+print(result.status)
+print(result.result)
+```
+
+- Charged **once per key**
+- Polling is free
+- Safe across retries and restarts
+
+---
+
+## AI Agents / Local Side-Effects
+
+Use the AI Lease API when your code performs the side-effect locally
+(payments, emails, webhooks) but still needs exactly-once guarantees.
+
+```python
+lease = client.ai.lease(key="ai:agent:charge:user_42:invoice_100", ttl=300)
+
+if lease["status"] == "acquired":
+    try:
+        do_side_effect()
+        client.ai.complete(key=KEY, lease_id=lease["lease_id"], result={"ok": True})
+    except Exception:
+        client.ai.fail(key=KEY, lease_id=lease["lease_id"], error_code="failed")
+```
+
+---
+
+## LangChain Integration 🤖
 
 ```python
 from onceonly.integrations.langchain import make_idempotent_tool
@@ -94,11 +167,14 @@ tool = make_idempotent_tool(
 )
 ```
 
-Repeated tool calls with the same inputs will execute **exactly once**, even across retries or agent restarts.
+Repeated tool calls with the same inputs will execute **exactly once**,
+even across retries or agent restarts.
+
+See `examples/ai/` for canonical patterns.
 
 ---
 
-## Decorator
+## Decorators
 
 ```python
 from onceonly.decorators import idempotent
@@ -108,7 +184,7 @@ def process_order(order_id):
     ...
 ```
 
-Idempotency keys are generated automatically and are stable across restarts.
+Idempotency keys are generated automatically and remain stable across restarts.
 
 ---
 

{onceonly_sdk-2.0.0.dist-info → onceonly_sdk-2.0.2.dist-info}/RECORD

@@ -1,17 +1,17 @@
 onceonly/__init__.py,sha256=KMS6F4DejM5nI5-gw3UC8SvETnK90oUE9V5pskh--Uw,481
 onceonly/_http.py,sha256=bFAgrLv0T7cGFq3LqaQCwEiqx-VfKEiT8jUommmhRws,3240
 onceonly/_util.py,sha256=YVdEWn1bvipAzR3g3oXpHmgLiaODwGRB1IGA3gHZ2PM,1273
-onceonly/ai.py,sha256=NjMHtZgc-a-l1Wr3mTWwL9HnIOLZbVr9gkuMXMHbuqA,7043
+onceonly/ai.py,sha256=-yaO1ZRlEO-Qqou4P_Q0cemZYwFSIRDM1Lu_AwfF5PY,14578
 onceonly/ai_models.py,sha256=7bHYnAavdb3c-4nlh9HgRY18949TgmU9XfXfv3PXQEE,2910
 onceonly/client.py,sha256=6DtLdWc-7_bAXsaaewUQUTHVnCkRZGsc-PByMVPRhYY,12838
 onceonly/decorators.py,sha256=nP7Wu-RAQQNaTwyOnibzClEgcBJvYheMrG3_KztdlG8,5171
 onceonly/exceptions.py,sha256=Issh08A4IHSDaysJhVZNRCU9W_9BfiGt65UHaMhDCs4,1156
 onceonly/models.py,sha256=hVEBPgIVZP3ELjWYIFSFCKPzI38t5DA0gio9FvrmHJg,678
-onceonly/version.py,sha256=_7OlQdbVkK4jad0CLdpI0grT-zEAb-qgFmH5mFzDXiA,22
+onceonly/version.py,sha256=tATvJM5shAzfspHYjdVwpV2w3-gDA119NlEYi5X2lFY,22
 onceonly/integrations/__init__.py,sha256=0tk-2HTTsmc42NhWuR_G_Afmz5-5WG8NvmlO7iIPkIY,34
 onceonly/integrations/langchain.py,sha256=cdpHIluddX48uYeDeE1cxmn-arruVdE3k6gvZxYC9z4,5821
-onceonly_sdk-2.0.0.dist-info/licenses/LICENSE,sha256=YQQ8IT_P7hcGmmLFFuOy3eKDZ90e1cqef_okg85oAiQ,129
-onceonly_sdk-2.0.0.dist-info/METADATA,sha256=3cso7k9xZoja4JR8VwZuT4QtnclBcR9cdB4zKYnOM1w,3080
-onceonly_sdk-2.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-onceonly_sdk-2.0.0.dist-info/top_level.txt,sha256=lvz-sHerZcTwlZW-uYoda_wgx62kY07GdtzIdw89hnU,9
-onceonly_sdk-2.0.0.dist-info/RECORD,,
+onceonly_sdk-2.0.2.dist-info/licenses/LICENSE,sha256=YQQ8IT_P7hcGmmLFFuOy3eKDZ90e1cqef_okg85oAiQ,129
+onceonly_sdk-2.0.2.dist-info/METADATA,sha256=WzkOQRSbp38Ot2NKPOAOEY8p-_5Wy298bREdx74uD4w,5041
+onceonly_sdk-2.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+onceonly_sdk-2.0.2.dist-info/top_level.txt,sha256=lvz-sHerZcTwlZW-uYoda_wgx62kY07GdtzIdw89hnU,9
+onceonly_sdk-2.0.2.dist-info/RECORD,,