Instagram Reels Commerce Attribution — Reels 商品发现链路归因与转化量化

"""
Instagram Reels Commerce Attribution — 多触点归因链路量化
基于 DV365 (arXiv: 2506.00450) + Amazon MTA (arXiv: 2508.08209)

依赖: numpy, dataclasses (标准库)
"""

from dataclasses import dataclass, field
import numpy as np
from datetime import datetime, timedelta


@dataclass
class ReelsTouchpoint:
    """单个 Reels 触点"""
    reel_id: str
    user_id: str
    action: str             # view / tag_click / profile_visit / link_click
    timestamp: float        # Unix timestamp
    video_completion_rate: float = 0.0
    product_tag_id: str = ""


@dataclass
class PurchaseEvent:
    """购买事件"""
    order_id: str
    user_id: str
    sku_id: str
    amount: float
    timestamp: float
    channel: str            # instagram / amazon_organic / direct


@dataclass
class ReelsAttributionResult:
    """Reels 归因结果"""
    reel_id: str
    attributed_orders: int
    attributed_gmv: float
    attributed_gmv_7d: float    # 7天窗口
    attributed_gmv_28d: float   # 28天窗口
    roas: float
    content_cost: float


class TimeDecayAttributor:
    """
    时间衰减多触点归因模型
    基于 Amazon MTA 的 Transformer 注意力归因方法简化版
    """

    def __init__(self, half_life_hours: float = 72.0,
                 attribution_window_days: int = 7):
        self.half_life = half_life_hours
        self.window = attribution_window_days * 24 * 3600  # 转秒

    def decay_weight(self, hours_before_purchase: float) -> float:
        """指数衰减权重"""
        lam = np.log(2) / self.half_life