proactive-gate 0.2.1__py3-none-any.whl

proactive_gate/presets.py

@@ -0,0 +1,128 @@
+"""Platform quotas and legal limits as ordered check lists, one to one with the
+TypeScript presets. Reviewable defaults, not legal advice; every number sits
+next to its source."""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from . import checks as c
+from .checks import Check
+from .types import Context, Outcome
+
+Options = Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class Preset:
+    build: Callable[[Options], list[Check]]
+    sources: tuple[str, ...]
+    note: str
+
+    def __call__(self, options: Options | None = None) -> list[Check]:
+        return self.build(options or {})
+
+
+LINE_PLANS: dict[str, int] = {"communication": 200, "light": 5000, "standard": 30000}
+
+
+def _line(o: Options) -> list[Check]:
+    plan = o.get("plan", "communication")
+    if plan not in LINE_PLANS:
+        raise ValueError(f'lineMessagingApi: unknown plan "{plan}", known: {", ".join(LINE_PLANS)}')
+    return [c.Consent(), c.MonthlyBudget(limit=LINE_PLANS[plan], near_limit=0.9)]
+
+
+def _cn_minor_mode(o: Options) -> list[Check]:
+    is_minor = lambda ctx: bool(ctx.user.minor)  # noqa: E731
+    window = c.AllowedWindow("06:00", "22:00", "Asia/Shanghai", id="window:minor")
+    return [c.OnlyWhen(window, is_minor, "not a minor"), c.OnlyWhen(c.DailyBudget(limit=1), is_minor, "not a minor")]
+
+
+class _SoftOptIn(c.BaseCheck):
+    id = "consent:marketing"
+
+    def __init__(self) -> None:
+        self.inner = c.RequiresConsent("marketing")
+
+    def run(self, ctx: Context, values: Mapping[str, str | None]) -> Outcome:
+        if ctx.user.existing_customer:
+            return Outcome("pass", "existing customer, soft opt-in")
+        return self.inner.run(ctx, values)
+
+
+presets: dict[str, Preset] = {
+    "lineMessagingApi": Preset(
+        _line,
+        ("https://developers.line.biz/en/docs/messaging-api/pricing/", "https://developers.line.biz/en/reference/messaging-api/"),
+        "Monthly push messages per plan for Japan: communication 200, light 5,000, standard 30,000; replies are free and not counted. Multicast and broadcast request rates are not encoded.",
+    ),
+    "wechatSubscriptionMessage": Preset(
+        lambda o: [c.RequiresConsent("subscription"), c.WindowBudget(limit=1, within_hours=24 * 365)],
+        ("https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/subscribe-message-overview.html",),
+        "One-time subscription: exactly one message per opt-in; set user.lastInboundAt to the opt-in instant. Long-term subscriptions for government, medical, transport, finance and education categories are not encoded.",
+    ),
+    "wechatCustomerService": Preset(
+        lambda o: [c.RecentInteraction(within_hours=48), c.WindowBudget(limit=5, within_hours=48)],
+        ("https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/customer-message/send.html",),
+        "Mini program customer-service messages: within 48 hours of the user's last message, at most 5 in that window.",
+    ),
+    "wechatTemplateMessage": Preset(
+        lambda o: [c.RequiresConsent("templateTrigger"), c.RateLimit(limit=3, per_seconds=24 * 3600, key_by="user", id="rate:template")],
+        ("https://developers.weixin.qq.com/doc/service/guide/product/template_message/Template_Message_Operation_Specifications.html",),
+        "Template messages only after a user action (consents.templateTrigger) and no more than three repeated templates a day; marketing templates are not allowed at all.",
+    ),
+    "wecomAppMessage": Preset(
+        lambda o: [c.RateLimit(limit=30, per_seconds=60, id="rate:30/min"), c.RateLimit(limit=1000, per_seconds=3600, id="rate:1000/h")],
+        ("https://developer.work.weixin.qq.com/document/path/96212",),
+        "WeCom application messages per app per member: 30 a minute and 1,000 an hour; the platform drops the excess silently, this preset refuses it with a reason.",
+    ),
+    "kakaoAlimtalk": Preset(
+        lambda o: [c.Consent()],
+        ("https://kakaobusiness.gitbook.io/main/ad/infotalk",),
+        "AlimTalk is informational and carries no time-of-day limit; consent is the only gate.",
+    ),
+    "kakaoBrandMessage": Preset(
+        lambda o: [c.RequiresConsent("ad"), c.AllowedWindow("08:00", "20:50", "Asia/Seoul", id="window:kakao")],
+        ("https://kakaobusiness.gitbook.io/main/ad/moment/messagead/channelmessage/new/send",),
+        "Brand messages need advertising consent and go out 08:00 to 20:50 Korea time regardless of the recipient's location. Official sources also quote 20:00 and 20:55; 20:50 is the stricter documented value.",
+    ),
+    "krNetworkAct50": Preset(
+        lambda o: [c.RequiresConsent("ad"), c.RequiresConsent("night", when={"start": "21:00", "end": "08:00", "timezone": "user"})],
+        ("https://www.law.go.kr", "https://developers.fingerpush.com/biz-message/console/ads-guide"),
+        "Network Act article 50: prior consent for advertising, and a separate consent for 21:00 to 08:00 (email is exempt). The two-year re-confirmation is not encoded.",
+    ),
+    "jpAntiSpamLaw": Preset(
+        lambda o: [c.RequiresConsent("optIn")],
+        ("https://www.soumu.go.jp/main_sosiki/cybersecurity/kokumin/basic/legal/08/",),
+        "Opt-in since 2008 with sender identity and an opt-out route. There is no time-of-day rule in the law; a Japanese quiet-hours window would be etiquette, so none is encoded.",
+    ),
+    "cnMinorMode": Preset(
+        _cn_minor_mode,
+        ("https://www.cac.gov.cn/2024-11/15/c_1733364304749288.htm", "https://www.cac.gov.cn/2022-01/04/c_1642894606364259.htm"),
+        "Minor mode: no service 22:00 to 06:00 China time and a daily budget of one when user.minor is true; adults pass both checks. Per-age daily durations are not encoded.",
+    ),
+    "usTcpa": Preset(
+        lambda o: [c.AllowedWindow("08:00", "21:00", "user", id="window:tcpa")],
+        ("https://www.law.cornell.edu/cfr/text/47/64.1200",),
+        "47 CFR 64.1200: no solicitation before 8 a.m. or after 9 p.m. at the called party's local time.",
+    ),
+    "euEprivacy": Preset(
+        lambda o: [_SoftOptIn()],
+        ("https://eur-lex.europa.eu/legal-content/EN/TXT/HTML/?uri=CELEX:32002L0058",),
+        "Directive 2002/58/EC article 13: prior consent for direct marketing, with the soft opt-in for existing customers (user.existingCustomer).",
+    ),
+    "telegramBot": Preset(
+        lambda o: [c.RateLimit(limit=1, per_seconds=1, key_by="channel", id="rate:1/s"), c.RateLimit(limit=20, per_seconds=60, key_by="channel", id="rate:20/min")],
+        ("https://core.telegram.org/bots/faq",),
+        "One message a second per chat and twenty a minute per group, keyed by candidate.channel. The broadcast rate of roughly thirty a second is not encoded.",
+    ),
+    "slackApp": Preset(
+        lambda o: [c.RateLimit(limit=1, per_seconds=1, key_by="channel", id="rate:1/s")],
+        ("https://docs.slack.dev/apis/web-api/rate-limits/",),
+        "chat.postMessage: one message a second per channel, keyed by candidate.channel.",
+    ),
+}
+
+__all__ = ["LINE_PLANS", "Preset", "presets"]

proactive_gate/stores.py

@@ -0,0 +1,168 @@
+"""Key-value stores. Sync ``Store`` for ``Gate``; ``AsyncStore`` for ``AsyncGate``.
+Every method may raise; the gate decides whether that fails open or closed."""
+from __future__ import annotations
+
+import sqlite3
+import threading
+import time
+from typing import Any, Protocol
+
+
+class Store(Protocol):
+    def get(self, key: str) -> str | None: ...
+
+    def set(self, key: str, value: str, ttl_seconds: int | None = None) -> None: ...
+
+    def incr(self, key: str, ttl_seconds: int | None = None) -> int: ...
+
+    def delete(self, key: str) -> None: ...
+
+
+class AsyncStore(Protocol):
+    async def get(self, key: str) -> str | None: ...
+
+    async def set(self, key: str, value: str, ttl_seconds: int | None = None) -> None: ...
+
+    async def incr(self, key: str, ttl_seconds: int | None = None) -> int: ...
+
+    async def delete(self, key: str) -> None: ...
+
+
+class MemoryStore:
+    """In-process store with TTLs. Good for tests and single-process deployments."""
+
+    def __init__(self) -> None:
+        self._data: dict[str, tuple[str, float | None]] = {}
+        self._lock = threading.Lock()
+
+    def _live(self, key: str) -> str | None:
+        entry = self._data.get(key)
+        if entry is None:
+            return None
+        value, expires = entry
+        if expires is not None and time.time() >= expires:
+            del self._data[key]
+            return None
+        return value
+
+    def get(self, key: str) -> str | None:
+        with self._lock:
+            return self._live(key)
+
+    def set(self, key: str, value: str, ttl_seconds: int | None = None) -> None:
+        with self._lock:
+            self._data[key] = (value, time.time() + ttl_seconds if ttl_seconds else None)
+
+    def incr(self, key: str, ttl_seconds: int | None = None) -> int:
+        with self._lock:
+            current = self._live(key)
+            next_value = int(current or 0) + 1
+            expires = self._data[key][1] if current is not None else (time.time() + ttl_seconds if ttl_seconds else None)
+            self._data[key] = (str(next_value), expires)
+            return next_value
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._data.pop(key, None)
+
+
+class SqliteStore:
+    """Standard-library sqlite3 store; one file shared by every process on the host."""
+
+    def __init__(self, path: str = ":memory:") -> None:
+        self._conn = sqlite3.connect(path, isolation_level=None, check_same_thread=False)
+        self._conn.execute("CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at REAL)")
+        self._lock = threading.Lock()
+
+    def _row(self, key: str) -> str | None:
+        row = self._conn.execute("SELECT value, expires_at FROM kv WHERE key = ?", (key,)).fetchone()
+        if row is None:
+            return None
+        value, expires = row
+        if expires is not None and time.time() >= expires:
+            self._conn.execute("DELETE FROM kv WHERE key = ?", (key,))
+            return None
+        return str(value)
+
+    def get(self, key: str) -> str | None:
+        with self._lock:
+            return self._row(key)
+
+    def set(self, key: str, value: str, ttl_seconds: int | None = None) -> None:
+        expires = time.time() + ttl_seconds if ttl_seconds else None
+        with self._lock:
+            self._conn.execute("INSERT OR REPLACE INTO kv (key, value, expires_at) VALUES (?, ?, ?)", (key, value, expires))
+
+    def incr(self, key: str, ttl_seconds: int | None = None) -> int:
+        with self._lock:
+            self._conn.execute("BEGIN IMMEDIATE")
+            try:
+                current = self._row(key)
+                next_value = int(current or 0) + 1
+                if current is None:
+                    expires = time.time() + ttl_seconds if ttl_seconds else None
+                    self._conn.execute("INSERT OR REPLACE INTO kv (key, value, expires_at) VALUES (?, ?, ?)", (key, str(next_value), expires))
+                else:
+                    self._conn.execute("UPDATE kv SET value = ? WHERE key = ?", (str(next_value), key))
+                self._conn.execute("COMMIT")
+            except BaseException:
+                self._conn.execute("ROLLBACK")
+                raise
+            return next_value
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._conn.execute("DELETE FROM kv WHERE key = ?", (key,))
+
+    def close(self) -> None:
+        self._conn.close()
+
+
+class AsyncMemoryStore:
+    """``MemoryStore`` behind the async protocol, for ``AsyncGate`` tests."""
+
+    def __init__(self, inner: MemoryStore | None = None) -> None:
+        self.inner = inner or MemoryStore()
+
+    async def get(self, key: str) -> str | None:
+        return self.inner.get(key)
+
+    async def set(self, key: str, value: str, ttl_seconds: int | None = None) -> None:
+        self.inner.set(key, value, ttl_seconds)
+
+    async def incr(self, key: str, ttl_seconds: int | None = None) -> int:
+        return self.inner.incr(key, ttl_seconds)
+
+    async def delete(self, key: str) -> None:
+        self.inner.delete(key)
+
+
+class RedisStore:
+    """Wraps a ``redis.asyncio`` client. INCR, then EXPIRE on the first increment so a key never lives forever."""
+
+    def __init__(self, client: Any) -> None:
+        self.client = client
+
+    async def get(self, key: str) -> str | None:
+        value = await self.client.get(key)
+        if value is None:
+            return None
+        return value.decode() if isinstance(value, bytes) else str(value)
+
+    async def set(self, key: str, value: str, ttl_seconds: int | None = None) -> None:
+        if ttl_seconds:
+            await self.client.set(key, value, ex=ttl_seconds)
+        else:
+            await self.client.set(key, value)
+
+    async def incr(self, key: str, ttl_seconds: int | None = None) -> int:
+        value = int(await self.client.incr(key))
+        if value == 1 and ttl_seconds:
+            await self.client.expire(key, ttl_seconds)
+        return value
+
+    async def delete(self, key: str) -> None:
+        await self.client.delete(key)
+
+
+__all__ = ["AsyncMemoryStore", "AsyncStore", "MemoryStore", "RedisStore", "SqliteStore", "Store"]

proactive_gate/types.py

@@ -0,0 +1,221 @@
+"""Frozen data the gate reads and writes. Field names are snake_case; the JSON
+fixtures and policies use the camelCase of the TypeScript package, and
+``from_dict`` maps between them."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Literal, Mapping, Sequence
+
+Priority = Literal["low", "normal", "high", "critical"]
+PRIORITY_RANK: dict[str, int] = {"low": 0, "normal": 1, "high": 2, "critical": 3}
+Intensity = Literal["low", "normal", "high"]
+OutcomeKind = Literal["pass", "reject", "adjust", "skip", "defer"]
+OutcomeEvent = Literal["delivered", "dismissed", "acted", "ignored"]
+StoreErrorMode = Literal["open", "closed"]
+
+UTC = timezone.utc
+
+
+def to_datetime(value: object) -> datetime | None:
+    """A datetime, an ISO-8601 string (``Z`` accepted) or epoch milliseconds; anything else is None."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=UTC)
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return datetime.fromtimestamp(value / 1000, tz=UTC)
+    if isinstance(value, str):
+        try:
+            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            return None
+        return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+    return None
+
+
+def iso_z(value: datetime) -> str:
+    """The JavaScript ``toISOString`` form: UTC, milliseconds, trailing Z."""
+    utc = value.astimezone(UTC)
+    return f"{utc.strftime('%Y-%m-%dT%H:%M:%S')}.{utc.microsecond // 1000:03d}Z"
+
+
+def epoch_ms(value: datetime) -> int:
+    return int(round(value.timestamp() * 1000))
+
+
+@dataclass(frozen=True, slots=True)
+class QuietHours:
+    start: str
+    end: str
+
+
+@dataclass(frozen=True, slots=True)
+class UserState:
+    id: str
+    consent: bool
+    proactive_enabled: bool | None = None
+    mode: str | None = None
+    snoozed_until: datetime | None = None
+    muted_types: tuple[str, ...] = ()
+    intensity: Intensity | None = None
+    timezone: str | None = None
+    quiet_hours: QuietHours | None = None
+    created_at: datetime | None = None
+    surfaces: tuple[str, ...] | None = None
+    consents: Mapping[str, bool] = field(default_factory=dict)
+    last_inbound_at: datetime | None = None
+    minor: bool | None = None
+    existing_customer: bool | None = None
+
+    @staticmethod
+    def from_dict(data: Mapping[str, Any]) -> "UserState":
+        qh = data.get("quietHours")
+        return UserState(
+            id=str(data["id"]),
+            consent=bool(data.get("consent", False)),
+            proactive_enabled=data.get("proactiveEnabled"),
+            mode=data.get("mode"),
+            snoozed_until=to_datetime(data.get("snoozedUntil")),
+            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,
+            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 {}),
+            last_inbound_at=to_datetime(data.get("lastInboundAt")),
+            minor=data.get("minor"),
+            existing_customer=data.get("existingCustomer"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Candidate:
+    id: str
+    type: str
+    priority: Priority = "normal"
+    surfaces: tuple[str, ...] = ("feed",)
+    channel: str | None = None
+    busy: bool | None = None
+    p_accept: float | None = None
+    p_need: float | None = None
+    payload: Any = None
+
+    @staticmethod
+    def from_dict(data: Mapping[str, Any]) -> "Candidate":
+        return Candidate(
+            id=str(data["id"]),
+            type=str(data["type"]),
+            priority=data.get("priority") or "normal",
+            surfaces=tuple(data.get("surfaces") or ("feed",)),
+            channel=data.get("channel"),
+            busy=data.get("busy"),
+            p_accept=data.get("pAccept"),
+            p_need=data.get("pNeed"),
+            payload=data.get("payload"),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class NearLimit:
+    used: int
+    limit: int
+
+
+@dataclass(frozen=True, slots=True)
+class Outcome:
+    """What a single check says. ``kind`` decides which other fields matter."""
+
+    kind: OutcomeKind
+    reason: str | None = None
+    retry_at: datetime | None = None
+    deliver_at: datetime | None = None
+    surfaces: tuple[str, ...] | None = None
+    near_limit: NearLimit | None = None
+
+
+PASS = Outcome("pass")
+
+
+def reject(reason: str) -> Outcome:
+    return Outcome("reject", reason)
+
+
+def skip(reason: str) -> Outcome:
+    return Outcome("skip", reason)
+
+
+def defer(reason: str, retry_at: datetime) -> Outcome:
+    return Outcome("defer", reason, retry_at=retry_at)
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    user: UserState
+    candidate: Candidate
+    now: datetime
+    priority: Priority
+    surfaces: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TraceEntry:
+    id: str
+    outcome: OutcomeKind
+    ms: float
+    reason: str | None = None
+    shadow: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class NearLimitNote:
+    check: str
+    used: int
+    limit: int
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    id: str
+    allowed: bool
+    user_id: str
+    candidate_id: str
+    surfaces: tuple[str, ...]
+    trace: tuple[TraceEntry, ...]
+    evaluated_at: datetime
+    shadowed: tuple[str, ...] = ()
+    near_limit: tuple[NearLimitNote, ...] = ()
+    deliver_at: datetime | None = None
+    rejected_by: str | None = None
+    deferred_by: str | None = None
+    retry_at: datetime | None = None
+    reason: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluateInput:
+    user: UserState
+    candidate: Candidate
+    now: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ConsumePlan:
+    """A budget-like check's commit-time increment: the key, its TTL and the limit the new value must not exceed."""
+
+    key: str
+    ttl_seconds: int
+    limit: int
+
+
+def at_least(priority: str, floor: str) -> bool:
+    return PRIORITY_RANK[priority] >= PRIORITY_RANK[floor]
+
+
+def surfaces_for(user: UserState, candidate: Candidate) -> tuple[str, ...]:
+    wanted: Sequence[str] = candidate.surfaces or ("feed",)
+    if user.surfaces is None:
+        return tuple(wanted)
+    allowed = set(user.surfaces)
+    return tuple(s for s in wanted if s in allowed)

proactive_gate-0.2.1.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.5
+Name: proactive-gate
+Version: 0.2.1
+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
+Project-URL: Issues, https://github.com/Bubblegunn/proactive-gate/issues
+Project-URL: Specification, https://github.com/Bubblegunn/proactive-gate/tree/main/spec
+Project-URL: Changelog, https://github.com/Bubblegunn/proactive-gate/blob/main/CHANGELOG.md
+Author: Efe Genc
+License-Expression: MIT
+Keywords: agents,notifications,policy,proactive,quiet-hours,rate-limit
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: redis>=5; extra == 'dev'
+Provides-Extra: redis
+Requires-Dist: redis>=5; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# proactive-gate for Python
+
+Decide whether a proactive assistant may speak to this person right now. Ordered checks
+(consent, mode, snooze, mute, intensity, quiet hours, trust ramp, dismissal cooldown,
+budgets), JSON policies, platform and regulatory presets, and a trace that says which check
+stopped the message and why.
+
+This is the Python sibling of the TypeScript package. Both implement the same behaviour
+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
+```
+
+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.
+
+## Use
+
+```python
+from datetime import datetime, timezone
+from proactive_gate import Candidate, EvaluateInput, Gate, UserState, default_checks
+
+gate = Gate(default_checks(daily_limit=3))
+user = UserState.from_dict({
+    "id": "u1", "consent": True, "timezone": "Europe/Istanbul",
+    "quietHours": {"start": "22:00", "end": "08:00"}, "createdAt": "2026-01-01T00:00:00Z",
+})
+candidate = Candidate(id="c1", type="reminder", priority="normal", surfaces=("push", "feed"))
+inp = EvaluateInput(user, candidate, datetime.now(timezone.utc))
+
+decision = gate.evaluate(inp)
+if decision.allowed and gate.commit(decision, inp):
+    send(candidate, decision.surfaces)
+else:
+    print(decision.rejected_by, decision.reason)
+```
+
+`evaluate` reads; `commit` is the atomic increment right before you send, and it is
+idempotent on `decision.id`. Every decision carries `trace`, one entry per check that ran.
+
+## A policy is data
+
+```python
+import json
+from proactive_gate import Gate
+
+gate = Gate.from_policy(json.load(open("policy.json")))
+```
+
+`policy.json` is the same document the TypeScript package and the CLI read
+(`{"specVersion": "1.0.0", "checks": [{"id": "consent"}, {"preset": "usTcpa"}, ...]}`).
+Unknown check ids and presets raise `ValueError` naming the known ones; `shadow: true`
+keeps a check observing without letting it decide.
+
+## Async
+
+```python
+from proactive_gate import AsyncGate, RedisStore
+import redis.asyncio as redis
+
+gate = AsyncGate.from_policy(policy, RedisStore(redis.from_url("redis://localhost")))
+decision = await gate.evaluate(inp)
+```
+
+`Gate` and `AsyncGate` share one decision loop (`Evaluation`): a check names the store keys
+it needs and decides purely from their values, so the two gates cannot drift. `decide()`
+runs that loop with values you supply, for tests with no store at all.
+
+## Stores
+
+`MemoryStore` (in-process), `SqliteStore` (standard library, one file per host),
+`AsyncMemoryStore`, and `RedisStore` over `redis.asyncio` (INCR, then EXPIRE on the first
+increment). Any object with `get`, `set`, `incr` and `delete` works.
+
+## Presets
+
+`proactive_gate.presets` holds the same fourteen presets as the TypeScript package, each with
+its source URLs and a note on what it leaves out: LINE, WeChat, WeCom, Kakao, Korea's Network
+Act, Japan's anti-spam law, China's minor mode, US TCPA, EU ePrivacy, Telegram and Slack.
+They are reviewable defaults, not legal advice.
+
+## Conformance
+
+```
+pytest
+```
+
+runs every fixture under `../spec/fixtures` through both gates. A fixture the Python package
+cannot yet satisfy is listed in `spec/skip/python.txt` with a reason; the list is empty.
+
+## License
+
+MIT.

proactive_gate-0.2.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+proactive_gate/__init__.py,sha256=eXdIfKGIUHR0JvfkzdZwhUAfAkrXE5Q8wCLlB1uAHTE,1143
+proactive_gate/checks.py,sha256=ZP19Qs5ggtCBc8FfeajyCgBRKWqrme_Zf5oFOwYTHKw,18385
+proactive_gate/clock.py,sha256=4PlvwoQ-hAY_O6Q-fW8D2153pT18CLbPdWZNWj4v3UY,1280
+proactive_gate/conformance.py,sha256=SFIh1ijv0wiS5rNEbebaVCPqX_pkQOCNEzHEGn6vY6w,6051
+proactive_gate/gate.py,sha256=N0QfoV5zeGfYCmG6IvmclC8xyovZVOFUtZqbUnnUoJ0,15842
+proactive_gate/policy.py,sha256=c54i53_zcXSo3G9Thy8YKPQz2bxu-fp_uv3LCGnQwR8,4477
+proactive_gate/presets.py,sha256=5mm16_y61ydYpjMspUsvh8Tr-x59rnGJMyY0YgFXs8I,7121
+proactive_gate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+proactive_gate/stores.py,sha256=KmVSxdVi4tiCFPRyZGtvnIY_gJVpNZtSMYtqjKykKPQ,6150
+proactive_gate/types.py,sha256=pgwv7ZSQyrnKu-UdLvEQ_YBUg5nBUMcMzY2shC7FO_c,6615
+proactive_gate-0.2.1.dist-info/METADATA,sha256=XCvHsd27rnZfunJWZxDf4MIfPnX1oW2y5FXSduxp2Go,5191
+proactive_gate-0.2.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+proactive_gate-0.2.1.dist-info/RECORD,,

proactive_gate-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any