onceonly-sdk 2.0.0__tar.gz → 2.0.1__tar.gz

{onceonly_sdk-2.0.0 → onceonly_sdk-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onceonly-sdk
-Version: 2.0.0
+Version: 2.0.1
 Summary: Python SDK for OnceOnly idempotency API
 Author-email: OnceOnly <support@onceonly.tech>
 License: MIT
@@ -41,7 +41,8 @@ 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
 
 ---
@@ -60,7 +61,7 @@ pip install "onceonly-sdk[langchain]"
 
 ---
 
-## Quick Start
+## Quick Start (Webhooks / Automations)
 
 ```python
 from onceonly import OnceOnly
@@ -78,11 +79,54 @@ else:
     print("First execution")
 ```
 
+Use `check_lock()` for:
+- Webhooks
+- Make / Zapier scenarios
+- Cron jobs
+- Distributed workers
+
+---
+
+## AI Jobs (Server-side)
+
+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 / LangChain Integration 🤖
+## AI Agents / Local Side-Effects
 
-OnceOnly integrates cleanly with AI-agent frameworks like LangChain.
+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 +138,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 +155,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 → onceonly_sdk-2.0.1}/README.md

@@ -16,7 +16,8 @@ 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
 
 ---
@@ -35,7 +36,7 @@ pip install "onceonly-sdk[langchain]"
 
 ---
 
-## Quick Start
+## Quick Start (Webhooks / Automations)
 
 ```python
 from onceonly import OnceOnly
@@ -53,11 +54,54 @@ else:
     print("First execution")
 ```
 
+Use `check_lock()` for:
+- Webhooks
+- Make / Zapier scenarios
+- Cron jobs
+- Distributed workers
+
+---
+
+## AI Jobs (Server-side)
+
+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 / LangChain Integration 🤖
+## AI Agents / Local Side-Effects
 
-OnceOnly integrates cleanly with AI-agent frameworks like LangChain.
+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
@@ -69,11 +113,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
@@ -83,7 +130,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.1/onceonly/ai.py

@@ -0,0 +1,403 @@
+from __future__ import annotations
+
+import asyncio
+import time
+import logging
+from typing import Any, Dict, Optional, Awaitable, Callable
+
+import httpx
+
+from ._http import (
+    parse_json_or_raise,
+    request_with_retries_sync,
+    request_with_retries_async,
+)
+from ._util import to_metadata_dict, MetadataLike
+from .ai_models import AiRun, AiStatus, AiResult
+
+logger = logging.getLogger("onceonly")
+
+
+class AiClient:
+    """
+    AI helpers for long-running backend tasks.
+
+    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__(
+        self,
+        sync_client: httpx.Client,
+        async_client_getter: Callable[[], Awaitable[httpx.AsyncClient]],
+        *,
+        max_retries_429: int = 0,
+        retry_backoff: float = 0.5,
+        retry_max_backoff: float = 5.0,
+    ):
+        self._c = sync_client
+        self._get_ac = async_client_getter
+
+        self._max_retries_429 = int(max_retries_429)
+        self._retry_backoff = float(retry_backoff)
+        self._retry_max_backoff = float(retry_max_backoff)
+
+    # ------------------------------------------------------------------
+    # 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}
+        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/run", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        data = parse_json_or_raise(resp)
+
+        logger.debug("ai.run key=%s status=%s version=%s", key, data.get("status"), data.get("version"))
+        return AiRun.from_dict(data)
+
+    def status(self, key: str) -> AiStatus:
+        resp = request_with_retries_sync(
+            lambda: self._c.get("/ai/status", params={"key": key}),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        data = parse_json_or_raise(resp)
+
+        logger.debug("ai.status key=%s status=%s version=%s", key, data.get("status"), data.get("version"))
+        return AiStatus.from_dict(data)
+
+    def result(self, key: str) -> AiResult:
+        resp = request_with_retries_sync(
+            lambda: self._c.get("/ai/result", params={"key": key}),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        data = parse_json_or_raise(resp)
+
+        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:
+        """
+        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)
+            if st.status in ("completed", "failed"):
+                return self.result(key)
+
+            if time.time() - t0 >= 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)))
+            time.sleep(sleep_s)
+
+    def run_and_wait(
+        self,
+        key: str,
+        *,
+        ttl: Optional[int] = None,
+        metadata: Optional[MetadataLike] = None,
+        timeout: float = 60.0,
+        poll_min: float = 0.5,
+        poll_max: float = 5.0,
+    ) -> AiResult:
+        self.run(key=key, ttl=ttl, metadata=metadata)
+        return self.wait(key=key, timeout=timeout, poll_min=poll_min, poll_max=poll_max)
+
+    # -------------------- 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}
+        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/run", json=payload),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        data = parse_json_or_raise(resp)
+
+        logger.debug("ai.run_async key=%s status=%s version=%s", key, data.get("status"), data.get("version"))
+        return AiRun.from_dict(data)
+
+    async def status_async(self, key: str) -> AiStatus:
+        c = await self._get_ac()
+        resp = await request_with_retries_async(
+            lambda: c.get("/ai/status", params={"key": key}),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        data = parse_json_or_raise(resp)
+
+        logger.debug("ai.status_async key=%s status=%s version=%s", key, data.get("status"), data.get("version"))
+        return AiStatus.from_dict(data)
+
+    async def result_async(self, key: str) -> AiResult:
+        c = await self._get_ac()
+        resp = await request_with_retries_async(
+            lambda: c.get("/ai/result", params={"key": key}),
+            max_retries=self._max_retries_429,
+            base_backoff=self._retry_backoff,
+            max_backoff=self._retry_max_backoff,
+        )
+        data = parse_json_or_raise(resp)
+
+        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:
+        t0 = time.time()
+        while True:
+            st = await self.status_async(key)
+            if st.status in ("completed", "failed"):
+                return await self.result_async(key)
+
+            if time.time() - t0 >= 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)))
+            await asyncio.sleep(sleep_s)
+
+    async def run_and_wait_async(
+        self,
+        key: str,
+        *,
+        ttl: Optional[int] = None,
+        metadata: Optional[MetadataLike] = None,
+        timeout: float = 60.0,
+        poll_min: float = 0.5,
+        poll_max: float = 5.0,
+    ) -> 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_sdk-2.0.1/onceonly/version.py

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

{onceonly_sdk-2.0.0 → onceonly_sdk-2.0.1}/onceonly_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: onceonly-sdk
-Version: 2.0.0
+Version: 2.0.1
 Summary: Python SDK for OnceOnly idempotency API
 Author-email: OnceOnly <support@onceonly.tech>
 License: MIT
@@ -41,7 +41,8 @@ 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
 
 ---
@@ -60,7 +61,7 @@ pip install "onceonly-sdk[langchain]"
 
 ---
 
-## Quick Start
+## Quick Start (Webhooks / Automations)
 
 ```python
 from onceonly import OnceOnly
@@ -78,11 +79,54 @@ else:
     print("First execution")
 ```
 
+Use `check_lock()` for:
+- Webhooks
+- Make / Zapier scenarios
+- Cron jobs
+- Distributed workers
+
+---
+
+## AI Jobs (Server-side)
+
+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 / LangChain Integration 🤖
+## AI Agents / Local Side-Effects
 
-OnceOnly integrates cleanly with AI-agent frameworks like LangChain.
+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 +138,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 +155,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 → onceonly_sdk-2.0.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "onceonly-sdk"
-version = "2.0.0"
+version = "2.0.1"
 description = "Python SDK for OnceOnly idempotency API"
 readme = "README.md"
 requires-python = ">=3.9"

{onceonly_sdk-2.0.0 → onceonly_sdk-2.0.1}/tests/test_client_behavior.py

@@ -3,6 +3,11 @@ import httpx
 from unittest.mock import MagicMock
 
 from onceonly.client import OnceOnly
+from onceonly.exceptions import UnauthorizedError, OverLimitError, ValidationError
+
+
+def _mk_req():
+    return httpx.Request("POST", "https://api.onceonly.tech/v1/check-lock")
 
 
 def test_fail_open_on_network_error():
@@ -40,3 +45,32 @@ def test_fail_open_on_500():
     assert res.duplicate is False
     assert res.raw.get("fail_open") is True
     assert res.raw.get("reason") == "api_5xx"
+
+
+def test_fail_open_does_not_mask_4xx_errors():
+    mock_http = MagicMock()
+
+    client = OnceOnly("apikey", sync_client=mock_http, fail_open=True)
+
+    # 401/403 should raise UnauthorizedError (NOT fail-open)
+    mock_http.post.return_value = httpx.Response(401, json={"detail": "nope"}, request=_mk_req())
+    with pytest.raises(UnauthorizedError):
+        client.check_lock("k")
+
+    mock_http.post.return_value = httpx.Response(403, json={"detail": "nope"}, request=_mk_req())
+    with pytest.raises(UnauthorizedError):
+        client.check_lock("k")
+
+    # 402 should raise OverLimitError (NOT fail-open)
+    mock_http.post.return_value = httpx.Response(
+        402,
+        json={"detail": {"error": "limit", "plan": "free", "limit": 1000, "usage": 1001}},
+        request=_mk_req(),
+    )
+    with pytest.raises(OverLimitError):
+        client.check_lock("k")
+
+    # 422 should raise ValidationError (NOT fail-open)
+    mock_http.post.return_value = httpx.Response(422, json={"detail": "Validation Error"}, request=_mk_req())
+    with pytest.raises(ValidationError):
+        client.check_lock("k")

{onceonly_sdk-2.0.0 → onceonly_sdk-2.0.1}/tests/test_integrations.py

@@ -125,6 +125,47 @@ def test_langchain_duplicate_behavior_structured(mock_client):
     assert "duplicate" in res.lower()
 
 
+def test_langchain_duplicate_does_not_call_original_tool():
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError:
+        pytest.skip("LangChain not installed")
+
+    mock_client = MagicMock(spec=OnceOnly)
+    mock_client.check_lock.return_value = CheckLockResult(
+        locked=False,
+        duplicate=True,
+        key="k",
+        ttl=60,
+        first_seen_at="now",
+        request_id="r",
+        status_code=409,
+        raw={},
+    )
+
+    called = {"n": 0}
+
+    def refund_user(user_id: str, amount: int) -> str:
+        called["n"] += 1
+        return "original run"
+
+    original_tool = StructuredTool.from_function(
+        func=refund_user,
+        name="refund_tool",
+        description="Refunds a user",
+    )
+
+    wrapped = make_idempotent_tool(original_tool, client=mock_client, key_prefix="test_prefix")
+
+    out = wrapped.invoke({"user_id": "u_100", "amount": 50})
+
+    assert called["n"] == 0
+    assert isinstance(out, str)
+    assert "duplicate" in out.lower()
+    assert "skipped" in out.lower()
+    mock_client.check_lock.assert_called_once()
+
+
 def test_single_input_tool_supported(mock_client):
     """
     Ensure single-input tools still work.

{onceonly_sdk-2.0.0 → onceonly_sdk-2.0.1}/tests/test_parsing.py

@@ -149,3 +149,30 @@ def test_500_non_json_body():
     resp = mk_response(500, text="<html>502 Bad Gateway</html>")
     with pytest.raises(ApiError):
         c._parse_check_lock_response(resp, fallback_key="a", fallback_ttl=60)
+
+
+def test_header_locked_without_body_json():
+    c = OnceOnly("k")
+    resp = mk_response(
+        200,
+        json_data={},  # empty body, but header says locked
+        headers={"X-OnceOnly-Status": "locked", "X-Request-Id": "rid_locked"},
+    )
+    r = c._parse_check_lock_response(resp, fallback_key="a", fallback_ttl=60)
+    assert r.locked is True
+    assert r.duplicate is False
+    assert r.request_id == "rid_locked"
+
+
+def test_ttl_fallback_when_missing_in_json():
+    c = OnceOnly("k")
+    resp = mk_response(
+        200,
+        json_data={"success": True, "status": "locked", "key": "a"},  # no ttl
+        headers={"X-OnceOnly-Status": "locked", "X-Request-Id": "rid_ttl"},
+    )
+    r = c._parse_check_lock_response(resp, fallback_key="a", fallback_ttl=123)
+    assert r.locked is True
+    assert r.duplicate is False
+    assert r.ttl == 123
+    assert r.request_id == "rid_ttl"

onceonly_sdk-2.0.0/onceonly/ai.py

@@ -1,195 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import time
-import logging
-from typing import Any, Dict, Optional, Awaitable, Callable
-
-import httpx
-
-from ._http import (
-    parse_json_or_raise,
-    request_with_retries_sync,
-    request_with_retries_async,
-)
-from ._util import to_metadata_dict, MetadataLike
-from .ai_models import AiRun, AiStatus, AiResult
-
-logger = logging.getLogger("onceonly")
-
-
-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)
-    """
-
-    def __init__(
-        self,
-        sync_client: httpx.Client,
-        async_client_getter: Callable[[], Awaitable[httpx.AsyncClient]],
-        *,
-        max_retries_429: int = 0,
-        retry_backoff: float = 0.5,
-        retry_max_backoff: float = 5.0,
-    ):
-        self._c = sync_client
-        self._get_ac = async_client_getter
-
-        self._max_retries_429 = int(max_retries_429)
-        self._retry_backoff = float(retry_backoff)
-        self._retry_max_backoff = float(retry_max_backoff)
-
-    # ---- sync ----
-
-    def run(self, key: str, ttl: Optional[int] = None, metadata: Optional[MetadataLike] = None) -> AiRun:
-        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/run", json=payload),
-            max_retries=self._max_retries_429,
-            base_backoff=self._retry_backoff,
-            max_backoff=self._retry_max_backoff,
-        )
-        data = parse_json_or_raise(resp)
-
-        logger.debug("ai.run key=%s status=%s version=%s", key, data.get("status"), data.get("version"))
-        return AiRun.from_dict(data)
-
-    def status(self, key: str) -> AiStatus:
-        resp = request_with_retries_sync(
-            lambda: self._c.get("/ai/status", params={"key": key}),
-            max_retries=self._max_retries_429,
-            base_backoff=self._retry_backoff,
-            max_backoff=self._retry_max_backoff,
-        )
-        data = parse_json_or_raise(resp)
-
-        logger.debug("ai.status key=%s status=%s version=%s", key, data.get("status"), data.get("version"))
-        return AiStatus.from_dict(data)
-
-    def result(self, key: str) -> AiResult:
-        resp = request_with_retries_sync(
-            lambda: self._c.get("/ai/result", params={"key": key}),
-            max_retries=self._max_retries_429,
-            base_backoff=self._retry_backoff,
-            max_backoff=self._retry_max_backoff,
-        )
-        data = parse_json_or_raise(resp)
-
-        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:
-        t0 = time.time()
-        while True:
-            st = self.status(key)
-            if st.status in ("completed", "failed"):
-                return self.result(key)
-
-            if time.time() - t0 >= timeout:
-                return AiResult(ok=False, status="timeout", 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)))
-            time.sleep(sleep_s)
-
-    def run_and_wait(
-        self,
-        key: str,
-        *,
-        ttl: Optional[int] = None,
-        metadata: Optional[MetadataLike] = None,
-        timeout: float = 60.0,
-        poll_min: float = 0.5,
-        poll_max: float = 5.0,
-    ) -> AiResult:
-        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 def run_async(self, key: str, ttl: Optional[int] = None, metadata: Optional[MetadataLike] = None) -> AiRun:
-        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/run", json=payload),
-            max_retries=self._max_retries_429,
-            base_backoff=self._retry_backoff,
-            max_backoff=self._retry_max_backoff,
-        )
-        data = parse_json_or_raise(resp)
-
-        logger.debug("ai.run_async key=%s status=%s version=%s", key, data.get("status"), data.get("version"))
-        return AiRun.from_dict(data)
-
-    async def status_async(self, key: str) -> AiStatus:
-        c = await self._get_ac()
-        resp = await request_with_retries_async(
-            lambda: c.get("/ai/status", params={"key": key}),
-            max_retries=self._max_retries_429,
-            base_backoff=self._retry_backoff,
-            max_backoff=self._retry_max_backoff,
-        )
-        data = parse_json_or_raise(resp)
-
-        logger.debug("ai.status_async key=%s status=%s version=%s", key, data.get("status"), data.get("version"))
-        return AiStatus.from_dict(data)
-
-    async def result_async(self, key: str) -> AiResult:
-        c = await self._get_ac()
-        resp = await request_with_retries_async(
-            lambda: c.get("/ai/result", params={"key": key}),
-            max_retries=self._max_retries_429,
-            base_backoff=self._retry_backoff,
-            max_backoff=self._retry_max_backoff,
-        )
-        data = parse_json_or_raise(resp)
-
-        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:
-        t0 = time.time()
-        while True:
-            st = await self.status_async(key)
-            if st.status in ("completed", "failed"):
-                return await self.result_async(key)
-
-            if time.time() - t0 >= timeout:
-                return AiResult(ok=False, status="timeout", 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)))
-            await asyncio.sleep(sleep_s)
-
-    async def run_and_wait_async(
-        self,
-        key: str,
-        *,
-        ttl: Optional[int] = None,
-        metadata: Optional[MetadataLike] = None,
-        timeout: float = 60.0,
-        poll_min: float = 0.5,
-        poll_max: float = 5.0,
-    ) -> 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)

onceonly_sdk-2.0.0/onceonly/version.py

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