[v2.0.1] finalize AI client, lease API, and canonical examples

Author: mykolademyanov

examples/README.md

@@ -1,16 +1,17 @@
 # OnceOnly Python SDK — Examples
 
 This folder contains **small, runnable examples** demonstrating how to use the OnceOnly Python SDK.
+
 Examples are organized into two groups:
 
 - `examples/general/` — core idempotency use cases (webhooks, workers, automations)
-- `examples/ai/` — AI agent and tool-calling integrations
+- `examples/ai/` — AI agents, long-running jobs, and tool-calling integrations
 
 ---
 
 ## Prerequisites
 
-1) Install the SDK (from repo root):
+1) Install the SDK (from repository root):
 
 ```bash
 pip install -e .
@@ -28,7 +29,7 @@ All examples read `ONCEONLY_API_KEY` from the environment.
 
 ## Running examples
 
-From the repository root:
+Always run examples from the repository root:
 
 ```bash
 python examples/general/basic_check_lock.py
@@ -42,7 +43,7 @@ python examples/general/basic_check_lock.py
 Minimal idempotency primitive.
 
 - First call → `locked=True`
-- Second call with same key → `duplicate=True`
+- Second call with the same key → `duplicate=True`
 
 Use this pattern for:
 - Webhooks
@@ -64,10 +65,10 @@ Demonstrates TTL behavior.
 Attaches metadata to an idempotency key.
 
 Typical metadata:
-- user_id
-- scenario_id
-- webhook_event_id
-- trace_id
+- `user_id`
+- `scenario_id`
+- `webhook_event_id`
+- `trace_id`
 
 Metadata is useful for debugging and analytics.
 If the server does not echo it back, the SDK preserves it in `result.raw`.
@@ -98,7 +99,7 @@ Designed for:
 ---
 
 ### `decorator_pydantic.py`
-Advanced decorator example with **Pydantic models**.
+Advanced decorator example using **Pydantic models**.
 
 Highlights:
 - Stable hashing for complex objects
@@ -113,7 +114,7 @@ This solves a common pain point for AI and API developers.
 Inspect account and usage information.
 
 Endpoints used:
-- `/v1/me` — API key & plan info
+- `/v1/me` — API key and plan info
 - `/v1/usage` — current usage vs limits
 
 Useful for:
@@ -123,84 +124,92 @@ Useful for:
 
 ---
 
-## AI / Agent examples (`examples/ai/`)
+## AI examples (`examples/ai/`)
 
-### `agent_guard_manual.py`
-Manual guard pattern for AI agents.
+### `run_and_wait.py`
+Canonical long-running AI job example.
 
-- Call `check_lock()` before performing a tool action
-- Abort immediately if duplicate
+- Uses `/v1/ai/run`
+- Polls status until completion
+- Charged **once per key**, polling is free
 
 Best for:
-- Custom agent loops
-- Tool routing
-- Expensive API calls
+- Background AI jobs
+- Batch processing
+- Server-side agents
 
 ---
 
-### `agent_retry_safe.py`
-Agent restart / retry safety example.
+### `agent_action_local.py`
+Local side-effect guard using the AI Lease API.
 
-- Run the script once: performs the side-effect
-- Run it again: duplicate is detected and the side-effect is skipped
+- Uses `/v1/ai/lease`
+- Executes the side-effect locally
+- Ensures exactly-once execution across retries and crashes
 
-This is a core pattern for autonomous agents that can crash, retry, or resume.
+Best for:
+- Payments
+- Emails
+- Webhooks triggered by agents
 
 ---
 
-### `langchain_tool.py`
-LangChain integration example.
+### `poll_status.py`
+Polling example for AI jobs.
 
-- Wraps a standard LangChain `Tool`
-- Automatically enforces idempotency
-- Prevents double execution of side-effects
+- Uses `/v1/ai/status`
+- Demonstrates `retry_after_sec` and adaptive polling
 
-Optional dependency:
+---
 
-```bash
-pip install langchain-core
-```
+### `get_result.py`
+Fetches the final result of a completed AI job.
 
-Works well with:
-- LangChain agents
-- Tool-calling LLMs
-- Multi-step plans
+- Uses `/v1/ai/result`
+- Safe to call multiple times
 
 ---
 
-### `long_running_job.py`
-Long-running AI / backend job example.
+### `langchain_tool_ai_lease.py`
+LangChain integration example using the AI Lease API.
 
-- Uses OnceOnly AI client helpers
-- Demonstrates run → poll → wait pattern
-- Suitable for batch AI jobs or background processing
+- Wraps a LangChain tool
+- Guarantees exactly-once tool execution
+- Prevents double side-effects
+- Protects against LLM 'hallucinations' causing multiple tool calls
+
+Optional dependency:
+
+```bash
+pip install langchain-core
+```
 
 ---
 
 ## Design tips
 
-- **Key design:** Model keys after real-world actions  
+- **Key design:** model keys after real-world actions  
   Example:
   ```
   agent:email:user42:welcome
-  make:scenario:123:event:evt_abc
+  ai:job:daily_summary:2026-01-09
   ```
 
-- **TTL:** Choose TTL based on how long a duplicate would be dangerous
+- **TTL:** choose TTL based on how long a duplicate would be dangerous
 
-- **Fail-open:**  
-  - `fail_open=True` (default): safer for production workflows  
+- **Fail-open behavior:**
+  - `fail_open=True` (default): safer for production workflows
   - `fail_open=False`: strict correctness for critical paths
 
 ---
 
 ## Troubleshooting
 
 - **401 / 403** — invalid or missing API key
-- **402** — plan limit reached
-- **429** — rate limit exceeded (backoff & retry)
+- **402** — plan or usage limit reached
+- **429** — rate limit exceeded (retry with backoff)
 - **5xx** — server error (fail-open may apply)
 
 ---
 
-If you need an additional example, open an issue or PR.
+If you need additional examples, open an issue or submit a PR.

examples/ai/agent_action_local.py

@@ -0,0 +1,76 @@
+"""
+Local agent/tool side effect guard using the AI Lease API.
+
+This pattern is for cases when YOUR CODE performs the side-effect locally,
+but you still want:
+- AI pricing/limits (AI usage)
+- exactly-once execution across retries/crashes
+
+Flow:
+  1) POST /ai/lease (charged only if acquired)
+  2) If acquired -> do side effect locally
+  3) POST /ai/complete or /ai/fail
+
+Run this file twice: second run should NOT do the side effect again.
+"""
+
+import os
+from onceonly import OnceOnly
+
+API_KEY = os.getenv("ONCEONLY_API_KEY")
+if not API_KEY:
+    raise SystemExit("Set ONCEONLY_API_KEY env var")
+
+client = OnceOnly(api_key=API_KEY)
+
+KEY = "ai:agent:charge:user_42:invoice_101"
+
+
+def do_side_effect() -> dict:
+    # (charge, refund, email, etc.)
+    print(">>> Charging...")
+    return {"ok": True}
+
+
+def main() -> None:
+    try:
+        lease = client.ai.lease(key=KEY, ttl=300, metadata={"kind": "charge", "user": "user_42", "invoice": "100"})
+        status = (lease.get("status") or "").lower()
+
+        if status == "acquired":
+            lease_id = lease.get("lease_id")
+            if not lease_id:
+                raise RuntimeError(f"Missing lease_id in response: {lease}")
+
+            try:
+                result = do_side_effect()
+            except Exception:
+                # mark failed so you can retry later deterministically
+                client.ai.fail(key=KEY, lease_id=lease_id, error_code="charge_failed")
+                raise
+            else:
+                client.ai.complete(key=KEY, lease_id=lease_id, result=result)
+                print("Done.")
+                return
+
+        if status == "completed":
+            res = client.ai.result(KEY)
+            # res.result may be dict or None depending on your backend model
+            print(f"Already done previously: {getattr(res, 'result', None)}")
+            return
+
+        if status == "failed":
+            # Optional: fetch final result to show error_code / details if backend stores it
+            res = client.ai.result(KEY)
+            print(f"Previously failed: {getattr(res, 'error_code', None)}")
+            return
+
+        # in_progress / locked / running / etc.
+        print(f"Action in progress by another worker. Status: {status}")
+
+    except Exception as e:
+        print(f"SDK or Network error: {e}")
+
+
+if __name__ == "__main__":
+    main()

examples/ai/agent_guard_manual.py

@@ -0,0 +1,16 @@
+import os
+from onceonly import OnceOnly
+
+API_KEY = os.getenv("ONCEONLY_API_KEY")
+if not API_KEY:
+    raise SystemExit("Set ONCEONLY_API_KEY env var")
+
+client = OnceOnly(api_key=API_KEY)
+
+key = "ai:job:daily-summary:2026-01-09"
+
+# If you already know the job is done, fetch result directly:
+res = client.ai.result(key)
+print("status:", res.status)
+print("result:", res.result)
+print("error:", res.error_code)