proactive-gate 0.2.1__tar.gz

proactive_gate-0.2.1/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+*.log
+.DS_Store
+python/.venv/
+python/dist/
+python/build/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/

proactive_gate-0.2.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,100 @@
+# 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/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "proactive-gate"
+version = "0.2.1"
+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"
+license = "MIT"
+authors = [{ name = "Efe Genc" }]
+keywords = ["proactive", "notifications", "agents", "rate-limit", "quiet-hours", "policy"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Framework :: AsyncIO",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Communications",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+redis = ["redis>=5"]
+dev = ["pytest>=8", "mypy>=1.11", "redis>=5"]
+
+[project.urls]
+Homepage = "https://bubblegunn.github.io/proactive-gate/"
+Repository = "https://github.com/Bubblegunn/proactive-gate"
+Issues = "https://github.com/Bubblegunn/proactive-gate/issues"
+Specification = "https://github.com/Bubblegunn/proactive-gate/tree/main/spec"
+Changelog = "https://github.com/Bubblegunn/proactive-gate/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/proactive_gate"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/proactive_gate", "tests", "README.md", "pyproject.toml"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src/proactive_gate", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

proactive_gate-0.2.1/src/proactive_gate/__init__.py

@@ -0,0 +1,31 @@
+"""proactive-gate: decide whether a proactive assistant may speak now.
+
+The Python sibling of the TypeScript package, held to the same behaviour
+contract in ``spec/`` and the same fixtures.
+"""
+from . import checks, presets
+from .checks import Check, default_checks
+from .gate import AsyncGate, Evaluation, Gate, Hooks, decide
+from .policy import KNOWN_CHECKS, CompiledPolicy, compile_policy, load_policy
+from .presets import Preset
+from .stores import AsyncMemoryStore, AsyncStore, MemoryStore, RedisStore, SqliteStore, Store
+from .types import (
+    PRIORITY_RANK,
+    Candidate,
+    Context,
+    Decision,
+    EvaluateInput,
+    Outcome,
+    Priority,
+    TraceEntry,
+    UserState,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "PRIORITY_RANK", "KNOWN_CHECKS", "AsyncGate", "AsyncMemoryStore", "AsyncStore", "Candidate", "Check",
+    "CompiledPolicy", "Context", "Decision", "EvaluateInput", "Evaluation", "Gate", "Hooks", "MemoryStore",
+    "Outcome", "Preset", "Priority", "RedisStore", "SqliteStore", "Store", "TraceEntry", "UserState",
+    "__version__", "checks", "compile_policy", "decide", "default_checks", "load_policy", "presets",
+]