proactive-gate 0.2.2__tar.gz → 0.2.4__tar.gz

{proactive_gate-0.2.2 → proactive_gate-0.2.4}/.gitignore

@@ -9,3 +9,6 @@ __pycache__/
 *.egg-info/
 .pytest_cache/
 .mypy_cache/
+
+# uv writes this when the Python package is run locally; the library pins nothing.
+python/uv.lock

{proactive_gate-0.2.2 → proactive_gate-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proactive-gate
-Version: 0.2.2
+Version: 0.2.4
 Summary: Decide whether a proactive assistant may speak now: ordered checks, budgets, quiet hours, JSON policies, shared conformance fixtures with the TypeScript package.
 Project-URL: Homepage, https://bubblegunn.github.io/proactive-gate/
 Project-URL: Repository, https://github.com/Bubblegunn/proactive-gate

{proactive_gate-0.2.2 → proactive_gate-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "proactive-gate"
-version = "0.2.2"
+version = "0.2.4"
 description = "Decide whether a proactive assistant may speak now: ordered checks, budgets, quiet hours, JSON policies, shared conformance fixtures with the TypeScript package."
 readme = "README.md"
 requires-python = ">=3.11"

{proactive_gate-0.2.2 → proactive_gate-0.2.4}/src/proactive_gate/checks.py

@@ -526,6 +526,58 @@ class OnlyWhen(BaseCheck):
         return None
 
 
+def dedupe_key_for(user_id: str, key: str) -> str:
+    return f"dedupe:{user_id}:{key}"
+
+
+def _human_window(seconds: int) -> str:
+    if seconds % DAY_SECONDS == 0:
+        return f"{seconds // DAY_SECONDS}d"
+    if seconds % 3600 == 0:
+        return f"{seconds // 3600}h"
+    if seconds % 60 == 0:
+        return f"{seconds // 60}m"
+    return f"{seconds}s"
+
+
+class Dedupe(BaseCheck):
+    """One delivery per event per window, claimed atomically at commit time.
+
+    Transports deliver at least once, so the same event arrives twice, and two
+    workers can hold it at the same moment. Both then evaluate against a store
+    where nothing is recorded, so reading cannot separate them: the claim has to
+    be atomic and it has to happen at commit. See spec clauses 5.5 to 5.8.
+
+    The window is the caller's; the 24-hour default is the common retry horizon,
+    the same figure Stripe prunes an idempotency key after and Nylas gives as the
+    safe default for webhook deduplication.
+    """
+
+    id = "dedupe"
+
+    def __init__(self, window_seconds: int = DAY_SECONDS) -> None:
+        self.window_seconds = window_seconds
+        self.label = _human_window(window_seconds)
+
+    def _key(self, ctx: Context) -> str | None:
+        key = getattr(ctx.candidate, "dedupe_key", None)
+        return dedupe_key_for(ctx.user.id, key) if key else None
+
+    def keys(self, ctx: Context) -> Sequence[str]:
+        key = self._key(ctx)
+        return (key,) if key else ()
+
+    def run(self, ctx: Context, values: Values) -> Outcome:
+        key = self._key(ctx)
+        if key is None:
+            return skip("no dedupeKey on the candidate; deduplication cannot be evaluated")
+        return PASS if values.get(key) is None else reject(f"already delivered within the last {self.label}")
+
+    def consume_plan(self, ctx: Context) -> ConsumePlan | None:
+        key = self._key(ctx)
+        return None if key is None else ConsumePlan(key, self.window_seconds, 1)
+
+
 def default_checks(
     kill_switch: Callable[[], bool] | bool = False,
     modes: Sequence[str] = ("normal",),
@@ -555,8 +607,8 @@ def default_checks(
 
 __all__ = [
     "AdaptiveTiming", "AllowedWindow", "BaseCheck", "BoundedDeferral", "Budget", "Check", "Consent", "Consumer",
-    "DailyBudget", "DismissalCooldown", "Enabled", "Intensity", "KillSwitch", "Mode", "MonthlyBudget", "Mute",
+    "DailyBudget", "Dedupe", "DismissalCooldown", "Enabled", "Intensity", "KillSwitch", "Mode", "MonthlyBudget", "Mute",
     "OnlyWhen", "QuietHours", "RateLimit", "RecentInteraction", "RequiresConsent", "Snooze", "TrustRamp",
     "UtilityFloor", "WeeklyBudget", "WindowBudget", "budget_key", "default_checks", "dismissal_key",
-    "monthly_budget_key", "weekly_budget_key",
+    "dedupe_key_for", "monthly_budget_key", "weekly_budget_key",
 ]

{proactive_gate-0.2.2 → proactive_gate-0.2.4}/src/proactive_gate/gate.py

@@ -202,7 +202,9 @@ def _elapsed(started: float) -> float:
 
 
 def _consumers(checks: Iterable[Check]) -> list[Check]:
-    return [c for c in checks if isinstance(c, (Budget, OnlyWhen)) and hasattr(c, "consume_plan")]
+    """Any check that offers a commit-time plan. Duck-typed, as the TypeScript side is:
+    a new consumer must not have to be added to a class list to be honoured."""
+    return [c for c in checks if hasattr(c, "consume_plan")]
 
 
 def _plan(check: Check, ctx: Context) -> ConsumePlan | None:

{proactive_gate-0.2.2 → proactive_gate-0.2.4}/src/proactive_gate/policy.py

@@ -32,6 +32,7 @@ KNOWN_CHECKS: dict[str, Factory] = {
     "trustRamp": lambda o: c.TrustRamp(o.get("days", 7), o.get("minPriority", "high")),
     "dismissalCooldown": lambda o: c.DismissalCooldown(o.get("dismissals", 3), o.get("withinDays", 30), o.get("silenceDays", 7)),
     "adaptiveTiming": lambda o: c.AdaptiveTiming(),
+    "dedupe": lambda o: c.Dedupe(int(o.get("windowSeconds", 86400))),
     "dailyBudget": _budget(c.DailyBudget),
     "weeklyBudget": _budget(c.WeeklyBudget),
     "monthlyBudget": _budget(c.MonthlyBudget),

{proactive_gate-0.2.2 → proactive_gate-0.2.4}/src/proactive_gate/types.py

@@ -135,6 +135,7 @@ class Candidate:
     busy: bool | None = None
     p_accept: float | None = None
     p_need: float | None = None
+    dedupe_key: str | None = None
     payload: Any = None
 
     @staticmethod
@@ -148,6 +149,7 @@ class Candidate:
             busy=data.get("busy"),
             p_accept=data.get("pAccept"),
             p_need=data.get("pNeed"),
+            dedupe_key=data.get("dedupeKey"),
             payload=data.get("payload"),
         )