perceptkit 0.2.2__py3-none-any.whl

perceptkit/__init__.py

@@ -0,0 +1,85 @@
+"""perceptkit —— 主动感知内核:纯函数、零 I/O,与宿主环境无关。
+
+这个包只做判断,不做执行:
+
+  · 有没有发生什么值得留意的事(glance,只出 bool,不泄露具体数值)
+  · 这次变化值不值得叫醒一次 agent(wake)
+  · 一条测量到底是"有观测到零值"还是"压根没测到"(observation 四态)
+  · 一条测量该记在本地日历的哪一天(attribution)
+  · "连续 N 天"怎么断续、只在跨入异常时触发一次(streaks)
+  · 按天汇总出什么趋势 —— 波动 / 漂移 / 周期性,三种判读方式(history / trend_models)
+  · agent 能看哪些字段、该不该给(fields)
+  · 该怎么把以上这些讲给模型(prompts)
+  · 每类信号的历史该留多久、一条测量的去重键怎么造(retention / identity)
+
+**wake ≠ 该开口了。** 戳醒之后继续睡 / 只看一眼 / 开口说话是三个平行选项,
+这个包不参与那个决定,也不产出任何"该说话了"式的措辞。
+
+不在这里的(由调用方提供):
+
+  数据采集 · 存储 · 加解密 · 账号身份与鉴权 · 定时器 / 调度 ·
+  真正调模型 · 决定 agent 最终该说什么话
+
+硬指标:**本包只依赖标准库**,不 import 任何宿主模块、不碰网络、不碰数据库、
+不碰文件系统。一旦这条破了,"内核可独立发布 / 可被任意宿主嵌入"就都不成立
+——见 ``tests/test_purity.py``(AST 扫描)与 ``tests/test_no_host_leakage.py``。
+
+详见 ``README.md``。
+"""
+from __future__ import annotations
+
+from . import contracts, manifest, ports, processing, rules
+from .algorithms.attribution import attribute_episode, attribute_instant, split_across_midnight
+from .catalog import CAPABILITIES, SIGNALS
+from .contracts import IngestContext, Observation, PerceptionEvent, ReportEnvelope, WakeReceipt
+from .kit import PerceptionKit
+from .fields import AGENT_PERCEPTION_SIGNALS, project_signal
+from .algorithms.glance import build_perception_glance
+from .algorithms.history import is_historized
+from .algorithms.identity import MissingIdentity, measurement_key
+from .algorithms.observation import (
+    NO_OBSERVATION,
+    OBSERVED,
+    OBSERVED_ZERO,
+    UNAVAILABLE,
+    classify,
+    is_trend_eligible,
+)
+from .retention import retention_days, stores_history
+from .algorithms.streaks import current_streak, should_trigger
+from .algorithms.trend_models import model_for, wake_eligible
+from .algorithms.wake import is_wake_worthy_signal, is_significant_change, should_wake
+
+__all__ = [
+    # 接入口
+    "PerceptionKit",
+    "ReportEnvelope", "Observation", "PerceptionEvent", "WakeReceipt", "IngestContext",
+    "contracts", "manifest", "ports", "processing", "rules",
+    # 算法
+    "attribute_episode",
+    "attribute_instant",
+    "split_across_midnight",
+    "CAPABILITIES",
+    "SIGNALS",
+    "AGENT_PERCEPTION_SIGNALS",
+    "project_signal",
+    "build_perception_glance",
+    "is_historized",
+    "MissingIdentity",
+    "measurement_key",
+    "NO_OBSERVATION",
+    "OBSERVED",
+    "OBSERVED_ZERO",
+    "UNAVAILABLE",
+    "classify",
+    "is_trend_eligible",
+    "retention_days",
+    "stores_history",
+    "current_streak",
+    "should_trigger",
+    "model_for",
+    "wake_eligible",
+    "is_wake_worthy_signal",
+    "is_significant_change",
+    "should_wake",
+]

perceptkit/algorithms/__init__.py

@@ -0,0 +1,40 @@
+"""纯计算 —— 给定输入算出结果，不碰存储、不碰网络、不认识任何宿主。
+
+产品规范 §18 要求这一层单独存在：「不能再把 contract、算法、存储、
+宿主 runtime 接线混成一层」。先前这些模块散在包的顶层，和 ``kit.py``
+（装配和接线）平级，正是那句话说的情况。
+
+**分出来不只是好看。** 这一层是唯一可以放心大改的地方 —— 它没有副作用、
+没有顺序依赖，一个函数改错了测试当场红，而不会在某个宿主的生产环境里
+变成一条静默错掉的记录。
+
+    attribution    一条观测算哪一天（跨午夜、跨时区、夏令时）
+    glance         把感知事实压成一组布尔，给不需要细节的调用方
+    history        日聚合的各种形状与合并
+    identity       上游给不了稳定 id 时怎么造一个确定性的
+    observation    三态判断（测到 / 没测到 / 不能测）
+    streaks        连续 N 天
+    trend_models   三种趋势模型的数学
+    wake           值不值得戳醒（**不回答该不该开口**）
+
+**刻意留在顶层、没搬进来的四个**：``catalog`` / ``fields`` / ``retention``
+是声明表不是算法（而且正在被 manifest 取代），``prompts`` 归属还没定
+（见给产品方的回复 §三）。把它们塞进 algorithms/ 只会让这个词失去意义。
+"""
+from __future__ import annotations
+
+from . import (  # noqa: F401
+    attribution,
+    glance,
+    history,
+    identity,
+    observation,
+    streaks,
+    trend_models,
+    wake,
+)
+
+__all__ = [
+    "attribution", "glance", "history", "identity",
+    "observation", "streaks", "trend_models", "wake",
+]

perceptkit/algorithms/attribution.py

@@ -0,0 +1,147 @@
+"""一条测量该算哪一天。
+
+★ 为什么需要这个模块（设计文档修订 D）：标准里的 effective_time_frame 只描述
+  「事实发生于某个点或某段区间」，它不替产品决定「算哪一天」。睡眠 23:00–07:00
+  按直觉是「第二天的睡眠」，而在公司待的时长跨午夜时必须切成两天 —— 这是两条
+  不同的规则，不能一刀切。
+
+★ 时区：一律用时间自带的 offset。缺 offset 直接报错，不猜 —— 静默按 UTC 或
+  按用户当前时区重解释，会让历史数据在用户出国时集体漂一天。
+
+★ 零 I/O、不读时钟。
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import zoneinfo as _zoneinfo
+
+INSTANT = "instant"                        # 单点：按其自带 offset 的本地日期
+EPISODE_END = "episode_end"                # 区间：整体归结束（醒来）那天
+SPLIT_AT_MIDNIGHT = "split_at_midnight"    # 可加总时长：按本地午夜切分
+SOURCE_LOCAL_DATE = "source_local_date"    # 周期事件：用来源记录的本地日期，不重解释
+
+ATTRIBUTION: dict[str, str] = {
+    "health_sleep": EPISODE_END,
+    "health_workout": EPISODE_END,
+    "health_body": INSTANT,
+    "health_vitals": INSTANT,
+    "health_metabolic": INSTANT,
+    "health_activity": INSTANT,
+    "health_mood": INSTANT,
+    "health_cycle": SOURCE_LOCAL_DATE,
+    "location_signal": SPLIT_AT_MIDNIGHT,
+    "playback": SPLIT_AT_MIDNIGHT,
+    "motion_state": SPLIT_AT_MIDNIGHT,
+    "focus": SPLIT_AT_MIDNIGHT,
+    "audio_route": SPLIT_AT_MIDNIGHT,
+    # calendar_next_event / reminders：条目自带日期(来自日历/提醒事项存储)，
+    # 按用户「当前」时区重解释会在他出国时把一场会议错移到另一天 ——
+    # 正是这个模块存在的目的要防的那类漂移，所以用来源本地日期,不重算。
+    "calendar_next_event": SOURCE_LOCAL_DATE,
+    "reminders": SOURCE_LOCAL_DATE,
+    # weather 现在的 SHAPE 是 NUMERIC_DIST（history.py），是单点测量，
+    # 跟体重/心率同类 —— 归属规则是 INSTANT。
+    # ⚠️ Codex code_review 2026-08-23 抓到：早先按"weather 即将改成仅当前+预报、
+    # 不再产生 rollup"的未来态把这条声明成了"故意缺席"，但 SHAPE/record_daily
+    # 从未真的改过去，导致四张声明表互相矛盾（history 说存、retention/attribution
+    # 说不存）。真要把 weather 改成不存历史时，这一行、retention.RETENTION_DAYS
+    # 里的 weather 条目、history.SHAPE 里的 weather 条目，三处必须在同一批
+    # 一起删，不许只删一处。
+    "weather": INSTANT,
+}
+
+
+def _aware(raw: str) -> _dt.datetime:
+    """解析成带 offset 的时刻。没有 offset 就报错 —— 不猜。"""
+    try:
+        parsed = _dt.datetime.fromisoformat(str(raw))
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"无法解析时间：{raw!r}") from exc
+    if parsed.tzinfo is None or parsed.utcoffset() is None:
+        raise ValueError(f"时间缺少时区 offset，拒绝按 UTC 或本机时区猜测：{raw!r}")
+    return parsed
+
+
+def _utc_naive(dtobj: _dt.datetime) -> _dt.datetime:
+    """把一个 aware datetime 精确转成"UTC 等价的裸 datetime"，用于比较/相减。
+
+    见 ``split_across_midnight`` 里的坑注释：两个 aware datetime 若共享同一个
+    ``tzinfo`` 对象，CPython 的 `<`/`-` 会走一条忽略 offset 变化的捷径，对
+    ``ZoneInfo`` 这种 offset 会随日期变的时区算错。显式转成裸 UTC datetime
+    绕开这条捷径；用 timedelta 精确运算，不经过 float epoch，避免精度损失。
+    """
+    return dtobj.replace(tzinfo=None) - dtobj.utcoffset()
+
+
+def attribute_instant(when: str) -> str:
+    """单点测量：按它自己那个 offset 下的本地日期。"""
+    return _aware(when).date().isoformat()
+
+
+def attribute_episode(start: str, end: str) -> str:
+    """区间事件（睡眠、一次运动）：整体归结束那天。"""
+    s, e = _aware(start), _aware(end)
+    if e < s:
+        raise ValueError(f"区间结束早于开始：{start!r} -> {end!r}")
+    return e.date().isoformat()
+
+
+def split_across_midnight(start: str, end: str, *, tz: str | None = None) -> list[tuple[str, float]]:
+    """可加总的时长：按本地午夜切开，返回 ``[(本地日期, 分钟数), ...]``。
+
+    ``tz``（可选）：传入 IANA 时区名（如 ``"America/New_York"``）时，用
+    ``zoneinfo.ZoneInfo`` 按该时区的真实换日规则计算本地午夜 —— 跨夏令时
+    切换的那一天会正确算出 23 小时（春季提前）或 25 小时（秋季回退），
+    不会被硬当成 1440 分钟。
+
+    不传 ``tz`` 时（默认）：本地午夜用 ``start`` 自带的 offset 推算 —— 这是
+    一个**固定** offset，不是一整套带换日规则的时区。★ 老实说明局限：跨夏
+    令时切换的那一天，本函数并不知道当地钟表在那天真的跳了一小时，切分点
+    仍按「每天 1440 分钟」机械推进，那一天算出来的分钟数会是错的（例如秋季
+    回退的 25 小时天，仍会被切成 24×60）。要正确处理夏令时切换，必须显式
+    传入 ``tz``。
+
+    各段分钟数不做单独四舍五入 —— 调用方需要展示或落库时再自己 round，
+    否则多段各自舍入会破坏「各段之和 = 总时长」这个不变式（例如跨午夜的
+    0.08 秒会被两段各自舍成 0.001，加总 0.002，而真实值是 0.001333...）。
+    """
+    s, e = _aware(start), _aware(end)
+    if e < s:
+        raise ValueError(f"区间结束早于开始：{start!r} -> {end!r}")
+    if e == s:
+        return []
+
+    zone = _zoneinfo.ZoneInfo(tz) if tz else None
+    if zone is not None:
+        s = s.astimezone(zone)
+        e = e.astimezone(zone)
+
+    # ★ 坑（真实调试过，别删）：下面比较/相减都拿 `_utc_naive()` 转换过的值，
+    #   不直接对两个 aware datetime 做 `<` / `-`。原因是 CPython 对"两个 aware
+    #   datetime 共享同一个 tzinfo 对象"有一条捷径：直接比较墙上时间、完全不
+    #   重新问 tzinfo 要 offset —— 对固定 offset 的 tzinfo 这条捷径没问题
+    #   （offset 反正不变），但 ZoneInfo 的 offset 会随日期变（换季），同一个
+    #   ZoneInfo 对象在夏令时切换前后 offset 不同，这条捷径会把跨切换的那一段
+    #   整整算错一小时。`_utc_naive()` 每次都显式调用 `.utcoffset()` 拿当下
+    #   那个墙上时间对应的真实 offset，不吃这条捷径；且转换本身是 timedelta
+    #   精确运算（不经过 float epoch），不会像 `.timestamp()` 那样在秒级精度
+    #   之外引入浮点误差。
+    e_utc = _utc_naive(e)
+    out: list[tuple[str, float]] = []
+    cursor = s
+    cursor_utc = _utc_naive(cursor)
+    while cursor_utc < e_utc:
+        next_midnight = _dt.datetime.combine(
+            cursor.date() + _dt.timedelta(days=1),
+            _dt.time(0, 0),
+            tzinfo=cursor.tzinfo,
+        )
+        next_midnight_utc = _utc_naive(next_midnight)
+        if next_midnight_utc < e_utc:
+            chunk_end, chunk_end_utc = next_midnight, next_midnight_utc
+        else:
+            chunk_end, chunk_end_utc = e, e_utc
+        minutes = (chunk_end_utc - cursor_utc).total_seconds() / 60.0
+        out.append((cursor.date().isoformat(), minutes))
+        cursor, cursor_utc = chunk_end, chunk_end_utc
+    return out

perceptkit/algorithms/glance.py

@@ -0,0 +1,236 @@
+"""Pure, number-free projections for Runtime V2 proactive perception."""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+import hashlib
+import json
+import math
+import sys
+from typing import Any, Callable
+
+_HEALTH_SIGNALS = ("steps", "sleep", "workout", "vitals", "activity", "body", "metabolic", "cycle")
+_HEALTH_HISTORY = frozenset({
+    "health_vitals", "health_sleep", "health_workout", "health_activity",
+    "health_body", "health_metabolic", "health_cycle",
+})
+_EXPIRED_MARKERS = frozenset({"expired", "stale", "is_expired", "is_stale"})
+_EVENT_FIELDS = {
+    "unlock_after_absence": {"trigger": "unlock_after_absence", "returned_after_absence": True},
+    "arrived_at_anchor": {"trigger": "arrived_at_anchor", "anchor_changed": True},
+    "photo_added": {"trigger": "photo_added", "new_photo": True},
+    "scene_change": {"trigger": "scene_change"},
+    "broadcast_opened": {"trigger": "broadcast_opened", "screen_share_started": True},
+    "broadcast_closed": {"trigger": "broadcast_closed", "screen_share_ended": True},
+}
+V1_PRESENCE_HINT_FIELDS = (
+    "place_label",
+    "motion_state",
+    "now_playing",
+    "locale",
+    "broadcast_state",
+    "broadcast_active",
+)
+
+
+def _finite_number(value: Any) -> bool:
+    if type(value) is int:
+        # Preserve the projector's historical "finite float" input range
+        # without coercing an arbitrary-precision int through float(), which
+        # raises OverflowError for malformed giant values.
+        return -sys.float_info.max <= value <= sys.float_info.max
+    if type(value) is float:
+        return math.isfinite(value)
+    return False
+
+
+def _text(value: Any) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _items(value: Any, predicate: Callable[[Any], bool]) -> bool:
+    return (
+        isinstance(value, Sequence)
+        and not isinstance(value, (str, bytes, bytearray))
+        and any(predicate(item) for item in value)
+    )
+
+
+def _event(value: Any) -> bool:
+    return isinstance(value, Mapping) and any((
+        _text(value.get("title")),
+        _text(value.get("start_time")),
+        _finite_number(value.get("starts_in_min")),
+        _finite_number(value.get("minutes_until_start")),
+    ))
+
+
+def _reminder(value: Any) -> bool:
+    return isinstance(value, Mapping) and any((
+        _text(value.get("title")),
+        _text(value.get("due_time")),
+        _text(value.get("due_date")),
+        type(value.get("overdue")) is bool,
+    ))
+
+
+def _alert(value: Any) -> bool:
+    return isinstance(value, Mapping) and any(
+        _text(value.get(field)) for field in ("title", "summary", "headline", "description", "severity")
+    )
+
+
+def _doc(signals: Mapping[str, Any], name: str) -> Mapping[str, Any]:
+    value = signals.get(name)
+    if (
+        not isinstance(value, Mapping)
+        or value.get("disabled") is True
+        or value.get("fresh") is False
+        or any(value.get(marker) is True for marker in _EXPIRED_MARKERS)
+    ):
+        return {}
+    return value
+
+
+def _available(
+    doc: Mapping[str, Any],
+    *,
+    number_fields: Sequence[str] = (),
+    text_fields: Sequence[str] = (),
+    bool_fields: Sequence[str] = (),
+    event_fields: Sequence[str] = (),
+) -> bool:
+    return any(_finite_number(doc.get(field)) for field in number_fields) or any(
+        _text(doc.get(field)) for field in text_fields
+    ) or any(type(doc.get(field)) is bool for field in bool_fields) or any(
+        _event(doc.get(field)) for field in event_fields
+    )
+
+
+def _positive_count(value: Any) -> bool:
+    return _finite_number(value) and value > 0
+
+
+def build_perception_glance(
+    signals: Mapping[str, Mapping[str, Any]],
+    *,
+    notable_changes: Sequence[Mapping[str, Any]] = (),
+) -> dict[str, dict[str, bool]]:
+    safe_signals = signals if isinstance(signals, Mapping) else {}
+    changed = {
+        str(item.get("signal") or "")
+        for item in notable_changes
+        if isinstance(item, Mapping)
+    }
+    out: dict[str, dict[str, bool]] = {}
+    location = _doc(safe_signals, "location")
+    if _available(location, text_fields=("place_label", "wifi_label", "country", "locality", "wifi_anchor_id")):
+        out["location"] = {"available": True, "notable_change": "location_signal" in changed}
+    now = _doc(safe_signals, "now")
+    playing = now.get("now_playing")
+    if isinstance(playing, Mapping) and _available(playing, text_fields=("title", "artist", "album", "playback_state")):
+        out["media"] = {"available": True, "active": True, "notable_change": "playback" in changed}
+    app = _doc(safe_signals, "app")
+    if _available(app, text_fields=("app_name", "app_category", "app_state")):
+        out["app"] = {"available": True, "recent_activity": True}
+    health_docs = [_doc(safe_signals, name) for name in _HEALTH_SIGNALS]
+    if any((
+        _available(health_docs[0], number_fields=("step_count",)),
+        _available(health_docs[1], number_fields=("asleep_minutes", "core_minutes", "deep_minutes", "rem_minutes")),
+        _available(health_docs[2], number_fields=("duration_min", "count_today"), text_fields=("workout_type",)),
+        _available(health_docs[3], number_fields=("resting_heart_rate", "step_count", "current_heart_rate", "hrv_sdnn_ms", "respiratory_rate", "oxygen_saturation_pct", "vo2_max")),
+        _available(health_docs[4], number_fields=("active_energy_kcal", "exercise_minutes", "stand_minutes", "mindful_minutes")),
+        _available(health_docs[5], number_fields=("weight_kg", "bmi", "body_fat_pct", "height_cm")),
+        _available(health_docs[6], number_fields=("blood_glucose_mmol_l", "blood_pressure_systolic", "blood_pressure_diastolic")),
+        _available(health_docs[7], text_fields=("flow_level",), bool_fields=("is_active_period",)),
+    )):
+        out["health"] = {"available": True, "notable_change": bool(changed & _HEALTH_HISTORY)}
+    weather = _doc(safe_signals, "weather")
+    if _available(
+        weather,
+        number_fields=("temperature", "apparent_temperature", "humidity", "precipitation_chance", "uv_index"),
+        text_fields=("condition",),
+        bool_fields=("is_daylight",),
+    ) or _items(weather.get("alerts"), _alert):
+        out["weather"] = {"available": True, "notable_change": "weather" in changed}
+    mood = _doc(safe_signals, "mood")
+    if _available(mood, number_fields=("valence", "label_count"), text_fields=("valence_classification", "kind"), bool_fields=("recorded_today",)):
+        out["mood"] = {"available": True, "recorded": mood.get("recorded_today") is True}
+    reminders = _doc(safe_signals, "reminders")
+    if _available(
+        reminders,
+        number_fields=("overdue_count", "due_today_count"),
+        text_fields=("next_reminder",),
+        bool_fields=("reminders_truncated",),
+    ) or _items(reminders.get("reminders"), _reminder):
+        out["reminders"] = {
+            "available": True,
+            "has_due": _positive_count(reminders.get("due_today_count")),
+            "has_overdue": _positive_count(reminders.get("overdue_count")),
+        }
+    calendar = _doc(safe_signals, "calendar")
+    if _available(calendar, event_fields=("calendar_next_event",)) or _items(calendar.get("calendar_events"), _event):
+        out["calendar"] = {
+            "available": True,
+            "has_upcoming": _event(calendar.get("calendar_next_event")) or _items(calendar.get("calendar_events"), _event),
+        }
+    return out
+
+
+def project_perception_wake_events(items: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    """Project the producer-bounded wake facts, excluding internal cursor data.
+
+    ``serve_worker._read_perception_wake_context`` is the trust boundary that
+    limits every string/list/scalar.  The old projection discarded those facts
+    and retained only a trigger-derived constant, leaving the provider unable to
+    tell what actually changed.  Copy only the closed field set consumed by the
+    prompt; never pass through arbitrary keys from storage.
+    """
+    out: list[dict[str, Any]] = []
+    for item in items:
+        if not isinstance(item, Mapping):
+            continue
+        trigger = str(item.get("trigger") or "")
+        if trigger not in _EVENT_FIELDS:
+            continue
+        projected: dict[str, Any] = dict(_EVENT_FIELDS[trigger])
+        for field, cap in (
+            ("wake_id", 160),
+            ("source", 120),
+            ("change_digest", 2000),
+        ):
+            value = str(item.get(field) or "")[:cap]
+            if value:
+                projected[field] = value
+        origin_refs = [
+            str(ref)[:200] for ref in list(item.get("origin_refs") or [])[:10]
+        ]
+        if origin_refs:
+            projected["origin_refs"] = origin_refs
+        raw_hints = item.get("presence_hints")
+        hints: dict[str, bool | int | float | str] = {}
+        if isinstance(raw_hints, Mapping):
+            for key in V1_PRESENCE_HINT_FIELDS:
+                value = raw_hints.get(key)
+                safe_key = str(key)[:80]
+                if isinstance(value, bool):
+                    hints[safe_key] = value
+                elif isinstance(value, int):
+                    hints[safe_key] = value
+                elif isinstance(value, float) and math.isfinite(value):
+                    hints[safe_key] = value
+                elif isinstance(value, str):
+                    hints[safe_key] = value[:200]
+        if hints:
+            projected["presence_hints"] = hints
+        if trigger == "photo_added":
+            for field, cap in (("photo_id", 160), ("scene", 200), ("time_of_day", 80)):
+                value = str(item.get(field) or "")[:cap]
+                if value:
+                    projected[field] = value
+        out.append(projected)
+    return out
+
+
+def perception_glance_fingerprint(glance: Mapping[str, Any]) -> str:
+    canonical = json.dumps(glance, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()