from dataclasses import dataclass

# ==================== DQN超参数配置类 ====================
@dataclass
class DQNParams:
    """
    DQN 超参数配置类

    功能：统一管理DQN算法的所有超参数

    超参数说明：
    - learning_rate: 神经网络学习率，控制梯度下降的步长
    - buffer_size: 经验回放缓冲区大小，存储历史经验
    - learning_starts: 开始训练前先收集的经验数量（warm-up）
    - batch_size: 每次训练采样的batch大小
    - gamma: 折扣因子，权衡即时奖励和长期奖励
    - train_freq: 训练频率，每隔多少步训练一次
    - target_update_interval: 目标网络更新频率
    - tau: 软更新系数（soft update）
    - exploration_*: ε-贪心策略的探索率参数
    """
    # ========== 神经网络参数 ==========
    learning_rate: float = 1e-4
    # 学习率，控制神经网络权重更新的步长
    # 典型范围：1e-5 ~ 1e-3
    # 过大：训练不稳定；过小：收敛慢

    # ========== 经验回放参数 ==========
    buffer_size: int = 100000
    # 经验回放缓冲区大小（可存储的transition数量）
    # 作用：打破样本间的时间相关性，提高训练稳定性
    # 建议：至少存储几个完整episode的经验

    learning_starts: int = 10000
    # 开始训练前先收集的步数（预填充缓冲区）
    # 作用：确保缓冲区有足够的多样性样本再开始训练
    # 建议：设为buffer_size的10%-20%

    batch_size: int = 32
    # 每次训练从缓冲区采样的样本数量
    # 典型值：32, 64, 128, 256
    # 过大：显存占用高，训练慢；过小：梯度估计不准确

    # ========== 强化学习参数 ==========
    gamma: float = 0.95
    # 折扣因子（discount factor），γ ∈ [0, 1]
    # 作用：权衡即时奖励和长期奖励
    # γ=0：只考虑当前奖励（短视）
    # γ=1：完全考虑未来奖励（长视）
    # 通常设为0.9-0.99

    train_freq: int = 4
    # 训练频率：每收集多少步执行一次训练
    # 作用：平衡数据收集和网络更新
    # 典型值：1（每步训练）或4-16（批量训练）

    # ========== 目标网络参数 ==========
    target_update_interval: int = 1
    # 目标网络更新间隔（硬更新）
    # 作用：目标网络每隔多少次训练更新一次
    # 注：使用软更新(tau)时此参数通常设为1

    tau: float = 0.005
    # 软更新系数（soft update）
    # θ_target = τ×θ + (1-τ)×θ_target
    # τ=1：硬更新（完全复制）
    # τ<<1：软更新（平滑过渡，更稳定）
    # 典型值：0.001 - 0.01

    # ========== 探索策略参数（ε-greedy） ==========
    exploration_initial_eps: float = 1.0
    # 初始探索率 ε_0
    # ε=1：完全随机探索
    # ε=0：完全利用已学知识

    exploration_fraction: float = 0.3
    # 探索率衰减比例
    # 表示训练总步数的前30%进行ε衰减
    # 例：总共10万步，前3万步ε从1.0衰减到0.02

    exploration_final_eps: float = 0.02
    # 最终探索率 ε_final
    # 衰减结束后保持此值（保留小概率探索）
    # 典型值：0.01 - 0.05

    # ========== 日志参数 ==========
    remark: str = "default"
    # 实验备注，用于区分不同训练实验
    # 会自动添加到TensorBoard日志目录名中