from __future__ import annotations

import logging
from typing import Any

logger = logging.getLogger(__name__)


def clamp(value: float, min_value: float, max_value: float) -> float:
    """
    将值裁剪到区间内，并对 NaN 做兜底。
    """

    if value != value:  # NaN
        return min_value
    return max(min_value, min(max_value, value))


def as_finite_float(value: Any, *, default: float) -> float:
    """
    将任意值尽量转为有限 float；失败则返回 default。
    """

    try:
        f = float(value)
    except Exception:
        return float(default)

    # NaN / inf 都视为不可用
    if f != f:
        return float(default)
    if f == float("inf") or f == float("-inf"):
        return float(default)
    return f


def pick_one_hot_key(one_hot: dict[str, Any] | None) -> str | None:
    """
    从稀疏 one-hot（{key: 1}）中取唯一 key。

    约定：
    - None / {} → 缺失，返回 None
    - 单 key → 返回该 key
    - 多 key → 取“字典序最小”的 key，并记录 debug 日志（避免静默歧义）
    """

    if not one_hot:
        return None

    keys = [k for k, v in one_hot.items() if v == 1 or v is True]
    if not keys:
        return None
    if len(keys) == 1:
        return keys[0]

    chosen = sorted(keys)[0]
    logger.debug("one-hot 出现多个 key=1，已按字典序选择：chosen=%s keys=%s", chosen, keys)
    return chosen

