onceonly-sdk 1.2.0__py3-none-any.whl → 2.0.1__py3-none-any.whl

onceonly/integrations/langchain.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Dict, Optional, Tuple
+
+from ..client import OnceOnly
+
+
+def _stable_hash_args(args: Tuple[Any, ...], kwargs: Dict[str, Any]) -> str:
+    def default_encoder(obj: Any) -> Any:
+        # Pydantic v2
+        md = getattr(obj, "model_dump", None)
+        if callable(md):
+            try:
+                return md()
+            except Exception:
+                pass
+
+        # Pydantic v1
+        dct = getattr(obj, "dict", None)
+        if callable(dct):
+            try:
+                return dct()
+            except Exception:
+                pass
+
+        # Dataclasses
+        if hasattr(obj, "__dataclass_fields__"):
+            try:
+                import dataclasses
+
+                return dataclasses.asdict(obj)
+            except Exception:
+                pass
+
+        if isinstance(obj, (bytes, bytearray)):
+            return obj.hex()
+
+        return str(obj)
+
+    payload = {"args": args, "kwargs": {k: v for k, v in sorted(kwargs.items())}}
+
+    try:
+        raw = json.dumps(
+            payload,
+            ensure_ascii=False,
+            default=default_encoder,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+    except Exception:
+        raw = str(payload)
+
+    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
+
+
+def _hash_tool_input(tool_input: Any) -> str:
+    """
+    Stable hash for LangChain tool_input across versions.
+    """
+    if isinstance(tool_input, dict):
+        return _stable_hash_args((), tool_input)
+    return _stable_hash_args((tool_input,), {})
+
+
+def make_idempotent_tool(
+    tool: Any,
+    *,
+    client: OnceOnly,
+    key_prefix: str = "tool",
+    ttl: int = 86400,
+    meta: Optional[Dict[str, Any]] = None,
+) -> Any:
+    """
+    Optional LangChain integration (no hard dependency).
+    Usage: pip install langchain-core
+
+    Wraps a BaseTool so repeated calls with the same tool_input become idempotent.
+
+    Implementation detail:
+    - We override invoke()/ainvoke() to avoid BaseTool._run signature differences across LC versions
+      and to support both single-input Tool and StructuredTool.
+    """
+    try:
+        from langchain_core.tools import BaseTool  # type: ignore
+    except ImportError as e:
+        raise ImportError("LangChain is not installed. Install langchain-core to use this integration.") from e
+
+    if not isinstance(tool, BaseTool):
+        raise TypeError("tool must be an instance of langchain_core.tools.BaseTool")
+
+    base_meta: Dict[str, Any] = {"tool": getattr(tool, "name", tool.__class__.__name__)}
+    if meta:
+        base_meta.update(meta)
+
+    class IdempotentTool(BaseTool):  # type: ignore[misc]
+        name: str
+        description: str
+
+        _tool: BaseTool
+        _client: OnceOnly
+        _key_prefix: str
+        _ttl: int
+        _meta: Dict[str, Any]
+
+        def __init__(self) -> None:
+            super().__init__(name=tool.name, description=tool.description)
+            object.__setattr__(self, "_tool", tool)
+            object.__setattr__(self, "_client", client)
+            object.__setattr__(self, "_key_prefix", key_prefix)
+            object.__setattr__(self, "_ttl", int(ttl))
+            object.__setattr__(self, "_meta", base_meta)
+
+            # Preserve schema + a few common attrs
+            if hasattr(tool, "args_schema"):
+                try:
+                    object.__setattr__(self, "args_schema", getattr(tool, "args_schema"))
+                except Exception:
+                    pass
+
+            for attr in ("return_direct", "tags", "metadata", "callbacks", "verbose"):
+                if hasattr(tool, attr):
+                    try:
+                        setattr(self, attr, getattr(tool, attr))
+                    except Exception:
+                        pass
+
+        def invoke(self, tool_input: Any, config: Any = None, **kwargs: Any) -> Any:  # type: ignore[override]
+            h = _hash_tool_input(tool_input)
+            key = f"{self._key_prefix}:{self.name}:{h}"
+
+            res = self._client.check_lock(key=key, ttl=self._ttl, meta=self._meta)
+            if res.duplicate:
+                return f"Action '{self.name}' skipped (idempotency key duplicate)."
+
+            # Delegate: let LangChain handle parsing/validation/config
+            if config is None:
+                return self._tool.invoke(tool_input, **kwargs)
+            return self._tool.invoke(tool_input, config=config, **kwargs)
+
+        async def ainvoke(self, tool_input: Any, config: Any = None, **kwargs: Any) -> Any:  # type: ignore[override]
+            h = _hash_tool_input(tool_input)
+            key = f"{self._key_prefix}:{self.name}:{h}"
+
+            res = await self._client.check_lock_async(key=key, ttl=self._ttl, meta=self._meta)
+            if res.duplicate:
+                return f"Action '{self.name}' skipped (idempotency key duplicate)."
+
+            ainvoke = getattr(self._tool, "ainvoke", None)
+            if callable(ainvoke):
+                if config is None:
+                    return await ainvoke(tool_input, **kwargs)
+                return await ainvoke(tool_input, config=config, **kwargs)
+
+            # Fallback
+            if config is None:
+                return self._tool.invoke(tool_input, **kwargs)
+            return self._tool.invoke(tool_input, config=config, **kwargs)
+
+        # Keep BaseTool abstract contract satisfied; not used because we override invoke/ainvoke.
+        def _run(self, *args: Any, **kwargs: Any) -> Any:
+            raise RuntimeError("IdempotentTool delegates via invoke(); _run() should not be called.")
+
+        async def _arun(self, *args: Any, **kwargs: Any) -> Any:
+            raise RuntimeError("IdempotentTool delegates via ainvoke(); _arun() should not be called.")
+
+    return IdempotentTool()

onceonly/models.py

@@ -14,3 +14,14 @@ class CheckLockResult:
     request_id: Optional[str]
     status_code: int
     raw: Dict[str, Any]
+
+    def should_proceed(self) -> bool:
+        """
+        Helper for agents/tools:
+        - True => proceed with the expensive/side-effect operation
+        - False => treat as duplicate (or blocked)
+        """
+        return bool(self.locked) and not bool(self.duplicate)
+
+    def is_duplicate(self) -> bool:
+        return bool(self.duplicate)

onceonly/version.py

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

onceonly_sdk-2.0.1.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: onceonly-sdk
+Version: 2.0.1
+Summary: Python SDK for OnceOnly idempotency API
+Author-email: OnceOnly <support@onceonly.tech>
+License: MIT
+Project-URL: Homepage, https://onceonly.tech/
+Project-URL: Documentation, https://onceonly.tech/docs/
+Project-URL: Repository, https://github.com/mykolademyanov/onceonly-python
+Keywords: idempotency,automation,zapier,make,ai-agents
+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
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: anyio>=4.0; extra == "test"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
+Dynamic: license-file
+
+# OnceOnly Python SDK
+
+**The Idempotency Layer for AI Agents, Webhooks, and Distributed Systems.**
+
+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/
+
+---
+
+## Features
+
+- Sync + Async client (httpx-based)
+- Fail-open mode for production safety
+- Stable idempotency keys (supports Pydantic & dataclasses)
+- Decorators for zero-boilerplate usage
+- Native AI API (long-running jobs, local side-effects)
+- Optional AI / LangChain integrations
+
+---
+
+## Installation
+
+```bash
+pip install onceonly-sdk
+```
+
+### With LangChain support included:
+
+```bash
+pip install "onceonly-sdk[langchain]"
+```
+
+---
+
+## Quick Start (Webhooks / Automations)
+
+```python
+from onceonly import OnceOnly
+
+client = OnceOnly(
+    api_key="once_live_...",
+    fail_open=True  # default: continues if API is down
+)
+
+res = client.check_lock(key="order:123", ttl=300)
+
+if res.duplicate:
+    print("Duplicate blocked")
+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 / 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
+
+tool = make_idempotent_tool(
+    original_tool,
+    client=client,
+    key_prefix="agent:tool"
+)
+```
+
+Repeated tool calls with the same inputs will execute **exactly once**,
+even across retries or agent restarts.
+
+See `examples/ai/` for canonical patterns.
+
+---
+
+## Decorators
+
+```python
+from onceonly.decorators import idempotent
+
+@idempotent(client, ttl=3600)
+def process_order(order_id):
+    ...
+```
+
+Idempotency keys are generated automatically and remain stable across restarts.
+
+---
+
+## Fail-Open Mode
+
+Fail-open is enabled by default.
+
+Network errors, timeouts, or server errors (5xx) will **not break your application**.
+The SDK will allow execution to continue safely.
+
+Fail-open never applies to:
+- Auth errors (401 / 403)
+- Plan limits (402)
+- Validation errors (422)
+- Rate limits (429)
+
+---
+
+## Support
+
+Need help?  
+Email: support@onceonly.tech  
+Or open an issue on GitHub.
+
+---
+
+## License
+
+MIT

onceonly_sdk-2.0.1.dist-info/RECORD

@@ -0,0 +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=-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=wAxkK8w13vqoF47A8iqWdSlIgRRXmZiQ0R4wePZfzhs,22
+onceonly/integrations/__init__.py,sha256=0tk-2HTTsmc42NhWuR_G_Afmz5-5WG8NvmlO7iIPkIY,34
+onceonly/integrations/langchain.py,sha256=cdpHIluddX48uYeDeE1cxmn-arruVdE3k6gvZxYC9z4,5821
+onceonly_sdk-2.0.1.dist-info/licenses/LICENSE,sha256=YQQ8IT_P7hcGmmLFFuOy3eKDZ90e1cqef_okg85oAiQ,129
+onceonly_sdk-2.0.1.dist-info/METADATA,sha256=j1xhLIcpLYW6x4qmLKJp8qoKbDHrOhueu6beqF6DVmI,4131
+onceonly_sdk-2.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+onceonly_sdk-2.0.1.dist-info/top_level.txt,sha256=lvz-sHerZcTwlZW-uYoda_wgx62kY07GdtzIdw89hnU,9
+onceonly_sdk-2.0.1.dist-info/RECORD,,

onceonly_sdk-1.2.0.dist-info/METADATA

@@ -1,153 +0,0 @@
-Metadata-Version: 2.4
-Name: onceonly-sdk
-Version: 1.2.0
-Summary: Python SDK for OnceOnly idempotency API
-Author-email: OnceOnly <support@onceonly.tech>
-License: MIT
-Project-URL: Homepage, https://onceonly.tech/
-Project-URL: Documentation, https://onceonly.tech/docs/
-Project-URL: Repository, https://github.com/mykolademyanov/onceonly-python
-Keywords: idempotency,automation,zapier,make,ai-agents
-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
-License-File: LICENSE
-Requires-Dist: httpx>=0.25
-Provides-Extra: test
-Requires-Dist: pytest>=7.0; extra == "test"
-Dynamic: license-file
-
-# OnceOnly Python SDK
-
-**The Idempotency Layer for AI Agents, Webhooks, and Distributed Systems.**
-
-OnceOnly is a high-performance Python SDK designed to ensure **exactly-once execution**.
-It prevents duplicate actions (payments, emails, tool calls) in unstable environments like
-AI agents, webhooks, or background workers.
-
-Website - https://onceonly.tech/ai/
-
-[![PyPI version](https://img.shields.io/pypi/v/onceonly.svg)](https://pypi.org/project/onceonly-sdk/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
----
-
-## Features
-
-- **Sync + Async Client** — built on httpx for modern Python stacks
-- **Connection Pooling** — high performance under heavy load
-- **Fail-Open Mode** — business logic keeps running even if API is unreachable
-- **Smart Decorator** — automatic idempotency based on function arguments
-- **Typed Results & Exceptions**
-
----
-
-## Installation
-
-```bash
-pip install onceonly-sdk
-```
-
----
-
-## Quick Start
-
-```python
-from onceonly import OnceOnly
-
-client = OnceOnly(api_key="once_live_...")
-
-result = client.check_lock(
-    key="order:123",
-    ttl=300, # 300 seconds = 5 minutes (clamped by your plan)
-)
-
-if result.duplicate:
-    print("Duplicate blocked")
-else:
-    print("First execution")
-```
-
----
-
-## Async Usage
-
-```python
-async def handler():
-    result = await client.check_lock_async("order:123")
-    if result.locked:
-        print("Locked")
-```
-
----
-
-## TTL Behavior
-
-- TTL is specified in seconds
-- If ttl is not provided, the server applies the plan default TTL
-- If ttl is provided, it is automatically clamped to your plan limits
-
----
-
-## Metadata
-
-You can optionally attach metadata to each check-lock call.
-Metadata is useful for debugging, tracing, and server-side analytics.
-
-Rules:
-- JSON-serializable only
-- Size-limited
-- Safely logged on the server
-
----
-
-## Decorator
-
-The SDK provides an optional decorator that automatically generates
-an idempotency key based on the **function name and arguments**.
-
-This allows you to add exactly-once guarantees to existing code
-with zero manual key management.
-
-```python
-from onceonly.decorators import idempotent
-
-@idempotent(client, ttl=3600)
-def process_order(order_id):
-    ...
-```
-
----
-
-## Fail-Open Mode
-
-Enabled by default.
-
-If a network error, timeout, or server error (5xx) occurs, the SDK returns a locked result
-instead of breaking your application.
-
-Fail-open never triggers for:
-- Authentication errors (401 / 403)
-- Plan limits (402)
-- Validation errors (422)
-- Rate limits (429)
-
----
-
-## Exceptions
-
-| Exception          | HTTP Status | Description                              |
-|--------------------|------------|------------------------------------------|
-| UnauthorizedError  | 401 / 403  | Invalid or disabled API key               |
-| OverLimitError     | 402        | Plan limit reached                        |
-| RateLimitError     | 429        | Too many requests                         |
-| ValidationError    | 422        | Invalid input                             |
-| ApiError           | 5xx / other| Server or unexpected API error            |
-
----
-
-## License
-
-MIT

onceonly_sdk-1.2.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-onceonly/__init__.py,sha256=_SwJ4Y2345WJKfpW2IsOVfgNaUzjZqTSSOnPQBroW-M,452
-onceonly/client.py,sha256=1RMTkGDpalHfx-xEH8DZsn9ZJ3VeGomG6PKAQQjPdZQ,13361
-onceonly/decorators.py,sha256=9eBhRUQDBGTUXVyRYlpYy77y-EHF-udX3ERkrfIt9Kg,2651
-onceonly/exceptions.py,sha256=RP556LUtO54TPFTZybF4dVA9n3TByFn35esz7EbcrpY,994
-onceonly/models.py,sha256=xhPfP1kpyHYfKJNiac2REeXTpPLzrEWJeqn-p6B6taQ,329
-onceonly_sdk-1.2.0.dist-info/licenses/LICENSE,sha256=YQQ8IT_P7hcGmmLFFuOy3eKDZ90e1cqef_okg85oAiQ,129
-onceonly_sdk-1.2.0.dist-info/METADATA,sha256=dvml-Mhrd_n0xFEhk7-rvShxiYfaLcl_Pq2vyGD0XRo,3891
-onceonly_sdk-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-onceonly_sdk-1.2.0.dist-info/top_level.txt,sha256=lvz-sHerZcTwlZW-uYoda_wgx62kY07GdtzIdw89hnU,9
-onceonly_sdk-1.2.0.dist-info/RECORD,,