perceptkit 0.2.2__py3-none-any.whl

perceptkit/contracts/event.py

@@ -0,0 +1,137 @@
+"""感知事件 —— kit 交给宿主的**唯一**产物。
+
+规则可以随便加、随便改,但这个信封必须稳。宿主接的是信封,不是规则 ——
+信封稳定,用户新配十条规则,宿主一行代码都不用动。
+
+事件只表达四件事:
+
+    发生了什么          type / signal / field
+    哪条规则命中        definition_id + definition_version
+    新旧事实是什么      previous / current
+    为什么符合条件      condition
+
+事件**不**表达:agent 该说什么、要不要给用户发通知、用哪个模型、
+走宿主的哪条 runtime。那些是宿主的决定 —— **戳醒不等于该开口**。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Mapping
+
+from . import versioning
+from ._time import to_iso
+
+
+@dataclass(frozen=True)
+class EventCondition:
+    """命中时的判据快照 —— 让宿主(和事后排查的人)看得懂为什么触发。
+
+    存快照而不是存规则的引用:规则会被改、被删,而事件是**已经发生的事实**,
+    不该因为规则后来变了就解释不通。
+    """
+
+    type: str
+    operator: str | None = None
+    value: Any = None
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"type": self.type}
+        if self.operator is not None:
+            out["operator"] = self.operator
+        if self.value is not None:
+            out["value"] = self.value
+        return out
+
+
+#: 事件 ``context`` 允许出现的键。**白名单，不是建议** —— 事件会被存下来、
+#: 投出去、进模型上下文，任何"顺手多带一点"都会同时撑上下文和漏隐私。
+#: 宿主要更多信息，应该拿 ``signal`` + ``occurred_at`` 自己去查，而不是让
+#: kit 把存储 doc 塞进信封。
+ALLOWED_CONTEXT_KEYS = (
+    "scope",
+    # 触发字段的单位。产品规范 §13 的信封示例里就带着它，而且它是必要的：
+    # 一个只说 "current: 3012" 的事件，读到的人（和模型）分不出这是步数、
+    # 毫升还是分钟 —— manifest 花那么大力气要求数值必须有单位，
+    # 到了事件这一层丢掉，等于前功尽弃。
+    "unit",
+    "reason",
+    "streak_length",
+    "silent_seconds",
+)
+
+#: 单个 context 值序列化后的字符数上限。主要防的是 ``reason`` ——
+#: 它来自 evaluator，而宿主可以注册自己的 evaluator，返回什么完全不受我们控制。
+MAX_CONTEXT_VALUE_CHARS = 200
+
+
+def safe_context(raw: Mapping[str, Any] | None) -> dict[str, Any]:
+    """把任意来源的 context 收敛成信封允许的形状。
+
+    白名单外的键**丢掉**（不是报错：一条规则多带了个字段，不该让整个事件消失）；
+    超长的值截断并留一个显式的省略号，让读到的人知道这里被截过。
+    """
+    out: dict[str, Any] = {}
+    for key in ALLOWED_CONTEXT_KEYS:
+        if raw is None or key not in raw:
+            continue
+        value = raw[key]
+        # 值是 None 的键**整个省掉**，不写成 `"unit": null`。
+        # 布尔和枚举本来就没有单位，给它编一个空位比不给更糟 ——
+        # 读到的人会以为"这里本该有个单位，只是没填"。
+        # 和信封里 condition 省略 operator 是同一条约定。
+        if value is None:
+            continue
+        if isinstance(value, str) and len(value) > MAX_CONTEXT_VALUE_CHARS:
+            value = value[:MAX_CONTEXT_VALUE_CHARS] + "…(截断)"
+        out[key] = value
+    return out
+
+
+@dataclass(frozen=True)
+class PerceptionEvent:
+    """一次规则命中产生的不可变事实。"""
+
+    event_id: str
+    definition_id: str
+    definition_version: int
+    subject_id: str
+    type: str
+    signal: str
+    occurred_at: datetime
+    received_at: datetime
+    condition: EventCondition
+    #: 触发这条规则的字段。``occurrence`` 型规则(整条信号的到达本身就是事件)
+    #: 没有具体字段,为 ``None``。
+    field_name: str | None = None
+    #: 变化前后的值。``occurrence`` 型两者都是 ``None``。
+    previous: Any = None
+    current: Any = None
+    #: 受控的附加事实。键限定在 ``ALLOWED_CONTEXT_KEYS``、值有长度上限,
+    #: 都由 ``safe_context`` 收敛 —— 不许把整个存储 doc 透传进来,
+    #: 那既撑爆上下文,也漏隐私。
+    context: dict[str, Any] = field(default_factory=dict)
+    schema_version: int = versioning.EVENT_SCHEMA_VERSION
+
+    def to_dict(self) -> dict[str, Any]:
+        """序列化成宿主可以直接投递的形状。"""
+        return {
+            "event_id": self.event_id,
+            "definition_id": self.definition_id,
+            "definition_version": self.definition_version,
+            "subject_id": self.subject_id,
+            "type": self.type,
+            "signal": self.signal,
+            "field": self.field_name,
+            "occurred_at": to_iso(self.occurred_at),
+            "received_at": to_iso(self.received_at),
+            "previous": self.previous,
+            "current": self.current,
+            "condition": self.condition.to_dict(),
+            "context": dict(self.context),
+            "schema_version": self.schema_version,
+        }
+
+
+__all__ = ["ALLOWED_CONTEXT_KEYS", "MAX_CONTEXT_VALUE_CHARS",
+           "EventCondition", "PerceptionEvent", "safe_context"]

perceptkit/contracts/observation.py

@@ -0,0 +1,172 @@
+"""标准观测 —— 上报数据经过校验和标准化之后的样子。
+
+这是整套系统里**唯一**的事实载体:current 是它的投影,日聚合是它的派生,
+事件是对它的判断。三者都可以从观测重算,反过来不行 —— 聚合是压缩过的,
+压缩不可逆。所以"只存 current 和日聚合、不存观测"会让修订、删除、
+算法升级后的重算**全部做不了**。
+
+时区为什么单独一个字段,而不是从 ``occurred_at`` 的偏移推:
+偏移只够算"这条算哪一天",不够处理夏令时。``+08:00`` 能定位到日期,
+但纽约的 ``-04:00`` 和 ``-05:00`` 是同一个时区在不同季节 —— 光看偏移
+分不出来,DST 切换那天(那天有 25 小时)就会算错。所以要 IANA 名字。
+
+``timezone`` 缺失时怎么办属于处理层的兜底策略,不在契约里定死 ——
+见 ``OPEN-QUESTIONS.md`` B2,这一条还没和产品方对齐。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from . import availability as _availability
+from ._time import TimestampError, parse_timestamp
+from .errors import ContractError
+
+
+@dataclass(frozen=True)
+class Observation:
+    """一条标准观测(wire 形态 —— producer 发过来的样子)。
+
+    存储形态比这个多几个字段(``observation_id`` / ``subject_id`` /
+    ``received_at`` / ``effective_local_date``),那些由宿主或处理层补,
+    不由 producer 提供 —— 见 :mod:`perceptkit.contracts.records`。
+    """
+
+    signal: str
+    signal_schema_version: int
+    occurred_at: datetime
+    availability: str
+    #: ``observed`` 时必填。``0`` / ``False`` / ``[]`` 都是合法值。
+    value: dict[str, Any] | None = None
+    #: 上游的稳定身份,用于重传幂等。事件型/样本型必填;
+    #: 纯状态型(如电量快照)可以没有,由 manifest 声明确定性 identity 策略。
+    source_event_id: str | None = None
+    #: 发生时的 IANA 时区名(如 ``Asia/Shanghai``)。见模块开头。
+    timezone: str | None = None
+    #: 来源侧的版本号。只有支持修订的来源(HealthKit / Calendar)才有。
+    source_revision: str | int | None = None
+    #: ``unavailable`` 时的粗粒度原因。默认不进 agent 的上下文。
+    reason: str | None = None
+    #: 协议没定义的额外字段。原样保留便于排查,不参与判断。
+    extensions: dict[str, Any] = field(default_factory=dict)
+
+    # -- 派生判断（都只读 availability，集中在这里免得每个调用方各判一次） --
+
+    @property
+    def is_observed(self) -> bool:
+        return _availability.normalize(self.availability) == _availability.OBSERVED
+
+    @property
+    def updates_current(self) -> bool:
+        """这条该不该更新 current 的数值。"""
+        return _availability.updates_current(self.availability)
+
+    @property
+    def enters_trend(self) -> bool:
+        """这条该不该进趋势和 streak。``no_data`` 不当 0 用。"""
+        return _availability.enters_trend(self.availability)
+
+    @classmethod
+    def parse(cls, payload: object) -> "Observation":
+        """从一个 dict 解析并校验。错误一次报全,不是遇到第一个就抛。"""
+        errors: list[str] = []
+        if not isinstance(payload, dict):
+            raise ContractError(
+                [f"observation must be an object, got {type(payload).__name__}"]
+            )
+
+        signal = payload.get("signal")
+        if not isinstance(signal, str) or not signal.strip():
+            errors.append("signal: required, must be a non-empty string")
+
+        version = payload.get("signal_schema_version")
+        if isinstance(version, bool) or not isinstance(version, int):
+            errors.append("signal_schema_version: required, must be an integer")
+
+        occurred_at: datetime | None = None
+        try:
+            occurred_at = parse_timestamp(payload.get("occurred_at"), field="occurred_at")
+        except TimestampError as exc:
+            errors.append(str(exc))
+
+        # 产品规范 §7.1 的最小契约把这个字段叫 `state`，把身份字段叫
+        # `sample_id`。我们内部用更长的名字（`state` 这个词在别处已经被
+        # 用作"规则状态"，`sample_id` 又太偏健康样本），但**两种写法都收** ——
+        # 照着规范文档实现的 producer 必须能直接接上，否则它的每一条观测
+        # 都会以"availability 缺失"被拒，而实现者手里那份文档写的就是 `state`。
+        raw_state = payload.get("availability", payload.get("state"))
+        if not isinstance(raw_state, str):
+            errors.append("availability: required, must be a string")
+            state = _availability.UNAVAILABLE
+        elif raw_state not in _availability.LEGACY_STATES:
+            errors.append(
+                f"availability: {raw_state!r} is not one of "
+                f"{sorted(_availability.AVAILABILITY_STATES)}"
+            )
+            state = _availability.UNAVAILABLE
+        else:
+            state = _availability.normalize(raw_state)
+
+        value = payload.get("value")
+        if state == _availability.OBSERVED:
+            # observed 就必须有值。注意 `{}` 是合法的(某些信号的 payload 本来就空),
+            # 但 None 不是 —— 那说明 producer 自己也不知道观测到了什么。
+            if value is None:
+                errors.append("value: required when availability is 'observed'")
+            elif not isinstance(value, dict):
+                errors.append(
+                    f"value: must be an object, got {type(value).__name__}"
+                )
+        elif value is not None and not isinstance(value, dict):
+            errors.append(f"value: must be an object when present, got {type(value).__name__}")
+
+        source_event_id = payload.get("source_event_id",
+                                     payload.get("sample_id"))
+        if source_event_id is not None and (
+            not isinstance(source_event_id, str) or not source_event_id.strip()
+        ):
+            errors.append("source_event_id: must be a non-empty string when present")
+
+        tz = payload.get("timezone")
+        if tz is not None and (not isinstance(tz, str) or not tz.strip()):
+            errors.append("timezone: must be a non-empty IANA name when present")
+
+        revision = payload.get("source_revision")
+        if revision is not None and not isinstance(revision, (str, int)):
+            errors.append("source_revision: must be a string or integer when present")
+
+        reason = payload.get("reason")
+        if reason is not None:
+            if not isinstance(reason, str):
+                errors.append("reason: must be a string when present")
+            elif reason not in _availability.UNAVAILABLE_REASONS:
+                # 不拒收 —— 只是提醒用粗粒度的那几个。穷举操作系统的每种权限
+                # 状态属于 adapter 的诊断,不该硬塞进公共协议。
+                errors.append(
+                    f"reason: {reason!r} is not one of "
+                    f"{sorted(_availability.UNAVAILABLE_REASONS)}"
+                )
+
+        if errors:
+            raise ContractError(errors)
+
+        known = {
+            "signal", "signal_schema_version", "occurred_at", "availability",
+            "value", "source_event_id", "timezone", "source_revision", "reason",
+        }
+        return cls(
+            signal=signal.strip(),                 # type: ignore[union-attr]
+            signal_schema_version=version,         # type: ignore[arg-type]
+            occurred_at=occurred_at,               # type: ignore[arg-type]
+            availability=state,
+            value=value,
+            source_event_id=source_event_id.strip() if source_event_id else None,
+            timezone=tz.strip() if tz else None,
+            source_revision=revision,
+            reason=reason,
+            extensions={k: v for k, v in payload.items() if k not in known},
+        )
+
+
+__all__ = ["Observation"]

perceptkit/contracts/receipt.py

@@ -0,0 +1,129 @@
+"""两种回执 —— 上报进来的回执,和事件投出去的回执。
+
+``IngestReceipt`` 让同一批上报重传时能返回相同结果,不重复处理。
+``WakeReceipt`` 让"到底投没投成"变成一个可持久化、可查询的事实,
+而不是一个只存在于某次函数调用里的瞬时值。
+
+**为什么 wake 的状态不能只有成功/失败两种**:runtime 拒绝一次唤醒有好几种
+完全不同的原因,处理方式也不同 —— 会话里正忙(等下次就好)和入队失败
+(得重试)混成一个"失败",要么该重试的没重试,要么不该重试的一直重试。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from ._time import parse_timestamp
+from .errors import ContractError
+
+# ---------------------------------------------------------------------------
+# 上报回执
+# ---------------------------------------------------------------------------
+
+#: 这批上报第一次被处理。
+INGEST_ACCEPTED = "accepted"
+#: 同一个 (subject, producer, report_id) + 相同内容 —— 返回原结果,不重复处理。
+INGEST_DUPLICATE = "duplicate"
+#: 同一个 identity 但内容不同。**必须报冲突,不能静默覆盖** ——
+#: 静默覆盖会让"到底哪份数据生效了"永远说不清。
+INGEST_CONFLICT = "conflict"
+#: 校验没过。``error_code`` 说明原因。
+INGEST_REJECTED = "rejected"
+
+INGEST_STATUSES: frozenset[str] = frozenset({
+    INGEST_ACCEPTED, INGEST_DUPLICATE, INGEST_CONFLICT, INGEST_REJECTED,
+})
+
+
+@dataclass(frozen=True)
+class IngestReceipt:
+    """一批上报的处理结果。唯一身份是 ``(subject_id, producer, report_id)``。"""
+
+    subject_id: str
+    producer: str
+    report_id: str
+    #: 信封内容的摘要。同 identity 同摘要 → duplicate;同 identity 不同摘要 → conflict。
+    payload_digest: str
+    received_at: datetime
+    status: str
+    error_code: str | None = None
+    #: 这批里有几条观测被真正处理了(duplicate 时为 0)。
+    observations_applied: int = 0
+
+    def __post_init__(self) -> None:
+        if self.status not in INGEST_STATUSES:
+            raise ContractError(
+                [f"status: {self.status!r} is not one of {sorted(INGEST_STATUSES)}"]
+            )
+        parse_timestamp(self.received_at, field="received_at")
+
+
+# ---------------------------------------------------------------------------
+# 唤醒回执
+# ---------------------------------------------------------------------------
+
+#: runtime 收下了这次唤醒。**只有这个状态才允许正式扣冷却/额度。**
+WAKE_ACCEPTED = "accepted"
+#: runtime 认得这个 ``event_id``,之前已经处理过。重试撞上它是正常的,不是错误。
+WAKE_DUPLICATE = "duplicate"
+#: runtime 现在不想被打扰(会话正忙、安静时段…)。**这不是失败** ——
+#: 事件已经送到了,是 runtime 自己决定不响应。不该重试。
+WAKE_SUPPRESSED = "conversation_suppressed"
+#: 投递本身失败了(队列写不进、连接断)。**该重试。**
+WAKE_ENQUEUE_FAILED = "enqueue_failed"
+#: runtime 明确拒绝(事件类型不认、subject 不属于它…)。不该重试。
+WAKE_REJECTED = "rejected"
+
+WAKE_STATUSES: frozenset[str] = frozenset({
+    WAKE_ACCEPTED, WAKE_DUPLICATE, WAKE_SUPPRESSED,
+    WAKE_ENQUEUE_FAILED, WAKE_REJECTED,
+})
+
+#: 这几种状态该重试。其余的是终态。
+#: 注意 ``conversation_suppressed`` **不在**里面 —— 事件已经送达,
+#: 是 runtime 自己选择不响应,重投只会打扰第二次。
+WAKE_RETRYABLE: frozenset[str] = frozenset({WAKE_ENQUEUE_FAILED})
+
+
+@dataclass(frozen=True)
+class WakeReceipt:
+    """runtime 对一次投递的应答。"""
+
+    event_id: str
+    #: 这是第几次尝试。``event_id`` 跨重试**保持不变**(runtime 靠它幂等),
+    #: ``attempt_id`` 每次都变(用来对上具体是哪一次投递的回执)。
+    attempt_id: str
+    status: str
+    received_at: datetime
+    #: 宿主自己的引用(job id、任务号…)。kit 不解释它的内容,原样存。
+    runtime_ref: str | None = None
+    reason: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.status not in WAKE_STATUSES:
+            raise ContractError(
+                [f"status: {self.status!r} is not one of {sorted(WAKE_STATUSES)}"]
+            )
+        parse_timestamp(self.received_at, field="received_at")
+
+    @property
+    def should_retry(self) -> bool:
+        return self.status in WAKE_RETRYABLE
+
+    @property
+    def consumes_budget(self) -> bool:
+        """这次投递该不该正式扣冷却/额度。
+
+        **只有 accepted 算。** 被压制、入队失败、被拒绝都不该扣 —— 用户
+        那一轮该说的话没说出去,额度却被吃掉了,是最难查的一类问题。
+        """
+        return self.status == WAKE_ACCEPTED
+
+
+__all__ = [
+    "INGEST_ACCEPTED", "INGEST_DUPLICATE", "INGEST_CONFLICT", "INGEST_REJECTED",
+    "INGEST_STATUSES", "IngestReceipt",
+    "WAKE_ACCEPTED", "WAKE_DUPLICATE", "WAKE_SUPPRESSED",
+    "WAKE_ENQUEUE_FAILED", "WAKE_REJECTED", "WAKE_STATUSES", "WAKE_RETRYABLE",
+    "WakeReceipt",
+]