让住宿推荐跟上用户下一步：用 Chronon 扩展实时序列推荐

A: 查看巴黎公寓 -> 查看巴黎公寓 -> 收藏巴黎公寓
B: 查看纽约酒店 -> 查看东京酒店 -> 查看巴黎公寓

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timezone
from math import exp
from typing import Iterable


@dataclass(frozen=True)
class Event:
    user_id: str
    item_id: str
    city: str
    event_type: str
    event_time: datetime


@dataclass(frozen=True)
class Candidate:
    item_id: str
    city: str
    price: int


def recent_sequence(
    events: Iterable[Event],
    user_id: str,
    now: datetime,
    limit: int = 5,
) -> list[Event]:
    """只返回 now 之前发生的事件，避免把未来事件带入特征。"""
    valid = [
        event
        for event in events
        if event.user_id == user_id and event.event_time <= now
    ]
    valid.sort(key=lambda event: event.event_time, reverse=True)
    return valid[:limit]


def score_candidate(candidate: Candidate, sequence: list[Event], now: datetime) -> float:
    """一个可解释的基线：最近行为、城市匹配和收藏行为都会增加分数。"""
    score = 0.0
    for position, event in enumerate(sequence):
        age_hours = max((now - event.event_time).total_seconds() / 3600, 0)
        recency = exp(-age_hours / 24)
        position_weight = 1.0 / (position + 1)

        if event.city == candidate.city:
            score += 2.0 * recency * position_weight
        if event.item_id == candidate.item_id:
            score += 3.0 * recency * position_weight
        if event.event_type == "save":
            score += 1.0 * recency * position_weight

    return round(score, 4)


def main() -> None:
    utc = timezone.utc
    events = [
        Event("u-1", "listing-ny-1", "New York", "view", datetime(2025, 1, 10, 8, tzinfo=utc)),
        Event("u-1", "listing-paris-1", "Paris", "view", datetime(2025, 1, 10, 9, tzinfo=utc)),
        Event("u-1", "listing-paris-2", "Paris", "save", datetime(2025, 1, 10, 9, 30, tzinfo=utc)),
        # 这条事件发生在 now 之后，不能进入当前请求的特征。
        Event("u-1", "listing-tokyo-1", "Tokyo", "view", datetime(2025, 1, 10, 11, tzinfo=utc)),
    ]
    candidates = [
        Candidate("listing-paris-2", "Paris", 180),
        Candidate("listing-ny-1", "New York", 150),
        Candidate("listing-tokyo-1", "Tokyo", 130),
    ]

    now = datetime(2025, 1, 10, 10, tzinfo=utc)
    sequence = recent_sequence(events, "u-1", now)
    ranked = sorted(
        ((candidate, score_candidate(candidate, sequence, now)) for candidate in candidates),
        key=lambda pair: pair[1],
        reverse=True,
    )

    print("sequence:")
    for event in sequence:
        print(f"  {event.event_time.isoformat()} {event.event_type} {event.city} {event.item_id}")

    print("\\nranking:")
    for candidate, score in ranked:
        print(f"  {candidate.item_id:18} {candidate.city:10} score={score}")


if __name__ == "__main__":
    main()