Package com.tnsai.idempotency

Interface IdempotencyKeySupplier

public interface IdempotencyKeySupplier
Opt-in interface a tool POJO implements to supply its own idempotency key under KeyStrategy.EXPLICIT (issue #91).

Use when KeyStrategy.HASH_INPUT (the default) would over- or under-dedupe — for example when only one input field is the natural identity of the operation, or when the input contains volatile fields that should not affect dedup (timestamps, request-scoped UUIDs).

Example


 public class CreateIssueTool implements IdempotencyKeySupplier {

     @Tool(description = "Create a GitHub issue")
     @Idempotent(strategy = KeyStrategy.EXPLICIT)
     public IssueResult createIssue(@ToolParam String title,
                                    @ToolParam String body) { ... }

     @Override
     public String idempotencyKeyFor(Map<String, Object> input) {
         // Dedupe by title only — body edits don't create a duplicate.
         return "issue:" + ((String) input.get("title")).toLowerCase(java.util.Locale.ROOT);
     }
 }

The framework prefixes the supplier's return value with the tool name so two tools that happen to return the same explicit key do not collide — implementations only need to make the key unique within the tool, not across the whole agent.

Guarded static-tool dispatch supplies a read-only map containing the effective values after defaults, type coercion, and input sanitization; those same values are used for body invocation. Other call sites define their own map mutability and value-normalization semantics. Suppliers should not rely on mutating the map or values obtained from it.

Since:
0.8.6 (issue #91 — wiring follow-up to PR #108)

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    idempotencyKeyFor(Map<String,Object> input)
    Compute the per-call idempotency key for the given LLM argument map.

  • Method Details

    • idempotencyKeyFor

      String idempotencyKeyFor(Map<String,Object> input)
      Compute the per-call idempotency key for the given LLM argument map.

      Must return a non-null, non-blank string. Throwing from this method aborts the call with the original throwable surfaced as the cause of an IdempotencyException carrying IdempotencyException.IdempotencyConflict.STORE_UNAVAILABLE.

      Parameters:
      input - the call site's argument map (never null; possibly empty or containing null optional values); guarded static-tool dispatch provides a read-only map
      Returns:
      the explicit idempotency key for this call