proactive-gate 0.2.1__tar.gz → 0.2.3__tar.gz

{proactive_gate-0.2.1 → proactive_gate-0.2.3}/.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.1 → proactive_gate-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: proactive-gate
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -40,17 +40,19 @@ This is the Python sibling of the TypeScript package. Both implement the same be
 contract in [`spec/`](https://github.com/Bubblegunn/proactive-gate/tree/main/spec) and run
 the same fixtures, so a policy written for one behaves the same in the other.
 
-Until the first PyPI release, install from the repository:
-
 ```
-git clone https://github.com/Bubblegunn/proactive-gate
-pip install ./proactive-gate/python
+pip install proactive-gate
 ```
 
-or, without cloning, `pip install "proactive-gate @ git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`.
-Python 3.11 or newer, no runtime dependencies. Add `[redis]` (`pip install "./proactive-gate/python[redis]"`)
-for the Redis store. The PyPI name `proactive-gate` is reserved for this package; the
-release workflow publishes there on the next tag.
+Python 3.11 or newer, no runtime dependencies. Add `[redis]` (`pip install "proactive-gate[redis]"`)
+for the Redis store.
+
+To run an unreleased state, install from the repository instead:
+`pip install "proactive-gate @ git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`.
+
+The published 0.2.1 was uploaded from a local build with a token, so unlike the npm package it
+carries no build provenance. Trusted publishing is not configured yet; when it is, releases will
+come from the workflow.
 
 ## Use
 

{proactive_gate-0.2.1 → proactive_gate-0.2.3}/README.md

@@ -9,17 +9,19 @@ This is the Python sibling of the TypeScript package. Both implement the same be
 contract in [`spec/`](https://github.com/Bubblegunn/proactive-gate/tree/main/spec) and run
 the same fixtures, so a policy written for one behaves the same in the other.
 
-Until the first PyPI release, install from the repository:
-
 ```
-git clone https://github.com/Bubblegunn/proactive-gate
-pip install ./proactive-gate/python
+pip install proactive-gate
 ```
 
-or, without cloning, `pip install "proactive-gate @ git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`.
-Python 3.11 or newer, no runtime dependencies. Add `[redis]` (`pip install "./proactive-gate/python[redis]"`)
-for the Redis store. The PyPI name `proactive-gate` is reserved for this package; the
-release workflow publishes there on the next tag.
+Python 3.11 or newer, no runtime dependencies. Add `[redis]` (`pip install "proactive-gate[redis]"`)
+for the Redis store.
+
+To run an unreleased state, install from the repository instead:
+`pip install "proactive-gate @ git+https://github.com/Bubblegunn/proactive-gate#subdirectory=python"`.
+
+The published 0.2.1 was uploaded from a local build with a token, so unlike the npm package it
+carries no build provenance. Trusted publishing is not configured yet; when it is, releases will
+come from the workflow.
 
 ## Use
 

{proactive_gate-0.2.1 → proactive_gate-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "proactive-gate"
-version = "0.2.1"
+version = "0.2.3"
 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.1 → proactive_gate-0.2.3}/src/proactive_gate/checks.py

@@ -10,7 +10,7 @@ from collections.abc import Callable, Mapping, Sequence
 from datetime import datetime, timedelta
 from typing import Protocol, runtime_checkable
 
-from .clock import DAY_SECONDS, in_window, iso_week_key, local_clock, local_day, parse_hhmm
+from .clock import DAY_SECONDS, day_before, in_window, iso_week_key, local_clock, local_day, parse_hhmm, weekday_of
 from .types import (
     PASS,
     ConsumePlan,
@@ -18,6 +18,8 @@ from .types import (
     NearLimit,
     Outcome,
     Priority,
+    QuietSchedule,
+    QuietWindow,
     at_least,
     defer,
     epoch_ms,
@@ -150,6 +152,39 @@ class Intensity(BaseCheck):
         return reject(f'priority {ctx.priority} is below the "{level}" intensity floor ({floor})')
 
 
+def window_for(quiet: QuietWindow | QuietSchedule, day: str) -> QuietWindow | None:
+    """The window in force on one local date: a date beats a weekday beats the default."""
+    if isinstance(quiet, QuietWindow):
+        return quiet
+    if day in quiet.dates:
+        return quiet.dates[day]
+    weekday = weekday_of(day)
+    if weekday in quiet.days:
+        return quiet.days[weekday]
+    return quiet.default
+
+
+def quiet_at(quiet: QuietWindow | QuietSchedule, day: str, minutes: int) -> tuple[QuietWindow, str] | None:
+    """The window silencing ``minutes`` on ``day``, and the day it opened on.
+
+    A window that crosses midnight belongs to the day it opens on, so a time can be
+    quiet because of yesterday. With one window every day this reduces exactly to
+    ``in_window``, which is why the single-window form behaves as it did.
+    """
+    today = window_for(quiet, day)
+    if today is not None:
+        start, end = parse_hhmm(today.start), parse_hhmm(today.end)
+        if start != end and (start <= minutes < end if start < end else minutes >= start):
+            return today, day
+    previous = day_before(day)
+    yesterday = window_for(quiet, previous)
+    if yesterday is not None:
+        start, end = parse_hhmm(yesterday.start), parse_hhmm(yesterday.end)
+        if start > end and minutes < end:
+            return yesterday, previous
+    return None
+
+
 class QuietHours(BaseCheck):
     id = "quietHours"
 
@@ -162,12 +197,17 @@ class QuietHours(BaseCheck):
             return PASS
         if not ctx.user.timezone:
             return skip("quiet hours set but no timezone on the user; cannot evaluate")
-        minutes, _ = local_clock(ctx.now, ctx.user.timezone)
-        if not in_window(minutes, parse_hhmm(qh.start), parse_hhmm(qh.end)):
+        minutes, day = local_clock(ctx.now, ctx.user.timezone)
+        hit = quiet_at(qh, day, minutes)
+        if hit is None:
             return PASS
         if at_least(ctx.priority, self.floor):
             return PASS
-        return reject(f"quiet hours {qh.start} to {qh.end} {ctx.user.timezone}; priority {ctx.priority} is below the floor ({self.floor})")
+        window, from_day = hit
+        # Name the day the window opened on when it was not today: the reason is
+        # yesterday's setting, and a reader checking today's would not find it.
+        whose = "" if from_day == day else f" ({weekday_of(from_day)} {from_day})"
+        return reject(f"quiet hours {window.start} to {window.end}{whose} {ctx.user.timezone}; priority {ctx.priority} is below the floor ({self.floor})")
 
 
 class TrustRamp(BaseCheck):
@@ -486,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",),
@@ -515,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.1 → proactive_gate-0.2.3}/src/proactive_gate/clock.py

@@ -1,7 +1,7 @@
 """Local-time arithmetic with the standard library only."""
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import date, datetime, timedelta
 from zoneinfo import ZoneInfo
 
 DAY_SECONDS = 24 * 60 * 60
@@ -38,3 +38,19 @@ def local_day(now: datetime, tz: str | None) -> str:
 def iso_week_key(day: str) -> str:
     year, week, _ = datetime.strptime(day, "%Y-%m-%d").isocalendar()
     return f"{year}-W{week:02d}"
+
+
+WEEKDAYS = ("mon", "tue", "wed", "thu", "fri", "sat", "sun")
+
+
+def weekday_of(day: str) -> str:
+    """The weekday of a local calendar date, ``"mon"`` to ``"sun"``.
+
+    Calendar arithmetic on the date ``local_clock`` already resolved, never arithmetic
+    on an instant, so a 45-minute offset or a daylight-saving change cannot reach it.
+    """
+    return WEEKDAYS[date.fromisoformat(day).weekday()]
+
+
+def day_before(day: str) -> str:
+    return (date.fromisoformat(day) - timedelta(days=1)).isoformat()

{proactive_gate-0.2.1 → proactive_gate-0.2.3}/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.1 → proactive_gate-0.2.3}/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.1 → proactive_gate-0.2.3}/src/proactive_gate/types.py

@@ -45,11 +45,46 @@ def epoch_ms(value: datetime) -> int:
 
 
 @dataclass(frozen=True, slots=True)
-class QuietHours:
+class QuietWindow:
     start: str
     end: str
 
 
+@dataclass(frozen=True, slots=True)
+class QuietSchedule:
+    """Quiet hours resolved per day: a date beats a weekday beats the default.
+
+    ``None`` at any level means the day has no quiet hours, which is how a working
+    day is carved out of a default. There is no bundled holiday calendar; the dates
+    a caller observes are the caller's to supply.
+    """
+
+    default: QuietWindow | None = None
+    days: Mapping[str, QuietWindow | None] = field(default_factory=dict)
+    dates: Mapping[str, QuietWindow | None] = field(default_factory=dict)
+
+
+# The single-window form every caller had before schedules existed.
+QuietHours = QuietWindow
+
+
+def _window(value: Any) -> QuietWindow | None:
+    return QuietWindow(str(value["start"]), str(value["end"])) if value else None
+
+
+def parse_quiet_hours(value: Any) -> QuietWindow | QuietSchedule | None:
+    """A window, or a schedule; the two forms are told apart by the ``start`` key."""
+    if not value:
+        return None
+    if "start" in value:
+        return _window(value)
+    return QuietSchedule(
+        default=_window(value.get("default")),
+        days={k: _window(v) for k, v in (value.get("days") or {}).items()},
+        dates={k: _window(v) for k, v in (value.get("dates") or {}).items()},
+    )
+
+
 @dataclass(frozen=True, slots=True)
 class UserState:
     id: str
@@ -60,7 +95,7 @@ class UserState:
     muted_types: tuple[str, ...] = ()
     intensity: Intensity | None = None
     timezone: str | None = None
-    quiet_hours: QuietHours | None = None
+    quiet_hours: QuietWindow | QuietSchedule | None = None
     created_at: datetime | None = None
     surfaces: tuple[str, ...] | None = None
     consents: Mapping[str, bool] = field(default_factory=dict)
@@ -80,7 +115,7 @@ class UserState:
             muted_types=tuple(data.get("mutedTypes") or ()),
             intensity=data.get("intensity"),
             timezone=data.get("timezone"),
-            quiet_hours=QuietHours(str(qh["start"]), str(qh["end"])) if qh else None,
+            quiet_hours=parse_quiet_hours(qh),
             created_at=to_datetime(data.get("createdAt")),
             surfaces=tuple(data["surfaces"]) if data.get("surfaces") is not None else None,
             consents=dict(data.get("consents") or {}),
@@ -100,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
@@ -113,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"),
         )