perceptkit 0.2.2__py3-none-any.whl

perceptkit/processing/recurrence.py

@@ -0,0 +1,166 @@
+"""重复日程的滚动展开。
+
+产品规范 §12：「Calendar 无限重复事件 | 保存 rule/series，并滚动展开查询窗口」。
+先前只有 ``recurrence_identity`` 这个字段，没有展开逻辑 —— 于是"每周一的例会"
+要么被展开到无限未来存进库，要么就查不到。
+
+## 为什么只做一个子集
+
+完整的 RFC 5545 RRULE 是一整个库的量（BYSETPOS、EXDATE、跨夏令时的
+BYHOUR、闰月…），而这个包是零依赖的。硬做等于在包里重新实现一个日历库，
+**而重复日程算错日期是那种「看起来完全正常」的错**：用户会准时出现在
+一个不存在的会议上。
+
+所以这里只认一个小而确定的子集，**不认识的一律明确拒绝**，
+由宿主自己展开好再传进来。拒绝是安全的，猜不是。
+
+    认    每天 / 每周（可指定星期几）/ 每月同一天，带 interval、until、count
+    不认  BYSETPOS(「每月第二个周二」)、EXDATE(「除了这几天」)、
+          按年、以及任何我们没把握的写法
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from typing import Any, Mapping
+
+#: 一次展开最多产出多少条。**必须有上限** —— "每天，永不结束"配上一个
+#: 十年的查询窗口就是三千多条直接塞进模型上下文。
+MAX_INSTANCES = 200
+
+SUPPORTED_FREQ = ("daily", "weekly", "monthly")
+
+#: 我们明确不支持的写法。列出来是为了让拒绝的理由能说清是哪一条，
+#: 而不是笼统一句"不支持"。
+UNSUPPORTED_KEYS = {
+    "bysetpos": "「每月第二个周二」这类按序号选的规则",
+    "exdate": "「除了这几天」的例外列表",
+    "byyearday": "按一年中的第几天",
+    "byweekno": "按第几周",
+}
+
+
+class RecurrenceUnsupported(ValueError):
+    """这条重复规则我们不认识。**拒绝，不猜。**"""
+
+
+@dataclass(frozen=True)
+class RecurrenceRule:
+    """一条重复规则的最小描述。"""
+
+    freq: str
+    interval: int = 1
+    #: 每周重复时指定星期几，0=周一。空 = 跟着起始日那天。
+    byweekday: tuple[int, ...] = ()
+    #: 到这天为止（含）。``None`` = 无限重复。
+    until: date | None = None
+    #: 最多重复多少次。``None`` = 不限次数。
+    count: int | None = None
+
+    @classmethod
+    def parse(cls, raw: Mapping[str, Any]) -> "RecurrenceRule":
+        bad = [k for k in raw if k.lower() in UNSUPPORTED_KEYS]
+        if bad:
+            why = "、".join(UNSUPPORTED_KEYS[k.lower()] for k in bad)
+            raise RecurrenceUnsupported(
+                f"这条规则用到了{why}，我们不展开它。"
+                "算错重复日程的日期是那种「看起来完全正常」的错 —— "
+                "用户会准时出现在一个不存在的会议上。请宿主自己展开好再传进来"
+            )
+        freq = str(raw.get("freq", "")).lower()
+        if freq not in SUPPORTED_FREQ:
+            raise RecurrenceUnsupported(
+                f"freq={raw.get('freq')!r} 不在 {list(SUPPORTED_FREQ)} 里"
+            )
+        # 刻意不写 `raw.get("interval", 1) or 1` —— 那会把 interval=0
+        # 静默变成 1，正是"不许猜"要防的那种改写。
+        raw_interval = raw.get("interval")
+        interval = 1 if raw_interval is None else int(raw_interval)
+        if interval < 1:
+            raise RecurrenceUnsupported(
+                f"interval={interval} 必须 >= 1（0 或负数没有意义，"
+                "而把它当成 1 就是替上游改写了规则）"
+            )
+
+        until = raw.get("until")
+        if isinstance(until, datetime):
+            until = until.date()
+        elif isinstance(until, str):
+            until = date.fromisoformat(until[:10])
+
+        return cls(
+            freq=freq, interval=interval,
+            byweekday=tuple(int(d) for d in (raw.get("byweekday") or ())),
+            until=until,
+            count=int(raw["count"]) if raw.get("count") is not None else None,
+        )
+
+
+def _step(current: date, rule: RecurrenceRule) -> date:
+    if rule.freq == "daily":
+        return current + timedelta(days=rule.interval)
+    if rule.freq == "weekly":
+        return current + timedelta(weeks=rule.interval)
+    # monthly：同一天。**遇到没有那一天的月份就跳过**（1 月 31 日 → 2 月没有
+    # 31 号）。不做"退回月末"，那是另一种语义，各家日历还不一致。
+    y, m = current.year, current.month + rule.interval
+    y += (m - 1) // 12
+    m = (m - 1) % 12 + 1
+    try:
+        return current.replace(year=y, month=m)
+    except ValueError:
+        return date(y, m, 28) + timedelta(days=4)   # 落到下个月，下轮再跳
+
+
+def expand(
+    start: datetime, rule: RecurrenceRule, *,
+    window_start: date, window_end: date,
+    max_instances: int = MAX_INSTANCES,
+) -> list[datetime]:
+    """把一条重复规则在给定窗口内展开成具体的发生时刻。
+
+    **保留原始的时刻和时区** —— 只挪日期，不碰时分和 offset。
+    每周一早上十点的会，跨夏令时之后仍然是"本地时间早上十点"。
+    """
+    out: list[datetime] = []
+    if window_end < window_start:
+        return out
+
+    day = start.date()
+    emitted = 0
+    # 无限重复配上一个很远的窗口，光是走到窗口起点就可能要几万步。
+    # 步数上限按窗口跨度 + 已产出条数给，够用且不会失控。
+    budget = (window_end - window_start).days + max_instances * 2 + 366
+
+    weekdays = set(rule.byweekday) if rule.freq == "weekly" and rule.byweekday else None
+    # 「每两周的周一」要按【周】数间隔，不是按天。以起始日那一周的周一为基准，
+    # 只有相隔整数个 interval 周的那些周才算数 —— 按天走会把每周都算上。
+    week0 = start.date() - timedelta(days=start.date().weekday())
+
+    while budget > 0 and day <= window_end:
+        budget -= 1
+        if rule.until is not None and day > rule.until:
+            break
+        if rule.count is not None and emitted >= rule.count:
+            break
+
+        hit = day >= start.date()
+        if hit and weekdays is not None:
+            weeks_apart = ((day - timedelta(days=day.weekday())) - week0).days // 7
+            hit = day.weekday() in weekdays and weeks_apart % rule.interval == 0
+        if hit:
+            emitted += 1
+            if day >= window_start:
+                out.append(datetime.combine(day, start.timetz()))
+                if len(out) >= max_instances:
+                    break
+
+        day = (day + timedelta(days=1)) if weekdays is not None else _step(day, rule)
+
+    return out
+
+
+__all__ = [
+    "MAX_INSTANCES", "SUPPORTED_FREQ", "UNSUPPORTED_KEYS",
+    "RecurrenceUnsupported", "RecurrenceRule", "expand",
+]

perceptkit/processing/scheduled.py

@@ -0,0 +1,233 @@
+"""由时钟驱动的两种规则 —— 主管线跑不到它们。
+
+主管线是**数据驱动**的：有观测进来才跑。这对九种规则里的七种都对，
+但另外两种不行：
+
+    streak    "连续三天睡眠不足" —— 要读历史，而且【一天只该判一次】
+              前台每 30 秒一条观测，跟着观测跑就是一天几千次，
+              而这件事一天只可能变化一次。
+              → 挂在【某天的聚合算完】那一刻
+
+    absence   "你三天没记录体重了" —— **没有数据才该触发**
+              跟着观测跑的话，它永远等不到自己被调用的那一刻。
+              → 由定时器驱动
+
+**宿主不用为此多起一个东西。** 投递那条线本来就需要一个定时循环
+（``dispatch_pending`` 得有人定期调），这两个搭在同一个循环上就行。
+
+⚠️ 产品规范把 ``absence`` 列进了内置规则，但**整份文档没说它由谁驱动** ——
+其他八种都是"数据来了 → 判断"，只有它是"数据没来 → 判断"。这是规范的一处缺口。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime, timedelta
+from typing import Any, Callable, Mapping, Sequence
+
+from ..contracts.context import IngestContext
+from ..contracts.event import PerceptionEvent
+from ..contracts.records import StoredObservation
+from ..manifest.types import SignalDefinition
+from ..ports.storage import StoragePort
+from ..rules.types import EventDefinition, RuleResult
+from .dispatch import RuleOutcome, definitions_for_signal, evaluate_and_enqueue
+from .normalize import NormalizedObservation
+
+#: 算连续天数时最多往回看多少天。不设上限的话，一条"连续 N 天"的规则
+#: 会在每次日聚合时把整个历史读一遍。
+MAX_STREAK_LOOKBACK_DAYS = 90
+
+_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,
+}
+
+
+@dataclass
+class ScheduledOutcome:
+    events: list[PerceptionEvent] = field(default_factory=list)
+    misses: list[tuple[str, str | None]] = field(default_factory=list)
+
+
+def _daily_value(doc: Mapping[str, Any], field_key: str, strategy: str) -> float | None:
+    """从一天的聚合文档里取出那个字段的代表数字。
+
+    不同聚合方式的文档形状不一样 —— 这里只处理数值型的那几种，
+    其余返回 ``None``（比如"按状态分时长"就没有单一代表值）。
+    """
+    cell = doc.get(field_key)
+    if isinstance(cell, (int, float)) and not isinstance(cell, bool):
+        return float(cell)
+    if not isinstance(cell, Mapping):
+        return None
+    if strategy in ("daily_total", "cumulative"):
+        raw = cell.get("total")
+    elif strategy == "numeric_dist":
+        # 用平均值当代表：min/max 太容易被单次异常读数带偏。
+        if cell.get("count"):
+            raw = cell["sum"] / cell["count"]
+        else:
+            raw = None
+    else:
+        raw = cell.get("value")
+    return float(raw) if isinstance(raw, (int, float)) else None
+
+
+def streak_length(
+    storage: StoragePort,
+    definition: EventDefinition,
+    signal: SignalDefinition,
+    *,
+    subject_id: str,
+    through: date,
+    max_days: int = MAX_STREAK_LOOKBACK_DAYS,
+) -> int:
+    """从 ``through`` 往回数，连续多少天满足这条规则的**每天条件**。
+
+    **缺数据的那天直接断掉，不跳过。** "连续三天睡眠不足"里如果有一天没戴表，
+    那就不是连续三天 —— 把缺失当成"满足"或"跳过"都是在替用户编事实。
+    """
+    fd = signal.field_map().get(definition.field_name or "")
+    if fd is None:
+        return 0
+    op = _OPS.get(definition.operator or "lt")
+    threshold = definition.value
+    if op is None or not isinstance(threshold, (int, float)):
+        return 0
+
+    start = through - timedelta(days=max_days - 1)
+    by_day = {
+        a.local_date: a.typed_aggregate
+        for a in storage.get_aggregate(
+            subject_id=subject_id, signal=signal.key,
+            start_date=start, end_date=through, aggregation_kind="daily",
+        )
+    }
+
+    count = 0
+    day = through
+    while day >= start:
+        doc = by_day.get(day)
+        if doc is None:
+            break                      # 那天没数据 —— 连续断了
+        value = _daily_value(doc, definition.field_name or "", fd.aggregation_strategy)
+        if value is None or not op(value, float(threshold)):
+            break
+        count += 1
+        day -= timedelta(days=1)
+    return count
+
+
+def _fake_observation(
+    signal: SignalDefinition, *, subject_id: str, when: datetime, day: date,
+) -> NormalizedObservation:
+    """给 ``evaluate_and_enqueue`` 造一个载体。
+
+    定时求值没有真实观测（这正是它存在的理由），但事件仍然要落到某个
+    signal / 某一天上。造一条**不落库**的载体，只用来把上下文传下去。
+    """
+    stored = StoredObservation(
+        observation_id=f"scheduled:{signal.key}:{day.isoformat()}",
+        subject_id=subject_id, signal=signal.key, signal_schema_version=signal.schema_version,
+        source="scheduler", occurred_at=when, received_at=when,
+        availability="observed", effective_local_date=day, typed_value={},
+    )
+    return NormalizedObservation(
+        stored=stored, identity_digest=stored.observation_id,
+        fact_key=stored.observation_id, content_digest="",
+    )
+
+
+def evaluate_daily(
+    *,
+    storage: StoragePort,
+    subject_id: str,
+    local_date: date,
+    now: datetime,
+    signals: Mapping[str, SignalDefinition],
+    definitions: Sequence[EventDefinition],
+    extra_evaluators: Mapping[str, Callable[..., RuleResult]] | None = None,
+) -> ScheduledOutcome:
+    """某一天的聚合算完之后调一次，跑 ``streak`` 这类按天判的规则。
+
+    宿主在跨日时调用（每个 subject 一次），不要跟着观测跑。
+    """
+    outcome = ScheduledOutcome()
+    context = IngestContext(subject_id=subject_id, received_at=now)
+
+    for definition in definitions:
+        if definition.condition_type != "streak" or not definition.enabled:
+            continue
+        signal = signals.get(definition.signal)
+        if signal is None:
+            continue
+        length = streak_length(
+            storage, definition, signal, subject_id=subject_id, through=local_date,
+        )
+        item = _fake_observation(signal, subject_id=subject_id, when=now, day=local_date)
+        rules: RuleOutcome = evaluate_and_enqueue(
+            item, context=context, storage=storage, definitions=[definition],
+            extra_evaluators=extra_evaluators,
+            extra_context={"streak_length": length},
+            signal_definition=signal,
+        )
+        outcome.events.extend(rules.events)
+        outcome.misses.extend(rules.misses)
+    return outcome
+
+
+def evaluate_absence(
+    *,
+    storage: StoragePort,
+    subject_id: str,
+    now: datetime,
+    signals: Mapping[str, SignalDefinition],
+    definitions: Sequence[EventDefinition],
+    extra_evaluators: Mapping[str, Callable[..., RuleResult]] | None = None,
+) -> ScheduledOutcome:
+    """定时调，跑 ``absence``（该来的没来）这类规则。
+
+    **静默时长从当前值的观测时刻算起** —— 用当前值而不是翻观测明细，
+    因为明细可能已经按保留期清理掉了，而当前值一定还在。
+    """
+    outcome = ScheduledOutcome()
+    context = IngestContext(subject_id=subject_id, received_at=now)
+
+    for definition in definitions:
+        if definition.condition_type != "absence" or not definition.enabled:
+            continue
+        signal = signals.get(definition.signal)
+        if signal is None:
+            continue
+
+        projections = storage.get_current(
+            subject_id=subject_id, signals=[definition.signal]
+        ).get(definition.signal) or []
+        if not projections:
+            # 从来没有过数据。**不触发** —— "你三天没记录体重了"对一个
+            # 从没记过体重的用户来说是句莫名其妙的话。
+            outcome.misses.append((definition.definition_id, "这个信号从来没有过数据"))
+            continue
+
+        last = max(p.observed_at for p in projections)
+        silent = (now - last).total_seconds()
+        item = _fake_observation(
+            signal, subject_id=subject_id, when=now, day=now.date(),
+        )
+        rules = evaluate_and_enqueue(
+            item, context=context, storage=storage, definitions=[definition],
+            extra_evaluators=extra_evaluators,
+            extra_context={"silent_seconds": silent},
+            signal_definition=signal,
+        )
+        outcome.events.extend(rules.events)
+        outcome.misses.extend(rules.misses)
+    return outcome
+
+
+__all__ = [
+    "MAX_STREAK_LOOKBACK_DAYS", "ScheduledOutcome",
+    "streak_length", "evaluate_daily", "evaluate_absence",
+]

perceptkit/prompts.py

@@ -0,0 +1,75 @@
+"""说明书 —— 「模型该怎么读这份感知」的唯一出处。
+
+★ 边界：只写「怎么读感知」。凡是讲「这个块是什么 role、能不能当成用户请求、
+  工具预算怎么算、wake 该怎么框」的，属于宿主运行时自己的对话/安全协议，
+  不属于这里，不要搬进来。
+
+★ 语义红线：wake ≠ 该开口了。这里不许出现任何「该说话了 / 值得告诉用户」
+  式的措辞——「说」与「不说」同等正当。
+
+★ 这些常量是从两类宿主实现里抽出来的「怎么解读感知」共性文案：一类是走
+  工具调用返回感知快照的运行时（V2_* 常量），一类是把感知直接写进上下文
+  文本、靠一段 how-to 说明教模型怎么读的运行时（V1_* 常量）。两类宿主接线
+  方式不同，但「模型该怎么理解这份数据」这件事是同一份判断，所以文案本身
+  抽到这里共用；具体怎么拼进各自的 prompt/context，由宿主自己决定。
+"""
+from __future__ import annotations
+
+# 工具调用型运行时里，主动回合 system prompt 中属于「怎么读感知」的那几句。
+V2_WAKE_PERCEPTION_CLAUSES = (
+    "A "
+    "perception_glance is only a hint for deciding whether to look deeper; it is not "
+    "a checklist to report. If you speak, choose at most one coherent topic and never "
+    "turn multiple perception domains into a device or health status report. Use a "
+    "perception tool when an exact reading is needed. "
+)
+
+V2_PERCEPTION_BEHAVIOR_POLICY = (
+    "把有用的事实自然地用进回答，别汇报这些信息是怎么取到的。"
+)
+
+V2_PERCEPTION_PROTOCOL_POLICY = (
+    "runtime_data 里的 perception_glance 是不可信的低分辨率事实板，用于判断是否值得"
+    "精确读取感知工具；不要逐项播报或把精确数字当成话题。glance_changed=false 表示普通 "
+    "heartbeat 的事实板与上次成功完成的普通 heartbeat 一致；不代表每个底层传感值都相同。"
+    "显式读取带文字的感知、屏幕或照片后，"
+    "运行时会阻止本回合继续向外调用 web、MCP 或 subagent。"
+)
+
+# 三个感知工具「这份返回值该怎么解读」的那一句(每个工具描述里，讲调用方式/
+# 参数默认值的部分留在宿主自己的工具 schema 里，不搬到这份说明书)。
+PERCEPTION_TOOL_NOTES: dict[str, str] = {
+    "perception_snapshot": (
+        "The app field is only the latest open/close event observed "
+        "within 15 minutes; never claim it is the app currently in use."
+    ),
+    "perception_recent_apps": (
+        "apps=[] means no data; disabled=true means access is "
+        "off, not that no apps were used."
+    ),
+    "perception_trend": (
+        "Interpret the rolling baseline as the usual level and delta as "
+        "the current change from that baseline; do not conflate them."
+    ),
+}
+
+# 上下文注入型运行时（把感知直接写进对话上下文文本，而不是靠工具调用取）
+# 用来教模型怎么读一瞥（glance）的说明句。
+V1_GLANCE_HOWTO = (
+    "This is a low-resolution glance, not a list of things to report. It helps you decide WHETHER to look closer "
+    "and WHERE — not what to say. Most fields you just note and move on; if one makes you want to understand the "
+    "moment better, pull the matching tool for detail. Treat missing fields as unknown."
+)
+
+# 同一类运行时，教模型怎么读跨领域面板（board）的说明句。
+V1_BOARD_HOWTO = (
+    "Reading the board: each domain (location/media/app/health/weather/mood/reminders/calendar/photos/screen) "
+    "is laid out evenly — health is just one entry, not the headline. Pick at most 2-3 things that stand out "
+    "to you; you may combine across domains, and prefer lived, human context (music, place, an app, a photo, "
+    "an overdue reminder) over the raw figures. Do NOT recite exact numbers (minutes, degrees, counts, sleep "
+    "figures) — use them only to notice what's genuinely about the user; if a number actually matters, pull "
+    "the tool for it. novelty hints (new_artist / long_dwell) are light factual context, not a directive. "
+    "If signals lean low or vulnerable (late hour, sad music, poor sleep), be lighter, not heavier — don't "
+    "diagnose, don't stack worries; one warm, light touch is enough. If nothing stands out, staying quiet is "
+    "equally fine."
+)

perceptkit/queries/__init__.py

@@ -0,0 +1,32 @@
+"""读取侧 —— agent 主动来查的八个函数。
+
+和写入侧方向相反、共用同一份存储。**不是转发器**:里面装着 TTL 判定、
+趋势模型选择、缺数据显式化、隐私投影四样每个宿主都必须一样的逻辑。
+
+MCP 工具那层(工具名、描述、给谁开、返回怎么写)留在宿主 —— 全是产品决策。
+"""
+from __future__ import annotations
+
+from .api import (
+    DEFAULT_LIMIT,
+    MAX_LIMIT,
+    CurrentView,
+    DailyView,
+    get_current,
+    get_daily_aggregates,
+    get_last_known,
+    get_trend,
+    list_calendar_events,
+    list_events,
+    list_reminders,
+    list_timeline,
+    project,
+    visible_fields,
+)
+
+__all__ = [
+    "get_current", "get_last_known", "list_timeline", "get_daily_aggregates",
+    "get_trend", "list_calendar_events", "list_reminders", "list_events",
+    "CurrentView", "DailyView", "visible_fields", "project",
+    "DEFAULT_LIMIT", "MAX_LIMIT",
+]