patbond-ai/app/config.py

"""集中配置：全部旋钮从环境变量读，一处定义。

为什么不用 pydantic-settings：当前运行时依赖只有 httpx 一个，为十来个环境变量
引入一个框架不划算。需要嵌套配置或复杂校验时再换。

**凭证纪律**（ADR-021）：密钥只从环境变量读，**绝不写默认值**。缺失时
`from_env()` 不抛异常——服务仍可启动并提供健康检查，只在真正要调用厂商时才
响亮失败。这与 Java 侧 `JwtVerifier`/`ServiceTokenSigner` 的既有约定一致：
缺配置是服务端错误，不该伪装成上游故障，但也不该让整个进程起不来。
"""

from __future__ import annotations

import os
from dataclasses import dataclass, field

from app.providers.openai.client import DEFAULT_BASE_URL as OPENAI_DEFAULT_BASE_URL
from app.providers.volcengine.models import DEFAULT_BASE_URL


def _env(name: str, default: str = "") -> str:
    return os.environ.get(name, default).strip()


def _env_int(name: str, default: int) -> int:
    raw = _env(name)
    if not raw:
        return default
    try:
        return int(raw)
    except ValueError as exc:
        # 静默回落到默认值会让一次配置笔误变成难查的行为偏差。
        raise ValueError(f"环境变量 {name} 不是合法整数：{raw!r}") from exc


def _env_float(name: str, default: float) -> float:
    raw = _env(name)
    if not raw:
        return default
    try:
        return float(raw)
    except ValueError as exc:
        raise ValueError(f"环境变量 {name} 不是合法数字：{raw!r}") from exc


@dataclass(frozen=True)
class VolcengineSettings:
    """火山方舟（Ark）接入配置。

    :param api_key: `ARK_API_KEY`。**无默认值**，缺失时适配层在调用点报错。
    :param timeout_sec: 单次 HTTP 往返超时。**不是生成耗时**——提交与查询都是
        短请求（提交只入队即返回），把它调大成「等出图」会重新引入长连接占用与
        计费歧义，见 ADR-023 §4。
    :param video_model: 视频生成的默认模型 ID。仅作**兜底**：正常路径由 Java 侧
        从目录表的快照列传入，适配层不自行选模型（选型是目录的职责，且任务行里
        冻结的快照必须与实际调用的模型一致）。
    :param task_expiry_sec: 传给厂商的 `execution_expires_after`。厂商取值范围
        `[3600, 259200]`，默认 48 小时对交互式应用过长，故默认取下限 1 小时。
    """

    api_key: str = ""
    base_url: str = DEFAULT_BASE_URL
    timeout_sec: float = 10.0
    video_model: str = ""
    task_expiry_sec: int = 3600

    @classmethod
    def from_env(cls) -> VolcengineSettings:
        return cls(
            api_key=_env("ARK_API_KEY"),
            base_url=_env("ARK_BASE_URL", cls.base_url),
            timeout_sec=_env_float("ARK_TIMEOUT_SEC", cls.timeout_sec),
            video_model=_env("ARK_VIDEO_MODEL"),
            task_expiry_sec=_env_int("ARK_TASK_EXPIRY_SEC", cls.task_expiry_sec),
        )

    def __post_init__(self) -> None:
        # 厂商硬性区间。设成区间外的值会在提交时被厂商拒（InvalidParameter），
        # 那要花一次往返才知道，不如在启动时就说清楚。
        if not 3600 <= self.task_expiry_sec <= 259200:
            raise ValueError(
                f"ARK_TASK_EXPIRY_SEC 必须在 [3600, 259200] 之间（厂商限制），"
                f"当前 {self.task_expiry_sec}"
            )


@dataclass(frozen=True)
class OpenAiSettings:
    """OpenAI 图片接入配置。

    :param api_key: `OPENAI_API_KEY`。**无默认值**，缺失时该适配器不装配。
    :param timeout_sec: **这里确实是生成耗时的上限**，与火山那边不同——OpenAI 的
        图片接口是同步的，一次请求里等到图片生成完才返回。故默认值比火山的
        「短往返超时」大一个量级。
    :param image_model: 图片模型 ID，仅作兜底；正常由 Java 侧传入任务行的快照。
    :param max_concurrent: 同时执行的同步调用数上限。**同时也是对服务商并发和
        「同时有多少钱在花」的自我限制**——超出的提交排队而非一起打过去。
    :param completed_ttl_sec: 已完成任务在内存注册表里的保留时长。须大于 Java 侧
        最长的轮询间隔（当前阶梯最长 30 秒），否则结果会在被取走前被清理。
    """

    api_key: str = ""
    base_url: str = OPENAI_DEFAULT_BASE_URL
    timeout_sec: float = 180.0
    image_model: str = ""
    organization: str = ""
    max_concurrent: int = 4
    completed_ttl_sec: float = 900.0
    max_inflight: int = 256

    @classmethod
    def from_env(cls) -> OpenAiSettings:
        return cls(
            api_key=_env("OPENAI_API_KEY"),
            base_url=_env("OPENAI_BASE_URL", cls.base_url),
            timeout_sec=_env_float("OPENAI_TIMEOUT_SEC", cls.timeout_sec),
            image_model=_env("OPENAI_IMAGE_MODEL"),
            organization=_env("OPENAI_ORGANIZATION"),
            max_concurrent=_env_int("OPENAI_MAX_CONCURRENT", cls.max_concurrent),
            completed_ttl_sec=_env_float(
                "OPENAI_COMPLETED_TTL_SEC", cls.completed_ttl_sec
            ),
            max_inflight=_env_int("OPENAI_MAX_INFLIGHT", cls.max_inflight),
        )

    def __post_init__(self) -> None:
        if self.max_concurrent < 1:
            raise ValueError(
                f"OPENAI_MAX_CONCURRENT 必须 >= 1，当前 {self.max_concurrent}"
            )
        # 小于最长轮询间隔会让结果在被取走前就被清掉——那表现为「任务成功了但查
        # 不到」，极难查。
        if self.completed_ttl_sec < 60:
            raise ValueError(
                f"OPENAI_COMPLETED_TTL_SEC 不应小于 60 秒（须大于 Java 侧最长轮询"
                f"间隔，否则结果会在被取走前被清理），当前 {self.completed_ttl_sec}"
            )


@dataclass(frozen=True)
class ServiceAuthSettings:
    """校验 Java 侧服务身份 JWT 所需的配置（ADR-023 §5）。

    :param public_key: 与 `patbond-creation` 持有的私钥配对的 RS256 公钥。
        注意这是一对**独立于用户 token 的**密钥——理由见 ADR-023 §5。
    :param audience: 必须强制校验。缺了这一步，任何用同一密钥签出的 token 都能
        进来，而独立密钥对的意义正在于此。
    """

    public_key: str = ""
    issuer: str = "patbond-api"
    audience: str = "patbond-ai"
    required_type: str = "service"

    @classmethod
    def from_env(cls) -> ServiceAuthSettings:
        return cls(
            public_key=_env("PATBOND_SERVICE_JWT_PUBLIC_KEY"),
            issuer=_env("PATBOND_SERVICE_JWT_ISSUER", cls.issuer),
            audience=_env("PATBOND_SERVICE_JWT_AUDIENCE", cls.audience),
            required_type=_env("PATBOND_SERVICE_JWT_TYPE", cls.required_type),
        )


@dataclass(frozen=True)
class Settings:
    """本服务的全部配置。"""

    volcengine: VolcengineSettings = field(default_factory=VolcengineSettings)
    openai: OpenAiSettings = field(default_factory=OpenAiSettings)
    service_auth: ServiceAuthSettings = field(default_factory=ServiceAuthSettings)
    log_level: str = "INFO"

    @classmethod
    def from_env(cls) -> Settings:
        return cls(
            volcengine=VolcengineSettings.from_env(),
            openai=OpenAiSettings.from_env(),
            service_auth=ServiceAuthSettings.from_env(),
            log_level=_env("PATBOND_AI_LOG_LEVEL", cls.log_level).upper(),
        )