latch-idempotent 0.1.0__tar.gz

latch_idempotent-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Type check
+        run: mypy src/latch
+      - name: Test
+        run: pytest -v

latch_idempotent-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+.env
+.coverage
+htmlcov/
+.DS_Store

latch_idempotent-0.1.0/CLAUDE.md

@@ -0,0 +1,111 @@
+# latch — Idempotency Middleware for LLM Agent Tool Calls
+
+This file is the persistent context for Claude Code working in this repo. Read it fully before making changes. Keep it updated as phases complete.
+
+## Mission
+
+`latch` is a small, dependency-free Python library that makes LLM agent tool calls safe to retry. When an agent's tool call times out or errors, the agent doesn't know whether the underlying action actually completed — retrying blindly can double-charge a card, send a duplicate email, or create a duplicate order. `latch` prevents that: wrap a tool function with `@idempotent`, pass a unique `idempotency_key` per logical operation, and repeated calls with the same key return the cached result instead of re-executing.
+
+## Why this exists (prior art — be honest about it)
+
+This is not an unclaimed idea. Before building, we searched and found:
+- **SagaLLM** (arXiv 2503.11951) — academic paper applying the Saga pattern to multi-agent LLM planning with compensation.
+- **Robust Agent Compensation (RAC)** (ACM CAIS '26) — academic paper on teaching agents to compensate for failures.
+- **ReliabilityBench** (arXiv 2601.06112) — a benchmark for agent reliability under stress, not a library.
+- Multiple engineering blog posts (Zylos Research, MightyBot, Chanl, TianPan.co) describe idempotency-for-agents as a pattern, but none of them shipped a polished, adoptable, framework-agnostic OSS package for it.
+
+**The gap we're actually filling:** nobody has shipped the practical, pip-installable version of this pattern. The contribution of v0.1 is execution and adoptability, not novelty of the underlying idea. Don't oversell originality in the README or paper — cite the above as prior art and position `latch` as "the missing implementation," not "the first to think of this."
+
+## Scope
+
+### v0.1 (current phase — idempotency only)
+- `@idempotent` decorator for sync and async functions
+- Pluggable `IdempotencyStore` interface
+- `InMemoryStore` (default, thread-safe, TTL-based expiry)
+- Explicit, required `idempotency_key` kwarg (caller/agent framework supplies it — `latch` does not guess or auto-hash args, because silent auto-keying can hide bugs)
+- Tests for sync, async, cache-hit, cache-miss, missing-key error, and TTL expiry
+- One usage example for a plain function and one for an OpenAI-style tool call
+
+### Explicit non-goals for v0.1 (do not build yet)
+- Circuit breaker (v0.2)
+- Timeout/cancellation propagation (v0.2)
+- Budget/cost guardrails (v0.2)
+- Saga/compensation (v0.3)
+- Framework adapters beyond a documented example (v0.3 — real adapter package)
+- Redis store (stub the interface only; implement in v0.2 as an optional extra)
+- Distributed tracing/observability (v0.4)
+
+Resist scope creep. Ship v0.1 narrow and solid before touching v0.2.
+
+## Roadmap (from the 90-day plan)
+
+- [x] v0.1 — Idempotency core + in-memory store + tests + docs
+- [ ] v0.2 — Circuit breaker, timeout/cancellation, budget guardrails, Redis store
+- [ ] v0.3 — Saga/compensation pattern, real OpenAI + LangChain adapter modules
+- [ ] v0.4 — Chaos-injection benchmark harness, example agents (before/after), tracing hooks
+- [ ] v1.0 — Docs site, public launch, paper submitted to arXiv
+
+Update the checkboxes above as phases land.
+
+## API design (already decided — implement to this contract)
+
+```python
+from latch import idempotent, InMemoryStore
+
+store = InMemoryStore()
+
+@idempotent(store=store, ttl_seconds=86400)
+def create_order(order_id: str, amount: float) -> dict:
+    # idempotency_key is consumed by the decorator, not passed to this function
+    ...
+    return {"order_id": order_id, "status": "created"}
+
+# Agent framework supplies a unique key per logical operation:
+create_order(order_id="A1", amount=42.0, idempotency_key="agent-run-7-step-3")
+```
+
+Key behaviors:
+- `idempotency_key` is a required keyword argument at call time. If missing, raise `IdempotencyKeyMissingError` — never silently generate one.
+- On a cache hit within the TTL window, return the cached result without calling the wrapped function.
+- On a cache miss, execute the function, store the result keyed by `idempotency_key`, and return it.
+- Must work transparently on both `def` and `async def` functions.
+- No required third-party dependencies for the core. Redis support is an optional extra (`pip install latch-idempotent[redis]`).
+
+## Architecture principles
+
+- Core has zero required dependencies — anyone can `pip install` it without dragging in redis/httpx/etc.
+- `IdempotencyStore` is an abstract interface (`get`, `set`, `exists`) so storage backends are swappable.
+- Every public function is type-hinted; run `mypy` clean.
+- Every behavior has a test before being considered done — no untested code paths in `core.py`.
+- Keep files small and single-purpose (`core.py`, `stores/memory.py`, `exceptions.py` — don't merge concerns).
+
+## Conventions
+
+- Format/lint with `ruff`; format with `black` (or ruff format).
+- Conventional commit messages (`feat:`, `fix:`, `test:`, `docs:`, `chore:`).
+- Every new feature: implementation + tests + README update in the same commit/PR.
+- Run `pytest` before considering any task complete.
+
+## Definition of done for v0.1
+
+1. `pytest` passes with tests covering: sync dedup, async dedup, different-key re-execution, missing-key error, TTL expiry.
+2. `mypy src/latch` is clean.
+3. README has a working quickstart example that a stranger could copy-paste and run.
+4. Package builds (`python -m build`) and is ready to publish to PyPI (actual publish is a manual step — don't automate credentials).
+5. `examples/openai_example.py` shows the decorator wrapping an OpenAI-style tool function.
+
+## Immediate next tasks (work through in order)
+
+1. Verify the scaffolded code in `src/latch/` builds and `pytest` passes as-is.
+2. Add TTL-expiry test (not yet covered by the scaffold — see `tests/test_core.py` TODO).
+3. Write `examples/openai_example.py`.
+4. Set up `ruff` + `mypy` config and run them clean.
+5. Set up GitHub Actions CI (test + lint on push).
+6. Once v0.1 is solid: write the launch README section, tag `v0.1.0`, publish to PyPI, post on GitHub.
+7. Only then move to v0.2 (circuit breaker) — do not start v0.2 work before v0.1 is tagged and published.
+
+## Non-negotiables
+
+- Don't silently swallow errors — if the wrapped function raises, `latch` should propagate the exception and NOT cache a failed result.
+- Don't auto-generate idempotency keys from function args by default — that's a footgun (subtly different args should sometimes get different keys, sometimes not, and only the caller knows which).
+- Keep the public API tiny. Every new parameter on `idempotent()` should justify its complexity cost.

latch_idempotent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Venkata Sangaraju
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

latch_idempotent-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: latch-idempotent
+Version: 0.1.0
+Summary: Idempotency middleware for LLM agent tool calls — prevent duplicate side effects on retry.
+Project-URL: Homepage, https://github.com/YOUR_USERNAME/latch
+Project-URL: Issues, https://github.com/YOUR_USERNAME/latch/issues
+Author: Venkata Sangaraju
+License: MIT
+License-File: LICENSE
+Keywords: agents,idempotency,llm,reliability,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# latch
+
+Idempotency middleware for LLM agent tool calls. Prevents duplicate side effects (double-charged orders, duplicate emails, duplicate records) when an agent retries a tool call after a timeout or transient failure.
+
+## The problem
+
+An agent calls a tool. The call times out. The agent doesn't know if the underlying action completed before the timeout — it just knows it didn't get a response. Retrying is the only reasonable move, but if the tool isn't idempotent, retrying can execute the side effect twice.
+
+## Install
+
+```bash
+pip install latch-idempotent
+```
+
+## Quickstart
+
+```python
+from latch import idempotent
+
+@idempotent()
+def create_order(order_id: str, amount: float) -> dict:
+    # ... call your payment/order API ...
+    return {"order_id": order_id, "status": "created"}
+
+# The agent framework supplies a unique key per logical operation.
+result = create_order(order_id="A1", amount=42.0, idempotency_key="run-7-step-3")
+
+# A retry with the same key returns the cached result instead of
+# re-executing create_order — no duplicate order.
+result_again = create_order(order_id="A1", amount=42.0, idempotency_key="run-7-step-3")
+assert result == result_again
+```
+
+Works the same way for `async def` tool functions.
+
+## How it works
+
+- `idempotency_key` is a required keyword argument — `latch` never guesses or auto-generates one. The caller (your agent framework or orchestration code) decides what constitutes "the same logical operation."
+- On first call with a given key, the function executes and the result is cached.
+- On any subsequent call with the same key, within the TTL window (default 24h), the cached result is returned and the function is not re-executed.
+- If the wrapped function raises, nothing is cached — the exception propagates normally so retries can still happen.
+
+## Storage backends
+
+Default is an in-memory store (single-process, not persistent across restarts). For multi-process or production deployments, use a distributed store:
+
+```python
+from latch import idempotent, InMemoryStore
+
+store = InMemoryStore()
+
+@idempotent(store=store, ttl_seconds=3600)
+def send_email(to: str) -> dict:
+    ...
+```
+
+Redis backend is planned for v0.2 (`pip install latch-idempotent[redis]`).
+
+## Status
+
+v0.1 — idempotency only. See `CLAUDE.md` for the roadmap (circuit breaker, budget guardrails, saga/compensation, and framework adapters are planned for later versions).
+
+## Prior art
+
+This library exists alongside academic work on agent reliability — see [SagaLLM](https://arxiv.org/abs/2503.11951), [Robust Agent Compensation](https://arxiv.org/pdf/2605.03409), and [ReliabilityBench](https://arxiv.org/pdf/2601.06112). `latch`'s contribution is a small, adoptable, production-ready implementation of the idempotency pattern specifically — not a claim of inventing it.
+
+## License
+
+MIT

latch_idempotent-0.1.0/README.md

@@ -0,0 +1,69 @@
+# latch
+
+Idempotency middleware for LLM agent tool calls. Prevents duplicate side effects (double-charged orders, duplicate emails, duplicate records) when an agent retries a tool call after a timeout or transient failure.
+
+## The problem
+
+An agent calls a tool. The call times out. The agent doesn't know if the underlying action completed before the timeout — it just knows it didn't get a response. Retrying is the only reasonable move, but if the tool isn't idempotent, retrying can execute the side effect twice.
+
+## Install
+
+```bash
+pip install latch-idempotent
+```
+
+## Quickstart
+
+```python
+from latch import idempotent
+
+@idempotent()
+def create_order(order_id: str, amount: float) -> dict:
+    # ... call your payment/order API ...
+    return {"order_id": order_id, "status": "created"}
+
+# The agent framework supplies a unique key per logical operation.
+result = create_order(order_id="A1", amount=42.0, idempotency_key="run-7-step-3")
+
+# A retry with the same key returns the cached result instead of
+# re-executing create_order — no duplicate order.
+result_again = create_order(order_id="A1", amount=42.0, idempotency_key="run-7-step-3")
+assert result == result_again
+```
+
+Works the same way for `async def` tool functions.
+
+## How it works
+
+- `idempotency_key` is a required keyword argument — `latch` never guesses or auto-generates one. The caller (your agent framework or orchestration code) decides what constitutes "the same logical operation."
+- On first call with a given key, the function executes and the result is cached.
+- On any subsequent call with the same key, within the TTL window (default 24h), the cached result is returned and the function is not re-executed.
+- If the wrapped function raises, nothing is cached — the exception propagates normally so retries can still happen.
+
+## Storage backends
+
+Default is an in-memory store (single-process, not persistent across restarts). For multi-process or production deployments, use a distributed store:
+
+```python
+from latch import idempotent, InMemoryStore
+
+store = InMemoryStore()
+
+@idempotent(store=store, ttl_seconds=3600)
+def send_email(to: str) -> dict:
+    ...
+```
+
+Redis backend is planned for v0.2 (`pip install latch-idempotent[redis]`).
+
+## Status
+
+v0.1 — idempotency only. See `CLAUDE.md` for the roadmap (circuit breaker, budget guardrails, saga/compensation, and framework adapters are planned for later versions).
+
+## Prior art
+
+This library exists alongside academic work on agent reliability — see [SagaLLM](https://arxiv.org/abs/2503.11951), [Robust Agent Compensation](https://arxiv.org/pdf/2605.03409), and [ReliabilityBench](https://arxiv.org/pdf/2601.06112). `latch`'s contribution is a small, adoptable, production-ready implementation of the idempotency pattern specifically — not a claim of inventing it.
+
+## License
+
+MIT

latch_idempotent-0.1.0/examples/basic_example.py

@@ -0,0 +1,23 @@
+"""Minimal usage example: an order-creation tool made retry-safe with latch."""
+
+from latch import idempotent
+
+
+@idempotent()
+def create_order(order_id: str, amount: float) -> dict:
+    print(f"Charging {amount} for order {order_id}...")  # simulates a real side effect
+    return {"order_id": order_id, "amount": amount, "status": "created"}
+
+
+if __name__ == "__main__":
+    # First call executes and charges.
+    result = create_order(order_id="A1", amount=42.0, idempotency_key="run-7-step-3")
+    print("First call result:", result)
+
+    # Simulated retry after a timeout, same logical operation, same key.
+    # This does NOT charge again — it returns the cached result.
+    retry_result = create_order(order_id="A1", amount=42.0, idempotency_key="run-7-step-3")
+    print("Retry result:", retry_result)
+
+    assert result == retry_result
+    print("No duplicate charge on retry.")

latch_idempotent-0.1.0/examples/openai_example.py

@@ -0,0 +1,46 @@
+"""Example: wrapping an OpenAI tool-calling function with latch.
+
+This shows the shape of the integration; it doesn't require an actual
+OpenAI API call to demonstrate the idempotency behavior. In a real agent
+loop, `idempotency_key` would typically be derived from something like
+`f"{run_id}:{step_id}"` and passed alongside the tool call arguments the
+model returns.
+
+TODO (v0.3): a real `latch.adapters.openai` module that auto-wraps a list
+of tool functions and injects idempotency_key generation into the agent
+loop, so callers don't have to thread it through manually.
+"""
+
+from latch import idempotent
+
+
+@idempotent()
+def send_email(to: str, subject: str, body: str) -> dict:
+    print(f"Sending email to {to}: {subject}")
+    return {"to": to, "subject": subject, "status": "sent"}
+
+
+def handle_tool_call(tool_name: str, arguments: dict, run_id: str, step_id: str) -> dict:
+    """Simulates how an agent loop would dispatch a model-requested tool call."""
+    idempotency_key = f"{run_id}:{step_id}"
+
+    if tool_name == "send_email":
+        return send_email(**arguments, idempotency_key=idempotency_key)
+
+    raise ValueError(f"Unknown tool: {tool_name}")
+
+
+if __name__ == "__main__":
+    args = {"to": "user@example.com", "subject": "Welcome", "body": "Hi there!"}
+
+    # First attempt.
+    result = handle_tool_call("send_email", args, run_id="run-42", step_id="step-1")
+    print("First attempt:", result)
+
+    # Agent retries the same step after a timeout — same run_id/step_id,
+    # so the same idempotency_key is derived, and no duplicate email is sent.
+    retry = handle_tool_call("send_email", args, run_id="run-42", step_id="step-1")
+    print("Retry:", retry)
+
+    assert result == retry
+    print("No duplicate email sent on retry.")

latch_idempotent-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "latch-idempotent"
+version = "0.1.0"
+description = "Idempotency middleware for LLM agent tool calls — prevent duplicate side effects on retry."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Venkata Sangaraju" }]
+keywords = ["llm", "agents", "idempotency", "reliability", "tool-calling"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = []
+
+[project.optional-dependencies]
+redis = ["redis>=5.0"]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.23", "mypy>=1.8", "ruff>=0.4"]
+
+[project.urls]
+Homepage = "https://github.com/YOUR_USERNAME/latch"
+Issues = "https://github.com/YOUR_USERNAME/latch/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/latch"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true

latch_idempotent-0.1.0/src/latch/__init__.py

@@ -0,0 +1,14 @@
+from latch.core import idempotent
+from latch.exceptions import IdempotencyKeyMissingError, LatchError
+from latch.stores.base import IdempotencyStore
+from latch.stores.memory import InMemoryStore
+
+__all__ = [
+    "idempotent",
+    "IdempotencyStore",
+    "InMemoryStore",
+    "LatchError",
+    "IdempotencyKeyMissingError",
+]
+
+__version__ = "0.1.0"

latch_idempotent-0.1.0/src/latch/core.py

@@ -0,0 +1,89 @@
+import functools
+import inspect
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+from latch.exceptions import IdempotencyKeyMissingError
+from latch.stores.base import IdempotencyStore
+from latch.stores.memory import InMemoryStore
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_DEFAULT_STORE: IdempotencyStore = InMemoryStore()
+_DEFAULT_TTL_SECONDS = 24 * 60 * 60  # 24 hours
+
+
+def idempotent(
+    *,
+    store: Optional[IdempotencyStore] = None,
+    key_arg: str = "idempotency_key",
+    ttl_seconds: int = _DEFAULT_TTL_SECONDS,
+    on_duplicate: Optional[Callable[[str, Any], None]] = None,
+) -> Callable[[F], F]:
+    """Make a tool function idempotent.
+
+    The decorated function must be called with a keyword argument matching
+    `key_arg` (default: "idempotency_key"). If a call with the same key has
+    already completed successfully within `ttl_seconds`, the cached result
+    is returned instead of re-executing the function.
+
+    Works transparently on both sync (`def`) and async (`async def`)
+    functions. The `key_arg` is consumed by the decorator and is not
+    passed through to the wrapped function.
+
+    Args:
+        store: Idempotency storage backend. Defaults to a shared
+            process-wide in-memory store if not provided.
+        key_arg: Name of the keyword argument callers use to supply the
+            idempotency key.
+        ttl_seconds: How long a cached result remains valid.
+        on_duplicate: Optional callback invoked as `on_duplicate(key, cached_result)`
+            when a duplicate call is detected. Useful for logging/metrics.
+
+    Raises:
+        IdempotencyKeyMissingError: if the caller does not supply `key_arg`.
+    """
+    active_store = store if store is not None else _DEFAULT_STORE
+
+    def decorator(func: F) -> F:
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                key = _extract_key(kwargs, key_arg)
+                cached = active_store.get(key)
+                if cached is not None:
+                    if on_duplicate is not None:
+                        on_duplicate(key, cached)
+                    return cached
+                result = await func(*args, **kwargs)
+                active_store.set(key, result, ttl_seconds)
+                return result
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            key = _extract_key(kwargs, key_arg)
+            cached = active_store.get(key)
+            if cached is not None:
+                if on_duplicate is not None:
+                    on_duplicate(key, cached)
+                return cached
+            result = func(*args, **kwargs)
+            active_store.set(key, result, ttl_seconds)
+            return result
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def _extract_key(kwargs: Dict[str, Any], key_arg: str) -> str:
+    if key_arg not in kwargs or kwargs[key_arg] is None:
+        raise IdempotencyKeyMissingError(
+            f"Missing required idempotency key argument '{key_arg}'. "
+            f"Callers (typically the agent framework) must supply a unique "
+            f"key per logical operation so retries can be deduplicated."
+        )
+    # Pop so the wrapped function's own signature stays clean.
+    return str(kwargs.pop(key_arg))

latch_idempotent-0.1.0/src/latch/exceptions.py

@@ -0,0 +1,12 @@
+class LatchError(Exception):
+    """Base exception for all latch errors."""
+
+
+class IdempotencyKeyMissingError(LatchError):
+    """Raised when a decorated function is called without a required
+    `idempotency_key` keyword argument.
+
+    latch never generates idempotency keys automatically — the caller
+    (typically the agent framework or orchestration layer) must supply
+    a key that uniquely identifies the logical operation being performed.
+    """

latch_idempotent-0.1.0/src/latch/stores/__init__.py

@@ -0,0 +1,4 @@
+from latch.stores.base import IdempotencyStore
+from latch.stores.memory import InMemoryStore
+
+__all__ = ["IdempotencyStore", "InMemoryStore"]

latch_idempotent-0.1.0/src/latch/stores/base.py

@@ -0,0 +1,26 @@
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class IdempotencyStore(ABC):
+    """Interface for pluggable idempotency result storage.
+
+    Implementations must be safe to call from concurrent contexts
+    (threads and/or async tasks, depending on where the store is used).
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> Optional[Any]:
+        """Return the cached result for `key`, or None if not present
+        or expired."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def set(self, key: str, value: Any, ttl_seconds: int) -> None:
+        """Store `value` under `key` with the given time-to-live."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def exists(self, key: str) -> bool:
+        """Return True if a non-expired entry exists for `key`."""
+        raise NotImplementedError

latch_idempotent-0.1.0/src/latch/stores/memory.py

@@ -0,0 +1,42 @@
+import threading
+import time
+from typing import Any, Dict, Optional, Tuple
+
+from latch.stores.base import IdempotencyStore
+
+
+class InMemoryStore(IdempotencyStore):
+    """Thread-safe in-memory idempotency store.
+
+    Not persistent across process restarts and not shared across
+    processes/nodes — suitable for development, tests, and single-process
+    deployments. Use a distributed store (e.g. Redis, planned for v0.2)
+    for multi-process or multi-node production deployments.
+    """
+
+    def __init__(self) -> None:
+        self._data: Dict[str, Tuple[Any, float]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Optional[Any]:
+        with self._lock:
+            entry = self._data.get(key)
+            if entry is None:
+                return None
+            value, expires_at = entry
+            if time.time() > expires_at:
+                del self._data[key]
+                return None
+            return value
+
+    def set(self, key: str, value: Any, ttl_seconds: int) -> None:
+        with self._lock:
+            self._data[key] = (value, time.time() + ttl_seconds)
+
+    def exists(self, key: str) -> bool:
+        return self.get(key) is not None
+
+    def clear(self) -> None:
+        """Remove all entries. Primarily useful for tests."""
+        with self._lock:
+            self._data.clear()

latch_idempotent-0.1.0/tests/test_core.py

@@ -0,0 +1,114 @@
+import asyncio
+import time
+
+import pytest
+
+from latch import IdempotencyKeyMissingError, InMemoryStore, idempotent
+
+
+def test_sync_function_executes_once_for_same_key():
+    store = InMemoryStore()
+    calls = []
+
+    @idempotent(store=store)
+    def create_order(order_id, amount):
+        calls.append(order_id)
+        return {"order_id": order_id, "amount": amount, "status": "created"}
+
+    result1 = create_order(order_id="A1", amount=42.0, idempotency_key="key-1")
+    result2 = create_order(order_id="A1", amount=42.0, idempotency_key="key-1")
+
+    assert result1 == result2
+    assert len(calls) == 1  # only executed once
+
+
+def test_sync_function_executes_again_for_different_key():
+    store = InMemoryStore()
+    calls = []
+
+    @idempotent(store=store)
+    def create_order(order_id):
+        calls.append(order_id)
+        return {"order_id": order_id}
+
+    create_order(order_id="A1", idempotency_key="key-1")
+    create_order(order_id="A1", idempotency_key="key-2")
+
+    assert len(calls) == 2
+
+
+def test_missing_key_raises():
+    @idempotent()
+    def do_thing():
+        return "done"
+
+    with pytest.raises(IdempotencyKeyMissingError):
+        do_thing()
+
+
+def test_exception_is_not_cached():
+    store = InMemoryStore()
+    attempts = []
+
+    @idempotent(store=store)
+    def flaky(idempotency_key=None):
+        attempts.append(1)
+        if len(attempts) == 1:
+            raise RuntimeError("transient failure")
+        return "ok"
+
+    with pytest.raises(RuntimeError):
+        flaky(idempotency_key="k1")
+
+    # Retry with the same key should re-execute, not return a cached failure.
+    result = flaky(idempotency_key="k1")
+    assert result == "ok"
+    assert len(attempts) == 2
+
+
+def test_ttl_expiry():
+    store = InMemoryStore()
+    calls = []
+
+    @idempotent(store=store, ttl_seconds=0)
+    def do_thing(idempotency_key=None):
+        calls.append(1)
+        return "done"
+
+    do_thing(idempotency_key="k1")
+    time.sleep(0.01)  # ensure we're past the 0-second TTL
+    do_thing(idempotency_key="k1")
+
+    assert len(calls) == 2  # expired, so it re-executed
+
+
+def test_on_duplicate_callback_invoked():
+    store = InMemoryStore()
+    seen = []
+
+    @idempotent(store=store, on_duplicate=lambda key, result: seen.append((key, result)))
+    def do_thing(idempotency_key=None):
+        return "done"
+
+    do_thing(idempotency_key="k1")
+    do_thing(idempotency_key="k1")
+
+    assert seen == [("k1", "done")]
+
+
+@pytest.mark.asyncio
+async def test_async_function_dedupes():
+    store = InMemoryStore()
+    calls = []
+
+    @idempotent(store=store)
+    async def send_email(to, idempotency_key=None):
+        calls.append(to)
+        await asyncio.sleep(0)
+        return {"sent_to": to}
+
+    r1 = await send_email(to="a@example.com", idempotency_key="k1")
+    r2 = await send_email(to="a@example.com", idempotency_key="k1")
+
+    assert r1 == r2
+    assert len(calls) == 1