perceptkit 0.2.2__py3-none-any.whl

perceptkit/rules/evaluators.py

@@ -0,0 +1,228 @@
+"""九种内置规则。
+
+每个 evaluator 只回答一件事：**这次观测，让这条规则命中了吗。**
+"今天已经触发过了要不要再触发""明天要不要重新武装"是生命周期的事，
+在 ``engine`` 里统一处理 —— 不然九个 evaluator 各写一遍，迟早不一致。
+
+九种：
+
+    changed             值变了
+    equals              值等于某个东西
+    enters / leaves     进入 / 离开某个状态
+    threshold_crossing  跨过一条线（**不是"大于某个数"**，见下）
+    delta               相邻两次的变化量超过某个幅度
+    occurrence          这条观测到达本身就是事件
+    streak              连续 N 个周期满足条件
+    absence             该来的没来
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, Protocol, runtime_checkable
+
+from .types import MAX_SEEN_KEYS, EventDefinition, RuleResult, RuleState
+
+
+@runtime_checkable
+class RuleEvaluator(Protocol):
+    """自定义 evaluator 的接口。
+
+    宿主可以注册代码型 evaluator 处理内置模板覆盖不了的逻辑。
+    **但普通用户配置只能用声明式模板** —— 用户配的规则跑在服务端，
+    允许任意代码就是一整类新的安全面。
+    """
+
+    kind: str
+
+    def evaluate(
+        self, definition: EventDefinition, state: RuleState,
+        current: Any, context: dict[str, Any],
+    ) -> RuleResult:
+        ...
+
+    # ⚠️ 和产品规范 §12.4 的签名草案有两处不同，都是有意的：
+    #
+    #   previous  在 ``state`` 里（``state.previous_value``），不单独传 ——
+    #             规则状态本来就是"上一次看到什么"的载体，拆成两个参数
+    #             会让实现者不知道该信哪一个。
+    #
+    #   history   **不传**。九种内置规则里只有 streak 需要历史，而它跑在
+    #             时钟驱动那条路上（一天判一次），历史由那边读好再通过
+    #             ``context`` 传进来。给每次求值都挂上历史，意味着前台
+    #             每 30 秒一条观测就要读一次历史表。
+    #
+    #             代价说清楚：**自定义 evaluator 拿不到历史**。需要历史的
+    #             自定义规则，宿主目前只能自己在时钟循环里算好，
+    #             通过 ``extra_context`` 递进来。
+
+
+def _numeric(value: Any) -> float | None:
+    if isinstance(value, bool) or value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    return None
+
+
+def _hit(state: RuleState, previous: Any, current: Any, reason: str) -> RuleResult:
+    return RuleResult(True, state, previous=previous, current=current, reason=reason)
+
+
+def _miss(state: RuleState, previous: Any, current: Any, reason: str) -> RuleResult:
+    return RuleResult(False, state, previous=previous, current=current, reason=reason)
+
+
+# ---------------------------------------------------------------------------
+
+def eval_changed(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    prev = s.previous_value
+    if prev is None and current is None:
+        return _miss(s, prev, current, "两次都没有值")
+    if prev == current:
+        return _miss(s, prev, current, "没变")
+    # 第一次见到某个值不算"变了" —— 否则用户刚装上 app，所有信号会一起触发。
+    if prev is None:
+        return _miss(s, prev, current, "第一次观测，不算变化")
+    return _hit(s, prev, current, f"{prev!r} -> {current!r}")
+
+
+def eval_equals(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    if current == d.value:
+        return _hit(s, s.previous_value, current, f"等于 {d.value!r}")
+    return _miss(s, s.previous_value, current, f"不等于 {d.value!r}")
+
+
+def eval_enters(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    """从"不是它"变成"是它"。**只在跨入那一刻触发**，之后一直是它也不再触发。"""
+    prev = s.previous_value
+    if current == d.value and prev != d.value:
+        return _hit(s, prev, current, f"进入 {d.value!r}")
+    return _miss(s, prev, current, "没有跨入")
+
+
+def eval_leaves(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    prev = s.previous_value
+    if prev == d.value and current != d.value:
+        return _hit(s, prev, current, f"离开 {d.value!r}")
+    return _miss(s, prev, current, "没有跨出")
+
+
+_OPS: dict[str, Callable[[float, float], bool]] = {
+    "gte": lambda a, b: a >= b,
+    "gt": lambda a, b: a > b,
+    "lte": lambda a, b: a <= b,
+    "lt": lambda a, b: a < b,
+}
+
+
+def eval_threshold_crossing(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    """**跨过**一条线，不是"在线的那一边"。
+
+    这是最容易写错的一条：``current >= 3000`` 会让 3001、3010、3100 的每次
+    上报都重复触发 —— 用户走一天路能被提醒几十次。正确的是
+    ``previous < 3000 and current >= 3000``。
+
+    第一次观测就已经在线的另一边时**不触发**：用户可能是中午才装上 app，
+    那时步数已经过万，不该立刻收到"你走够 3000 步了"。
+    """
+    op = _OPS.get(d.operator or "gte")
+    threshold = _numeric(d.value)
+    now = _numeric(current)
+    prev = _numeric(s.previous_value)
+    if op is None or threshold is None or now is None:
+        return _miss(s, s.previous_value, current, "阈值或当前值不是数字")
+    if prev is None:
+        return _miss(s, s.previous_value, current, "第一次观测，没有可比的前值")
+    if op(prev, threshold):
+        return _miss(s, s.previous_value, current, "之前就已经在线的另一边")
+    if op(now, threshold):
+        return _hit(s, s.previous_value, current,
+                    f"{prev:g} -> {now:g} 跨过 {threshold:g}")
+    return _miss(s, s.previous_value, current, "还没跨过")
+
+
+def eval_delta(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    """相邻两次的变化幅度超过某个值。用于"突然掉了很多"这类。"""
+    now, prev, limit = _numeric(current), _numeric(s.previous_value), _numeric(d.value)
+    if now is None or prev is None or limit is None:
+        return _miss(s, s.previous_value, current, "缺少可比的数字")
+    change = now - prev
+    magnitude = abs(change)
+    if magnitude >= abs(limit):
+        return _hit(s, s.previous_value, current, f"变化 {change:+g}，超过 {limit:g}")
+    return _miss(s, s.previous_value, current, f"变化 {change:+g}，未达 {limit:g}")
+
+
+def eval_occurrence(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    """观测到达本身就是事件。没有前后值可比，靠去重键挡住重复。
+
+    去重键取自 ``ctx``（通常是 ``source_event_id``）。**没有去重键时不触发** ——
+    宁可漏一次，也不要因为客户端重传而让用户被同一件事提醒两次。
+    """
+    key = ctx.get(d.dedupe_field)
+    if not key:
+        return _miss(s, None, current, f"没有 {d.dedupe_field}，无法去重，跳过")
+    if key in s.seen_keys:
+        return _miss(s, None, current, "这次事件之前处理过")
+    # 有上限：高频信号会让这条状态记录无限膨胀，而它每次求值都要被读出来。
+    seen = (s.seen_keys + (key,))[-MAX_SEEN_KEYS:]
+    return _hit(RuleState(
+        previous_value=s.previous_value, fired_in_scope=s.fired_in_scope,
+        last_fired_at=s.last_fired_at, seen_keys=seen,
+    ), None, current, f"发生了（{d.dedupe_field}={key}）")
+
+
+def eval_streak(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    """连续 N 个周期满足条件。
+
+    两个参数分开：``operator`` / ``value`` 是**每天的条件**（"睡眠 < 360 分钟"），
+    ``params["periods"]`` 是**连续几天**。挤在一个字段里表达不了。
+
+    连续长度由调用方通过 ``ctx["streak_length"]`` 给 —— 它要读历史，
+    而 evaluator 只看单次观测。
+
+    **由日聚合完成时驱动，不是每条观测都跑**：前台每 30 秒一条观测，
+    但"连续三天"这件事一天只可能变化一次。
+
+    **边缘触发**：只在恰好跨到 N 的那一次触发。第 N+1 天仍然连续，
+    但不再提醒 —— 否则"连续三天睡不好"会变成天天念叨。
+    """
+    need = int(_numeric(d.params.get("periods")) or _numeric(d.value) or 0)
+    length = int(_numeric(ctx.get("streak_length")) or 0)
+    prev_length = int(_numeric(s.previous_value) or 0)
+    if need <= 0:
+        return _miss(s, prev_length, length, "没有指定连续长度")
+    if length >= need > prev_length:
+        return _hit(s, prev_length, length, f"连续到达 {length} 个周期")
+    return _miss(s, prev_length, length, f"连续 {length}，需要 {need}")
+
+
+def eval_absence(d: EventDefinition, s: RuleState, current: Any, ctx) -> RuleResult:
+    """该来的没来。
+
+    多久算"没来"由 ``ctx["silent_seconds"]`` 给 —— 同样要读历史。
+    这条规则天然由**定时检查**驱动，而不是由上报驱动：没有上报的时候，
+    才是它该触发的时候。
+    """
+    limit = _numeric(d.value)
+    silent = _numeric(ctx.get("silent_seconds"))
+    if limit is None or silent is None:
+        return _miss(s, None, current, "缺少静默时长")
+    if silent >= limit and not s.fired_in_scope:
+        return _hit(s, None, current, f"已经 {silent:g}s 没有数据，超过 {limit:g}s")
+    return _miss(s, None, current, f"静默 {silent:g}s，未达 {limit:g}s")
+
+
+BUILTIN: dict[str, Callable[..., RuleResult]] = {
+    "changed": eval_changed,
+    "equals": eval_equals,
+    "enters": eval_enters,
+    "leaves": eval_leaves,
+    "threshold_crossing": eval_threshold_crossing,
+    "delta": eval_delta,
+    "occurrence": eval_occurrence,
+    "streak": eval_streak,
+    "absence": eval_absence,
+}
+
+
+__all__ = ["RuleEvaluator", "BUILTIN"] + [f"eval_{k}" for k in BUILTIN]

perceptkit/rules/types.py

@@ -0,0 +1,236 @@
+"""规则的形状 —— 定义、状态、求值结果。
+
+**定义和发生是两件事，必须分开。**
+
+    EventDefinition   用户或宿主说"什么条件算一件事"。会被改、被删、被停用。
+    PerceptionEvent   某条规则命中后产生的**不可变事实**。规则后来变了，
+                      已经发生的事实仍然解释得通 —— 所以事件里带条件快照，
+                      不带指向定义的活引用。
+
+**不做通用表达式 DSL。** 九种模板已经覆盖真实需求，而 DSL 意味着要解析、
+要防注入、要考虑求值超时 —— 用户配的规则跑在服务端，那是一整类新的安全面。
+需要更复杂逻辑的宿主可以注册代码型 evaluator，但那要求宿主自己信任那段代码。
+
+**规则用 dict/JSON 表达，不是 YAML。** 这个包零依赖（``dependencies = []``，
+有 AST 测试盯着），引 PyYAML 当场破坏"任何宿主都能直接嵌入"这句话。
+宿主想用 YAML 写规则完全可以 —— 自己 ``yaml.safe_load`` 成 dict 再传进来。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+from ..contracts.errors import ContractError
+
+#: 规则在什么范围内计一次。``local_day`` 每天重置，``forever`` 永不重置。
+SCOPES: frozenset[str] = frozenset({"local_day", "forever"})
+
+#: 一个范围内触发几次。
+FIRE_MODES: frozenset[str] = frozenset({"once", "every"})
+
+#: 什么时候重新武装。
+REARM_MODES: frozenset[str] = frozenset({"next_scope", "cooldown", "never"})
+
+
+@dataclass(frozen=True)
+class Lifecycle:
+    """一条规则的触发节奏。
+
+    默认是"每天一次、次日重新武装" —— 这是绝大多数感知规则想要的：
+    今天走够 3000 步提醒一次，明天重新算。
+    """
+
+    scope: str = "local_day"
+    fire: str = "once"
+    rearm: str = "next_scope"
+    cooldown_seconds: float = 0.0
+
+    def __post_init__(self) -> None:
+        problems = []
+        if self.scope not in SCOPES:
+            problems.append(f"scope={self.scope!r} 不在 {sorted(SCOPES)}")
+        if self.fire not in FIRE_MODES:
+            problems.append(f"fire={self.fire!r} 不在 {sorted(FIRE_MODES)}")
+        if self.rearm not in REARM_MODES:
+            problems.append(f"rearm={self.rearm!r} 不在 {sorted(REARM_MODES)}")
+        if self.cooldown_seconds < 0:
+            problems.append("cooldown_seconds 不能为负")
+        # 这两个组合以前"能配出来但不生效"——比配不出来更糟,因为用户以为配上了。
+        if self.rearm == "never" and self.scope != "forever":
+            problems.append(
+                "rearm=never 只能配 scope=forever："
+                "按天算范围的话，换一天就是一条新状态，本来就重新武装了"
+            )
+        if self.rearm == "cooldown" and self.cooldown_seconds <= 0:
+            problems.append("rearm=cooldown 必须给一个正的 cooldown_seconds")
+        if problems:
+            raise ContractError(problems)
+
+
+def default_lifecycle_for(condition_type: str) -> Lifecycle:
+    """没有显式写 lifecycle 时用什么默认值。
+
+    ``occurrence`` 型默认 ``fire="every"`` —— 它的"不重复"已经由去重键保证了,
+    再叠一层"每个范围只触发一次"是双重限制:"久别之后重新在场"一天可能发生
+    三次,不该只报第一次。产品规范的两个示例正好印证:步数那条显式写了
+    ``fire: once``,解锁那条整个 lifecycle 块都没写。
+
+    其余规则默认"每天一次、次日重新武装" —— 绝大多数感知规则想要的就是这个。
+    """
+    if condition_type == "occurrence":
+        return Lifecycle(fire="every")
+    return Lifecycle()
+
+
+@dataclass(frozen=True)
+class EventDefinition:
+    """用户或宿主定义的一条规则。"""
+
+    definition_id: str
+    version: int
+    signal: str
+    condition_type: str
+    event_type: str
+    enabled: bool = True
+    #: 盯哪个字段。``occurrence`` 型规则盯的是整条信号的到达，为 ``None``。
+    field_name: str | None = None
+    operator: str | None = None
+    value: Any = None
+    #: 没写时按 condition_type 取默认值,见 default_lifecycle_for。
+    lifecycle: Lifecycle | None = None
+    wake_enabled: bool = True
+    #: 只属于某个用户的规则；``None`` = 宿主级，对所有用户生效。
+    subject_id: str | None = None
+    #: ``occurrence`` 型用什么去重。默认用 ``source_event_id``。
+    dedupe_field: str = "source_event_id"
+    #: 某些规则型需要的额外参数。放一个口袋，而不是给每种规则各开一个字段。
+    #: ``streak`` 用 ``{"periods": 3}``（连续几个周期）—— 它的 ``operator`` /
+    #: ``value`` 已经被"每天的条件"占用了（比如"睡眠 < 360 分钟"）。
+    params: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.lifecycle is None:
+            object.__setattr__(
+                self, "lifecycle", default_lifecycle_for(self.condition_type)
+            )
+
+    @classmethod
+    def parse(cls, payload: Mapping[str, Any]) -> "EventDefinition":
+        """从 dict 解析。宿主想用 YAML 就自己 ``safe_load`` 成 dict 再进来。"""
+        if not isinstance(payload, Mapping):
+            raise ContractError(["definition 必须是一个对象"])
+        problems: list[str] = []
+
+        def need(key: str, types: tuple[type, ...], label: str) -> Any:
+            raw = payload.get(key)
+            if not isinstance(raw, types) or (isinstance(raw, str) and not raw.strip()):
+                problems.append(f"{key}: 必填，{label}")
+                return None
+            return raw
+
+        definition_id = need("id", (str,), "非空字符串")
+        version = need("version", (int,), "整数")
+        source = payload.get("source") or {}
+        condition = payload.get("condition") or {}
+        event = payload.get("event") or {}
+        wake = payload.get("wake") or {}
+
+        signal = source.get("signal") if isinstance(source, Mapping) else None
+        if not isinstance(signal, str) or not signal.strip():
+            problems.append("source.signal: 必填")
+
+        condition_type = condition.get("type") if isinstance(condition, Mapping) else None
+        if not isinstance(condition_type, str) or not condition_type.strip():
+            problems.append("condition.type: 必填")
+
+        event_type = event.get("type") if isinstance(event, Mapping) else None
+        if not isinstance(event_type, str) or not event_type.strip():
+            problems.append("event.type: 必填")
+
+        if problems:
+            raise ContractError(problems)
+
+        raw_lifecycle = payload.get("lifecycle")
+        if raw_lifecycle is None:
+            lifecycle = default_lifecycle_for(condition_type)   # type: ignore[arg-type]
+        else:
+            fallback = default_lifecycle_for(condition_type)    # type: ignore[arg-type]
+            lifecycle = Lifecycle(
+                scope=raw_lifecycle.get("scope", fallback.scope),
+                fire=raw_lifecycle.get("fire", fallback.fire),
+                rearm=raw_lifecycle.get("rearm", fallback.rearm),
+                cooldown_seconds=float(raw_lifecycle.get("cooldown_seconds", 0) or 0),
+            )
+        return cls(
+            definition_id=definition_id,          # type: ignore[arg-type]
+            version=version,                      # type: ignore[arg-type]
+            signal=signal,                        # type: ignore[arg-type]
+            condition_type=condition_type,        # type: ignore[arg-type]
+            event_type=event_type,                # type: ignore[arg-type]
+            enabled=bool(payload.get("enabled", True)),
+            field_name=source.get("field"),
+            operator=condition.get("operator"),
+            value=condition.get("value"),
+            lifecycle=lifecycle,
+            wake_enabled=bool(wake.get("enabled", True)),
+            subject_id=payload.get("subject_id"),
+            dedupe_field=(payload.get("deduplication") or {}).get("key", "source_event_id"),
+            params=dict(condition.get("params") or {}),
+        )
+
+
+@dataclass(frozen=True)
+class RuleState:
+    """一条规则在某个范围内的状态。
+
+    ``scope_key`` 是"哪一天"（或 ``forever``）。换了一天就是一条新状态，
+    所以"今天已经触发过"不会影响明天 —— 这就是 ``rearm=next_scope``。
+    """
+
+    previous_value: Any = None
+    fired_in_scope: bool = False
+    last_fired_at: str | None = None
+    #: ``occurrence`` 型见过哪些去重键。有上限，见 ``MAX_SEEN_KEYS``。
+    seen_keys: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "previous_value": self.previous_value,
+            "fired_in_scope": self.fired_in_scope,
+            "last_fired_at": self.last_fired_at,
+            "seen_keys": list(self.seen_keys),
+        }
+
+    @classmethod
+    def from_dict(cls, raw: Mapping[str, Any] | None) -> "RuleState":
+        raw = raw or {}
+        return cls(
+            previous_value=raw.get("previous_value"),
+            fired_in_scope=bool(raw.get("fired_in_scope")),
+            last_fired_at=raw.get("last_fired_at"),
+            seen_keys=tuple(raw.get("seen_keys") or ()),
+        )
+
+
+#: ``occurrence`` 型记住多少个去重键。不设上限的话，一个高频信号会让这条
+#: 状态记录无限膨胀 —— 而它每次求值都要被读出来。
+MAX_SEEN_KEYS = 200
+
+
+@dataclass(frozen=True)
+class RuleResult:
+    """一次求值的结果。"""
+
+    fired: bool
+    state: RuleState
+    previous: Any = None
+    current: Any = None
+    #: 为什么触发（或为什么没触发）。进事件信封，也进排查日志。
+    reason: str | None = None
+
+
+__all__ = [
+    "SCOPES", "FIRE_MODES", "REARM_MODES", "MAX_SEEN_KEYS",
+    "Lifecycle", "default_lifecycle_for",
+    "EventDefinition", "RuleState", "RuleResult",
+]