kd-engine 1.0.0__py3-none-any.whl

ytk/config.py

@@ -0,0 +1,757 @@
+"""Application settings (T43.1) — legacy-compatible plus v2 platform config.
+
+Priority (highest first), as frozen in contracts-v2 §1.7:
+
+1. explicit CLI arguments (``overrides=`` on :meth:`AppSettings.load`),
+2. platform-level / v2 environment variables (``YTK_DOUYIN_COOKIES_FILE``,
+   ``YTK_ASR_BACKEND``, ``YTK_MAX_MEDIA_MB`` …),
+3. an explicit TOML config file (``--config``, or ``$YTK_CONFIG``),
+4. the legacy global environment variables (``YTK_MINIMAX_API_KEY`` …),
+5. field defaults.
+
+Only keys that are actually present in a higher layer are applied, so an
+object default can never overwrite a user-provided value (explicit-only
+mapping).  ``AppSettings()`` keeps its historical behaviour: field defaults
+overridden by the environment.
+
+Platform isolation is deliberate: the legacy global YouTube cookie
+(``YTK_YT_DLP_COOKIES_FILE``) and transcript proxy are only inherited by the
+``youtube`` platform.  TikTok/Douyin/Bilibili/Xiaohongshu must configure their
+own ``[platforms.<name>] cookies_file`` / ``proxy`` (or platform env vars).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+import shutil
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, ClassVar, Literal
+from urllib.parse import urlsplit
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator, model_validator
+
+from ytk.errors import UserFacingError
+from ytk.ingestion.providers.transcript_api import DEFAULT_LANG_PRIORITY
+from ytk.models.source import SUPPORTED_PLATFORMS, Platform
+
+LOGGER = logging.getLogger(__name__)
+
+TranscriptProxyMode = Literal["generic", "webshare"]
+AsrBackend = Literal["auto", "whisper_cpp", "faster_whisper"]
+CloudKind = Literal["text", "media"]
+
+NO_DOTENV_ENV_VAR = "YTK_NO_DOTENV"
+CONFIG_PATH_ENV_VAR = "YTK_CONFIG"
+DEFAULT_OCR_MODEL_DIR = str(Path.home() / ".cache" / "ytk-models" / "rapidocr" / "models")
+_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
+
+
+class ConfigFileError(UserFacingError):
+    """The explicit TOML config file is missing, malformed or has unknown keys."""
+
+
+def resolve_credential_ref(
+    reference: str | None, *, environ: Mapping[str, str] | None = None
+) -> str | None:
+    """Resolve an explicit ``env:NAME`` reference without reading any file.
+
+    Error messages deliberately exclude both the reference and its value.
+    Resolve only the chosen credential, after per-request overrides.
+    """
+    if reference is None:
+        return None
+    if not isinstance(reference, str) or re.fullmatch(r"env:[A-Za-z_][A-Za-z0-9_]*", reference) is None:
+        raise ConfigFileError("credential_ref must name an environment variable using the env scheme")
+    source = os.environ if environ is None else environ
+    raw = source.get(reference[4:])
+    if not isinstance(raw, str) or not raw.strip():
+        raise ConfigFileError("credential_ref environment variable is missing or empty")
+    value = raw.strip()
+    if any(ord(char) < 33 or ord(char) > 126 for char in value) or "\r" in raw or "\n" in raw:
+        raise ConfigFileError("credential_ref must resolve to a single HTTP token")
+    return value
+
+
+def _env_flag(raw: str | None) -> bool:
+    return str(raw or "").strip().lower() in _TRUE_VALUES
+
+
+def _comma_tuple(raw: str | None) -> tuple[str, ...]:
+    return tuple(item.strip() for item in str(raw or "").split(",") if item.strip())
+
+
+def _safe_int(raw: str | None, default: int) -> int:
+    try:
+        return int(str(raw).strip()) if raw not in (None, "") else default
+    except (TypeError, ValueError):
+        LOGGER.warning("ignoring invalid integer environment value %r", raw)
+        return default
+
+
+def _safe_float(raw: str | None, default: float) -> float:
+    try:
+        return float(str(raw).strip()) if raw not in (None, "") else default
+    except (TypeError, ValueError):
+        LOGGER.warning("ignoring invalid float environment value %r", raw)
+        return default
+
+
+def dotenv_disabled(environ: dict[str, str] | os._Environ[str] | None = None) -> bool:
+    """True when ``YTK_NO_DOTENV`` disables reading the project ``.env``."""
+    source = os.environ if environ is None else environ
+    return _env_flag(source.get(NO_DOTENV_ENV_VAR))
+
+
+class AppSettings(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    # ------------------------------------------------------------------ legacy
+    _ENV_MAP: ClassVar[dict[str, str]] = {
+        "YTK_DEBUG": "debug",
+        "YTK_PROXY_MODE": "transcript_proxy_mode",
+        "YTK_HTTP_PROXY_URL": "transcript_http_proxy_url",
+        "YTK_HTTPS_PROXY_URL": "transcript_https_proxy_url",
+        "YTK_WEBSHARE_USERNAME": "webshare_proxy_username",
+        "YTK_WEBSHARE_PASSWORD": "webshare_proxy_password",
+        "YTK_WEBSHARE_REGIONS": "webshare_proxy_regions",
+        "YTK_WHISPER_CPP_BINARY": "whisper_cpp_binary",
+        "YTK_WHISPER_CPP_MODEL": "whisper_cpp_model",
+        "YTK_WHISPER_CPP_LANGUAGE": "whisper_cpp_language",
+        "YTK_FASTER_WHISPER_MODEL": "faster_whisper_model",
+        "YTK_FFMPEG_BINARY": "ffmpeg_binary",
+        "YTK_YT_DLP_BINARY": "yt_dlp_binary",
+        "YTK_YT_DLP_COOKIES_FILE": "yt_dlp_cookies_file",
+        "YTK_YT_DLP_COOKIES_FROM_BROWSER": "yt_dlp_cookies_from_browser",
+        "YTK_TRANSCRIPT_LANGUAGES": "transcript_languages",
+        "YTK_SENTENCE_TRANSFORMER_MODEL": "sentence_transformer_model",
+        "YTK_MINIMAX_API_KEY": "minimax_api_key",
+        "YTK_MINIMAX_REGION": "minimax_region",
+        "YTK_MINIMAX_MODEL": "minimax_model",
+        "YTK_MINIMAX_MAX_TOKENS": "minimax_max_tokens",
+        "YTK_MINIMAX_VIDEO_DETAIL": "minimax_video_detail",
+        "YTK_MINIMAX_VIDEO_FPS": "minimax_video_fps",
+        "YTK_MINIMAX_MAX_LONG_SIDE_PIXEL": "minimax_max_long_side_pixel",
+        "YTK_MINIMAX_MAX_VIDEO_MB": "minimax_max_video_mb",
+        "YTK_TRANSCRIPT_CACHE_ENABLED": "transcript_cache_enabled",
+        "YTK_TRANSCRIPT_CACHE_DIR": "transcript_cache_dir",
+        "YTK_DOC_LANGUAGE": "doc_language",
+        "YTK_KNOWLEDGE_DOC_TIMEOUT": "knowledge_doc_timeout",
+        "YTK_KNOWLEDGE_DOC_MAX_TOKENS": "knowledge_doc_max_tokens",
+    }
+    _BOOL_ENV_FIELDS: ClassVar[frozenset[str]] = frozenset(
+        {"debug", "transcript_cache_enabled"}
+    )
+    _TUPLE_ENV_FIELDS: ClassVar[frozenset[str]] = frozenset(
+        {"webshare_proxy_regions", "transcript_languages"}
+    )
+    _INT_ENV_FIELDS: ClassVar[frozenset[str]] = frozenset(
+        {
+            "minimax_max_tokens",
+            "minimax_max_long_side_pixel",
+            "minimax_max_video_mb",
+            "knowledge_doc_max_tokens",
+        }
+    )
+    _FLOAT_ENV_FIELDS: ClassVar[frozenset[str]] = frozenset(
+        {"minimax_video_fps", "knowledge_doc_timeout"}
+    )
+
+    # ---------------------------------------------------------------- defaults
+    debug: bool = False
+    transcript_proxy_mode: TranscriptProxyMode | None = None
+    transcript_http_proxy_url: str | None = None
+    transcript_https_proxy_url: str | None = None
+    webshare_proxy_username: str | None = None
+    webshare_proxy_password: str | None = None
+    webshare_proxy_regions: tuple[str, ...] | None = None
+    whisper_cpp_binary: str | None = None
+    whisper_cpp_model: str | None = None
+    whisper_cpp_language: str = "auto"
+    faster_whisper_model: str | None = "base.en"
+    ffmpeg_binary: str = "ffmpeg"
+    #: Empty means "no standalone CLI": consumers run ``<sys.executable> -m yt_dlp``.
+    yt_dlp_binary: str = ""
+    yt_dlp_cookies_file: str | None = None
+    yt_dlp_cookies_from_browser: str | None = None
+    transcript_languages: tuple[str, ...] = tuple(DEFAULT_LANG_PRIORITY)
+    transcript_cache_enabled: bool = True
+    transcript_cache_dir: str | None = None
+    sentence_transformer_model: str = "sentence-transformers/all-MiniLM-L6-v2"
+    minimax_api_key: str | None = None
+    minimax_region: Literal["cn", "global"] = "cn"
+    minimax_model: str = "MiniMax-M3"
+    minimax_max_tokens: int = 16384
+    minimax_video_detail: Literal["low", "default", "high"] = "low"
+    minimax_video_fps: float = 0.2
+    minimax_max_long_side_pixel: int = 640
+    minimax_max_video_mb: int = 512
+    doc_language: Literal["zh", "en", "auto"] | None = None
+    knowledge_doc_timeout: float = 300.0
+    knowledge_doc_max_tokens: int = 16384
+
+    # --------------------------------------------------------------- platforms
+    #: Platforms enabled for this machine.  Everything defaults to enabled; a
+    #: missing sidecar still reports as ``not_configured`` (never as verified).
+    platforms_enabled: tuple[Platform, ...] = (
+        "youtube",
+        "tiktok",
+        "douyin",
+        "bilibili",
+        "xiaohongshu",
+    )
+    dtk_base_url: str | None = None
+    dtk_token: str | None = None
+    dtk_credential_ref: str | None = None
+    xhs_base_url: str | None = None
+    xhs_credential_ref: str | None = None
+
+    # Per-platform credentials/network.  The legacy global YouTube cookie and
+    # transcript proxy are only inherited by YouTube (see helpers below).
+    youtube_cookies_file: str | None = None
+    tiktok_cookies_file: str | None = None
+    douyin_cookies_file: str | None = None
+    bilibili_cookies_file: str | None = None
+    xiaohongshu_cookies_file: str | None = None
+    youtube_proxy: str | None = None
+    tiktok_proxy: str | None = None
+    douyin_proxy: str | None = None
+    bilibili_proxy: str | None = None
+    xiaohongshu_proxy: str | None = None
+
+    # --------------------------------------------------------- ASR / OCR models
+    asr_backend: AsrBackend = "auto"
+    asr_model: str | None = None
+    asr_language: str | None = None
+    asr_beam_size: int = Field(default=5, ge=1, le=20)
+    asr_initial_prompt: str | None = Field(default=None, max_length=2000)
+    asr_hotwords: str | None = Field(default=None, max_length=1000)
+    asr_word_timestamps: bool = True
+    ocr_enabled: bool = False
+    ocr_model_dir: str = Field(default_factory=lambda: DEFAULT_OCR_MODEL_DIR)
+
+    # ----------------------------------------------------------------- budgets
+    max_media_mb: int = 512
+    max_duration_s: float | None = Field(default=None, gt=0, allow_inf_nan=False)
+    frame_budget: int = 24
+    #: Wall-clock budget for one task, local ASR included. Local recognition
+    #: scales with audio length (a 46-minute recording needs ~45 minutes of
+    #: ASR on this class of machine), so a 15-minute default killed real long
+    #: videos mid-run. This is a floor that fits ordinary media, not a promise
+    #: about very long recordings: raise YTK_TASK_DEADLINE_S for those.
+    task_deadline_s: float = Field(default=3600.0, gt=0, allow_inf_nan=False)
+    concurrency: int = 2
+
+    # ------------------------------------------------------------------- cloud
+    cloud_text_enabled: bool = False
+    cloud_media_enabled: bool = False
+
+    # ------------------------------------------------------------------- cache
+    cache_dir: str | None = None
+
+    # -------------------------------------------------------------- validation
+    @field_validator("asr_language", mode="before")
+    @classmethod
+    def _normalize_asr_language(cls, value: Any) -> str | None:
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            raise ValueError("asr_language must be a language code such as zh or en, or auto")
+        language = value.strip().lower()
+        if language in {"", "auto"}:
+            return None
+        if re.fullmatch(r"[a-z]{2,3}", language) is None:
+            raise ValueError("asr_language must be a language code such as zh or en, or auto")
+        return language
+
+    @model_validator(mode="after")
+    def _validate_v2_fields(self) -> AppSettings:
+        unknown = [value for value in self.platforms_enabled if value not in SUPPORTED_PLATFORMS]
+        if unknown:
+            raise ValueError(f"unknown enabled platform(s): {sorted(set(unknown))}")
+        # de-duplicate but keep the canonical platform order
+        self.platforms_enabled = tuple(
+            value for value in SUPPORTED_PLATFORMS if value in set(self.platforms_enabled)
+        )
+        if self.max_media_mb < 0:
+            raise ValueError("max_media_mb must be >= 0")
+        if self.frame_budget < 0:
+            raise ValueError("frame_budget must be >= 0")
+        if self.concurrency < 1:
+            raise ValueError("concurrency must be >= 1")
+        if self.task_deadline_s <= 0:
+            raise ValueError("task_deadline_s must be > 0")
+        return self
+
+    # ------------------------------------------------------------- env loading
+    @model_validator(mode="before")
+    @classmethod
+    def _from_env(cls, values: Any, info: ValidationInfo) -> Any:
+        """Historical behaviour: ``AppSettings()`` reads the legacy env only.
+
+        v2 platform/backend env variables and TOML are applied by
+        :meth:`load`; instantiating ``AppSettings()`` directly keeps the exact
+        pre-v2 semantics (defaults + the historical ``YTK_*`` variables) so
+        existing call sites and diagnostics do not change meaning.
+        """
+        merged: dict[str, Any] = {} if not isinstance(values, dict) else dict(values)
+        if info.context and info.context.get("environment_loaded"):
+            return merged
+        for field_name, value in _legacy_env_values(os.environ).items():
+            merged.setdefault(field_name, value)
+        return merged
+
+    # ---------------------------------------------------------------- loading
+    @classmethod
+    def load(
+        cls,
+        *,
+        config_path: Path | str | None = None,
+        overrides: dict[str, Any] | None = None,
+        environ: dict[str, str] | os._Environ[str] | None = None,
+    ) -> AppSettings:
+        """Build settings with the frozen priority order.
+
+        Only explicitly provided keys are applied at each layer; defaults never
+        overwrite a user-provided value.
+        """
+        env = os.environ if environ is None else environ
+        explicit = {key: value for key, value in (overrides or {}).items() if value is not None}
+        values: dict[str, Any] = {}
+        values.update(_legacy_env_values(env))  # tier 4
+
+        toml_platform_enable: dict[str, bool] = {}
+        resolved_config = config_path if config_path is not None else env.get(CONFIG_PATH_ENV_VAR)
+        if resolved_config:
+            toml_values, toml_platform_enable = load_config_file(resolved_config)
+            values.update(toml_values)  # tier 3
+
+        v2_values, v2_platform_enable = _v2_env_values_split(env)
+        values.update(v2_values)  # tier 2
+
+        values.update(explicit)  # tier 1
+
+        values["platforms_enabled"] = _resolve_platforms_enabled(
+            explicit.get("platforms_enabled"),
+            values.get("platforms_enabled"),
+            env,
+            toml_enable=toml_platform_enable,
+            env_enable=v2_platform_enable,
+        )
+        return cls.model_validate(values, context={"environment_loaded": True})
+
+    # -------------------------------------------------------------- helpers
+    @property
+    def platforms_enabled_set(self) -> frozenset[Platform]:
+        return frozenset(self.platforms_enabled)
+
+    def is_platform_enabled(self, platform: Platform) -> bool:
+        return platform in self.platforms_enabled_set
+
+    def cookies_file_for(self, platform: Platform) -> str | None:
+        """Per-platform cookie jar; the legacy global cookie is YouTube-only."""
+        if platform == "youtube":
+            return self.youtube_cookies_file or self.yt_dlp_cookies_file
+        return getattr(self, f"{platform}_cookies_file", None)
+
+    def cookies_from_browser_for(self, platform: Platform) -> str | None:
+        if platform == "youtube":
+            return self.yt_dlp_cookies_from_browser
+        return None
+
+    def proxy_for(self, platform: Platform) -> str | None:
+        """Per-platform proxy; legacy transcript proxy is YouTube-only."""
+        if platform == "youtube":
+            return (
+                self.youtube_proxy
+                or self.transcript_https_proxy_url
+                or self.transcript_http_proxy_url
+            )
+        return getattr(self, f"{platform}_proxy", None)
+
+    def base_url_for(self, platform: Platform) -> str | None:
+        if platform == "douyin":
+            return self.dtk_base_url
+        if platform == "xiaohongshu":
+            return self.xhs_base_url
+        return None
+
+    def credential_ref_for(self, platform: Platform) -> str | None:
+        if platform == "douyin":
+            return self.dtk_credential_ref
+        if platform == "xiaohongshu":
+            return self.xhs_credential_ref
+        return None
+
+    def resolved_ocr_model_dir(self) -> Path:
+        return Path(self.ocr_model_dir).expanduser()
+
+    def ytdlp_command(self) -> list[str]:
+        """Command prefix for yt-dlp: explicit binary, else ``python -m yt_dlp``."""
+        if self.yt_dlp_binary:
+            resolved = shutil.which(self.yt_dlp_binary) or self.yt_dlp_binary
+            return [resolved]
+        return [sys.executable, "-m", "yt_dlp"]
+
+    def cloud_allowed(self, platform: Platform, kind: CloudKind) -> bool:
+        """Cloud use is opt-in; legacy YouTube consent is honoured for YouTube only."""
+        explicit = (
+            self.cloud_text_enabled if kind == "text" else self.cloud_media_enabled
+        )
+        if f"cloud_{kind}_enabled" in self.model_fields_set:
+            return bool(explicit)
+        legacy_youtube_consent = platform == "youtube" and bool(self.minimax_api_key)
+        return bool(explicit or legacy_youtube_consent)
+
+    def redacted(self) -> dict[str, Any]:
+        """Credential-free settings view safe for logs/diagnostics/JSON output."""
+        from ytk.logging import redact_text
+
+        credential_fields = {
+            "minimax_api_key",
+            "dtk_token",
+            "webshare_proxy_username",
+            "webshare_proxy_password",
+        }
+        cookie_fields = {name for name in _field_names() if name.endswith("_cookies_file")}
+        proxy_fields = {
+            name for name in _field_names() if name.endswith("_proxy") or "proxy_url" in name
+        }
+        view: dict[str, Any] = {}
+        for name in _field_names():
+            value = getattr(self, name)
+            if name in credential_fields or name in cookie_fields or name in {"asr_initial_prompt", "asr_hotwords"}:
+                view[name] = "<configured>" if value else None
+            elif name in proxy_fields:
+                view[name] = (urlsplit(str(value)).hostname or "<configured>") if value else None
+            elif isinstance(value, tuple):
+                view[name] = list(value)
+            elif isinstance(value, str):
+                view[name] = redact_text(value)
+            else:
+                view[name] = value
+        return view
+
+
+def _field_names() -> tuple[str, ...]:
+    return tuple(AppSettings.model_fields)
+
+
+# --------------------------------------------------------------------------- #
+# TOML config file
+# --------------------------------------------------------------------------- #
+_PLATFORM_FIELD_TEMPLATES: dict[str, str] = {
+    "cookies_file": "{platform}_cookies_file",
+    "proxy": "{platform}_proxy",
+}
+_SERVICE_BASE_URL_FIELD: dict[str, str] = {
+    "douyin": "dtk_base_url",
+    "xiaohongshu": "xhs_base_url",
+}
+_SERVICE_TOKEN_FIELD: dict[str, str | None] = {
+    "douyin": "dtk_token",
+    "xiaohongshu": None,
+}
+_SERVICE_CRED_FIELD: dict[str, str] = {
+    "douyin": "dtk_credential_ref",
+    "xiaohongshu": "xhs_credential_ref",
+}
+_TOP_LEVEL_GROUPS: dict[str, dict[str, str]] = {
+    "asr": {
+        "backend": "asr_backend", "model": "asr_model", "language": "asr_language",
+        "beam_size": "asr_beam_size", "initial_prompt": "asr_initial_prompt",
+        "hotwords": "asr_hotwords", "word_timestamps": "asr_word_timestamps",
+    },
+    "ocr": {"enabled": "ocr_enabled", "model_dir": "ocr_model_dir"},
+    "budgets": {
+        "max_media_mb": "max_media_mb",
+        "max_duration_s": "max_duration_s",
+        "frame_budget": "frame_budget",
+        "task_deadline_s": "task_deadline_s",
+        "concurrency": "concurrency",
+    },
+    "cloud": {"text_enabled": "cloud_text_enabled", "media_enabled": "cloud_media_enabled"},
+    "cache": {"dir": "cache_dir"},
+}
+_PLATFORM_ENABLE_KEY = "enabled"
+
+
+def load_config_file(
+    path: Path | str,
+) -> tuple[dict[str, Any], dict[str, bool]]:
+    """Load an explicit TOML config file into field overrides + platform flags.
+
+    Only explicitly present keys are returned.  Unknown keys/sections are a
+    clear error instead of being silently ignored (config typos must not look
+    like working settings).
+    """
+    import tomllib
+
+    target = Path(path).expanduser()
+    try:
+        payload = tomllib.loads(target.read_text(encoding="utf-8"))
+    except FileNotFoundError as exc:
+        raise ConfigFileError(f"config file not found: {target}") from exc
+    except OSError as exc:
+        raise ConfigFileError(f"cannot read config file {target}: {exc}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigFileError(f"invalid TOML in {target}: {exc}") from exc
+
+    known_fields = set(AppSettings.model_fields)
+    values: dict[str, Any] = {}
+    platform_enable: dict[str, bool] = {}
+    unknown: list[str] = []
+
+    def _assign(key: str, value: Any, context: str) -> None:
+        if key == "platforms_enabled":
+            values[key] = _coerce_platforms(value, context)
+            return
+        if key not in known_fields:
+            unknown.append(context)
+            return
+        values[key] = value
+
+    for key, value in payload.items():
+        if key == "platforms":
+            if not isinstance(value, dict):
+                raise ConfigFileError("[platforms] must be a table")
+            for platform, section in value.items():
+                if platform not in SUPPORTED_PLATFORMS:
+                    raise ConfigFileError(f"unknown platform in config: [platforms.{platform}]")
+                if not isinstance(section, dict):
+                    raise ConfigFileError(f"[platforms.{platform}] must be a table")
+                for section_key, section_value in section.items():
+                    if section_key == _PLATFORM_ENABLE_KEY:
+                        if not isinstance(section_value, bool):
+                            raise ConfigFileError(
+                                f"platforms.{platform}.enabled must be a boolean"
+                            )
+                        platform_enable[platform] = section_value
+                        continue
+                    template = _PLATFORM_FIELD_TEMPLATES.get(section_key)
+                    if template is not None:
+                        _assign(
+                            template.format(platform=platform),
+                            section_value,
+                            f"platforms.{platform}.{section_key}",
+                        )
+                        continue
+                    if section_key == "base_url" and platform in _SERVICE_BASE_URL_FIELD:
+                        _assign(
+                            _SERVICE_BASE_URL_FIELD[platform],
+                            section_value,
+                            f"platforms.{platform}.base_url",
+                        )
+                        continue
+                    token_field = _SERVICE_TOKEN_FIELD.get(platform)
+                    if section_key == "token" and token_field:
+                        _assign(token_field, section_value, f"platforms.{platform}.token")
+                        continue
+                    if section_key == "credential_ref" and platform in _SERVICE_CRED_FIELD:
+                        _assign(
+                            _SERVICE_CRED_FIELD[platform],
+                            section_value,
+                            f"platforms.{platform}.credential_ref",
+                        )
+                        continue
+                    unknown.append(f"platforms.{platform}.{section_key}")
+            continue
+        group = _TOP_LEVEL_GROUPS.get(key)
+        if group is not None:
+            if not isinstance(value, dict):
+                raise ConfigFileError(f"[{key}] must be a table")
+            for section_key, section_value in value.items():
+                field = group.get(section_key)
+                if field is None:
+                    unknown.append(f"{key}.{section_key}")
+                    continue
+                _assign(field, section_value, f"{key}.{section_key}")
+            continue
+        _assign(key, value, key)
+
+    if unknown:
+        raise ConfigFileError(
+            "unknown config key(s): "
+            + ", ".join(sorted(unknown))
+            + ". See docs/implementation/five-platform/infra-cli.md for the accepted schema."
+        )
+    return values, platform_enable
+
+
+def _coerce_platforms(value: Any, context: str) -> tuple[str, ...]:
+    if isinstance(value, str):
+        if value.strip().lower() in {"all", "*"}:
+            return tuple(SUPPORTED_PLATFORMS)
+        items = _comma_tuple(value)
+    elif isinstance(value, (list, tuple)):
+        items = tuple(str(item).strip() for item in value if str(item).strip())
+    else:
+        raise ConfigFileError(f"{context} must be a list of platform names")
+    unknown = [item for item in items if item not in SUPPORTED_PLATFORMS]
+    if unknown:
+        raise ConfigFileError(f"{context} contains unknown platform(s): {sorted(set(unknown))}")
+    return tuple(item for item in SUPPORTED_PLATFORMS if item in set(items))
+
+
+# --------------------------------------------------------------------------- #
+# Environment parsing
+# --------------------------------------------------------------------------- #
+#: v2 environment variables (tier 2).  Applied in order, so platform-specific
+#: aliases can override the generic names for their platform.
+_V2_ENV_MAP: tuple[tuple[str, str], ...] = (
+    ("YTK_DTK_BASE_URL", "dtk_base_url"),
+    ("YTK_DTK_TOKEN", "dtk_token"),
+    ("YTK_DTK_CREDENTIAL_REF", "dtk_credential_ref"),
+    ("YTK_XHS_BASE_URL", "xhs_base_url"),
+    ("YTK_XHS_CREDENTIAL_REF", "xhs_credential_ref"),
+    ("YTK_ASR_BACKEND", "asr_backend"),
+    ("YTK_ASR_MODEL", "asr_model"),
+    ("YTK_ASR_LANGUAGE", "asr_language"),
+    ("YTK_ASR_BEAM_SIZE", "asr_beam_size"),
+    ("YTK_ASR_INITIAL_PROMPT", "asr_initial_prompt"),
+    ("YTK_ASR_HOTWORDS", "asr_hotwords"),
+    ("YTK_ASR_WORD_TIMESTAMPS", "asr_word_timestamps"),
+    ("YTK_OCR_ENABLED", "ocr_enabled"),
+    ("YTK_OCR_MODEL_DIR", "ocr_model_dir"),
+    ("YTK_MAX_MEDIA_MB", "max_media_mb"),
+    ("YTK_MAX_DURATION_S", "max_duration_s"),
+    ("YTK_FRAME_BUDGET", "frame_budget"),
+    ("YTK_TASK_DEADLINE_S", "task_deadline_s"),
+    ("YTK_CONCURRENCY", "concurrency"),
+    ("YTK_CLOUD_TEXT_ENABLED", "cloud_text_enabled"),
+    ("YTK_CLOUD_MEDIA_ENABLED", "cloud_media_enabled"),
+    ("YTK_CACHE_DIR", "cache_dir"),
+    ("YTK_V2_CACHE_DIR", "cache_dir"),
+    # platform-level aliases (contracts-v2 §1.7)
+    ("YTK_YOUTUBE_COOKIES_FILE", "youtube_cookies_file"),
+    ("YTK_TIKTOK_COOKIES_FILE", "tiktok_cookies_file"),
+    ("YTK_DOUYIN_COOKIES_FILE", "douyin_cookies_file"),
+    ("YTK_BILIBILI_COOKIES_FILE", "bilibili_cookies_file"),
+    ("YTK_XIAOHONGSHU_COOKIES_FILE", "xiaohongshu_cookies_file"),
+    ("YTK_YOUTUBE_PROXY", "youtube_proxy"),
+    ("YTK_TIKTOK_PROXY", "tiktok_proxy"),
+    ("YTK_DOUYIN_PROXY", "douyin_proxy"),
+    ("YTK_BILIBILI_PROXY", "bilibili_proxy"),
+    ("YTK_XIAOHONGSHU_PROXY", "xiaohongshu_proxy"),
+    ("YTK_DOUYIN_BASE_URL", "dtk_base_url"),
+    ("YTK_DOUYIN_TOKEN", "dtk_token"),
+)
+
+_V2_BOOL_FIELDS: frozenset[str] = frozenset(
+    {"ocr_enabled", "cloud_text_enabled", "cloud_media_enabled", "asr_word_timestamps"}
+)
+_V2_INT_FIELDS: frozenset[str] = frozenset({"max_media_mb", "frame_budget", "concurrency", "asr_beam_size"})
+_V2_FLOAT_FIELDS: frozenset[str] = frozenset({"max_duration_s", "task_deadline_s"})
+
+
+def _legacy_env_values(environ: dict[str, str] | os._Environ[str]) -> dict[str, Any]:
+    """Tier-4: the historical global env variables."""
+    values: dict[str, Any] = {}
+    for env_var, field_name in AppSettings._ENV_MAP.items():
+        raw = environ.get(env_var)
+        if raw is None:
+            continue
+        if field_name in AppSettings._BOOL_ENV_FIELDS:
+            values[field_name] = _env_flag(raw)
+        elif field_name in AppSettings._TUPLE_ENV_FIELDS:
+            values[field_name] = _comma_tuple(raw)
+        elif field_name in AppSettings._INT_ENV_FIELDS:
+            values[field_name] = _safe_int(raw, 0)
+        elif field_name in AppSettings._FLOAT_ENV_FIELDS:
+            values[field_name] = _safe_float(raw, 0.0)
+        else:
+            values[field_name] = raw
+    return values
+
+
+def _v2_env_values_split(
+    environ: dict[str, str] | os._Environ[str],
+) -> tuple[dict[str, Any], dict[str, bool]]:
+    """Tier-2: v2 platform/backend environment variables + platform enable flags."""
+    values: dict[str, Any] = {}
+    for env_var, field_name in _V2_ENV_MAP:
+        raw = environ.get(env_var)
+        if raw is None:
+            continue
+        if field_name in _V2_BOOL_FIELDS:
+            values[field_name] = _env_flag(raw)
+        elif field_name in _V2_INT_FIELDS:
+            values[field_name] = _safe_int(raw, 0)
+        elif field_name in _V2_FLOAT_FIELDS:
+            values[field_name] = _safe_float(raw, 0.0)
+        else:
+            values[field_name] = raw
+    return values, _platform_env_flags(environ)
+
+
+def _platform_env_flags(environ: dict[str, str] | os._Environ[str]) -> dict[str, bool]:
+    flags: dict[str, bool] = {}
+    for platform in SUPPORTED_PLATFORMS:
+        raw = environ.get(f"YTK_{platform.upper()}_ENABLED")
+        if raw is not None:
+            flags[platform] = _env_flag(raw)
+    return flags
+
+
+def _resolve_platforms_enabled(
+    explicit: Any,
+    merged_value: Any,
+    environ: dict[str, str] | os._Environ[str],
+    *,
+    toml_enable: dict[str, bool] | None = None,
+    env_enable: dict[str, bool] | None = None,
+) -> tuple[str, ...]:
+    """Compute the effective enabled platform tuple (explicit > env > lower tiers)."""
+    if explicit is not None:
+        # An explicit whitelist is final: no lower layer may add a platform back.
+        return tuple(_normalise_platforms(explicit))
+    env_list = environ.get("YTK_PLATFORMS_ENABLED")
+    if env_list not in (None, ""):
+        base = _normalise_platforms(env_list)
+        adjustments = dict(env_enable or {})  # env whitelist > TOML enabled flags
+    else:
+        base = (
+            _normalise_platforms(merged_value)
+            if merged_value is not None
+            else list(SUPPORTED_PLATFORMS)
+        )
+        adjustments = {**(toml_enable or {}), **(env_enable or {})}
+    for platform, enabled in adjustments.items():
+        if platform not in SUPPORTED_PLATFORMS:
+            continue
+        if enabled and platform not in base:
+            base.append(platform)
+        elif not enabled and platform in base:
+            base.remove(platform)
+    return tuple(_normalise_platforms(base))
+
+
+def _normalise_platforms(value: Any) -> list[str]:
+    if isinstance(value, str):
+        if value.strip().lower() in {"all", "*"}:
+            return list(SUPPORTED_PLATFORMS)
+        items = list(_comma_tuple(value))
+    elif isinstance(value, (list, tuple, set, frozenset)):
+        items = [str(item).strip() for item in value if str(item).strip()]
+    else:
+        raise ValueError("platforms_enabled must be a list of platform names")
+    unknown = [item for item in items if item not in SUPPORTED_PLATFORMS]
+    if unknown:
+        raise ValueError(f"unknown platform(s): {sorted(set(unknown))}")
+    return [platform for platform in SUPPORTED_PLATFORMS if platform in set(items)]
+
+
+__all__ = [
+    "AppSettings",
+    "AsrBackend",
+    "CONFIG_PATH_ENV_VAR",
+    "ConfigFileError",
+    "DEFAULT_OCR_MODEL_DIR",
+    "NO_DOTENV_ENV_VAR",
+    "TranscriptProxyMode",
+    "dotenv_disabled",
+    "load_config_file",
+]