自动化竞价与预算动态分配 — 跨平台广告Autobidding与ROI约束下的预算优化

"""
自动化竞价与预算动态分配系统
功能：KKT最优竞价 + PID预算控制 + 跨平台Markowitz分配
"""
import numpy as np
import pandas as pd
from dataclasses import dataclass, field
from typing import List, Dict, Optional
from scipy.optimize import minimize
import warnings
warnings.filterwarnings('ignore')


@dataclass
class KeywordBidContext:
    """关键词竞价上下文"""
    keyword: str
    historical_cvr: float          # 历史转化率
    avg_order_value: float         # 平均订单价值(USD)
    avg_cpc: float                 # 当前平均CPC(USD)
    weekly_impressions: int        # 周展现量
    campaign_id: str = "default"
    
    @property
    def conversion_value(self) -> float:
        """转化价值 = 转化率 × 订单价值"""
        return self.historical_cvr * self.avg_order_value


class KKTAutoBidder:
    """
    基于KKT条件的最优竞价系统
    实现 bid* = v / (1 + λ) 的动态竞价策略
    """
    
    def __init__(self, target_roas: float = 3.0, initial_lambda: float = 0.3):
        self.target_roas = target_roas
        self.lambda_val = initial_lambda  # 预算影子价格
        
        # PID控制参数
        self.pid_kp = 0.5   # 比例增益
        self.pid_ki = 0.1   # 积分增益
        self.pid_kd = 0.05  # 微分增益
        self._integral = 0.0
        self._prev_error = 0.0
    
    def compute_optimal_bid(self, keyword: KeywordBidContext) -> float:
        """
        计算最优出价
        bid* = conversion_value / (1 + λ)
        """
        optimal_bid = keyword.conversion_value / (1 + self.lambda_val)
        # 出价不低于$0.10，不超过转化价值的2倍（防止极端竞价）
        return np.clip(optimal_bid, 0.10, keyword.conversion_value * 2)
    
    def update_lambda_pid(self, budget_target: float, budget_consumed: float, dt: float = 1.0):
        """
        PID控制器更新λ
        超支 → 增大λ（压低出价）
        欠消耗 → 减小λ（提高出价）