Skip to content

"Vibe-Trading: Your Personal Trading Agent"

41.2 KB
Raw Blame
"""LLM and data-source settings HTTP routes.

Mounted by ``agent/api_server.py`` via ``register_settings_routes(app, ...)``.
"""

from __future__ import annotations

import asyncio
import importlib.util
import logging
import json
import os
import re
import sys as _sys
from pathlib import Path
from typing import Any, Awaitable, Callable, Dict, List, Literal, Optional
from urllib.parse import urlsplit

import httpx
from fastapi import Depends, FastAPI, HTTPException, status
from pydantic import BaseModel, Field

from src.config.accessor import get_env_value, reset_env_config

from src.config.gildata_features import FEATURES_ENV, GildataFeature, selected_features

logger = logging.getLogger(__name__)

# Agent root (agent/) — resolved from this file's location (agent/src/api/).
_AGENT_DIR = Path(__file__).resolve().parent.parent.parent


# ---------------------------------------------------------------------------
# Pydantic models (defined locally -- NO shared modules, per maintainer rule)
# ---------------------------------------------------------------------------


# "none" is an explicit value direct OpenAI needs to allow function tools on
# gpt-5.6-* models; a provider with its own levels lists them in llm_providers.json.
DEFAULT_REASONING_EFFORTS = ("none", "low", "medium", "high", "max")


class LLMProviderOption(BaseModel):
    """Supported LLM provider metadata for the settings UI."""

    name: str
    label: str
    api_key_env: Optional[str] = None
    base_url_env: str
    default_model: str
    model_options: List[str] = Field(default_factory=list)
    default_base_url: str
    base_url_options: List[str] = Field(default_factory=list)
    api_key_required: bool = True
    auth_type: str = "api_key"
    login_command: Optional[str] = None
    # Levels the settings form offers and the update route accepts; "" (unset)
    # is always allowed on top of these.
    reasoning_efforts: List[str] = Field(default_factory=lambda: list(DEFAULT_REASONING_EFFORTS))


class LLMSettingsResponse(BaseModel):
    """Current LLM runtime settings."""

    provider: str
    model_name: str
    base_url: str
    api_key_env: Optional[str] = None
    api_key_configured: bool
    api_key_hint: Optional[str] = None
    api_key_required: bool
    temperature: float
    timeout_seconds: int
    max_retries: int
    reasoning_effort: str
    sse_timeout_seconds: int
    env_path: str
    providers: List[LLMProviderOption]


class UpdateLLMSettingsRequest(BaseModel):
    """Update LLM settings persisted to agent/.env."""

    provider: str = Field(..., min_length=1)
    model_name: str = Field(..., min_length=1)
    base_url: Optional[str] = None
    api_key: Optional[str] = None
    clear_api_key: bool = False
    temperature: float = 0.0
    timeout_seconds: int = Field(120, ge=1, le=3600)
    max_retries: int = Field(2, ge=0, le=20)
    reasoning_effort: Optional[str] = None


class ListLLMModelsRequest(BaseModel):
    """Resolve live model choices without persisting credentials or settings."""

    provider: str = Field(..., min_length=1)
    base_url: Optional[str] = None
    api_key: Optional[str] = None
    refresh: bool = False


ModelDiscoveryWarningCode = Literal[
    "oauth_discovery_unsupported",
    "api_key_required",
    "model_list_unavailable",
]


class LLMModelsResponse(BaseModel):
    """Model IDs suitable for an editable settings combobox."""

    provider: str
    models: List[str]
    source: str
    warning_code: Optional[ModelDiscoveryWarningCode] = None
    # Model id -> reasoning effort levels it accepts; an empty list means the
    # model takes no effort setting. Only providers that report it fill this.
    effort_levels: Optional[Dict[str, List[str]]] = None
    # Optional display metadata. IDs remain canonical and editable.
    model_labels: Optional[Dict[str, str]] = None
    default_effort_levels: Optional[Dict[str, str]] = None


class SourceOrderEntry(BaseModel):
    """One market's fallback-chain order (default + override state)."""

    market: str
    env_var: str
    default_order: List[str]
    effective_order: List[str]
    override: Optional[List[str]] = None
    override_invalid: bool = False


class SourceOrderUpdate(BaseModel):
    """Reorder one market's fallback chain (null/empty order = reset)."""

    market: str
    order: Optional[List[str]] = None


class DataSourceSettingsResponse(BaseModel):
    """Current data source credential settings."""

    tushare_token_configured: bool
    tushare_token_hint: Optional[str] = None
    gildata_features: list[GildataFeature] = Field(default_factory=list)
    gildata_token_configured: bool
    gildata_token_hint: Optional[str] = None
    baostock_supported: bool
    baostock_installed: bool
    baostock_message: str
    env_path: str
    source_orders: List[SourceOrderEntry] = Field(default_factory=list)


class UpdateDataSourceSettingsRequest(BaseModel):
    """Update project-local data source credentials."""

    tushare_token: Optional[str] = None
    clear_tushare_token: bool = False
    gildata_token: Optional[str] = None
    gildata_features: list[GildataFeature] | None = None
    clear_gildata_token: bool = False
    source_orders: Optional[List[SourceOrderUpdate]] = None


# ---------------------------------------------------------------------------
# Provider metadata (settings-exclusive)
# ---------------------------------------------------------------------------

LLM_PROVIDER_CONFIG_PATH = _AGENT_DIR / "src" / "providers" / "llm_providers.json"


def _load_llm_providers() -> List[LLMProviderOption]:
    """Load provider metadata from JSON so additions stay data-driven."""
    try:
        raw = json.loads(LLM_PROVIDER_CONFIG_PATH.read_text(encoding="utf-8"))
        providers = [LLMProviderOption(**item) for item in raw]
    except Exception as exc:
        raise RuntimeError(f"Failed to load LLM provider config: {LLM_PROVIDER_CONFIG_PATH}") from exc

    seen: set[str] = set()
    for provider in providers:
        if provider.name in seen:
            raise RuntimeError(f"Duplicate LLM provider name: {provider.name}")
        seen.add(provider.name)
    if not providers:
        raise RuntimeError("LLM provider config must not be empty")
    return providers


LLM_PROVIDERS = _load_llm_providers()
LLM_PROVIDER_BY_NAME = {provider.name: provider for provider in LLM_PROVIDERS}
LLM_API_KEY_PLACEHOLDERS = {"", "sk-or-v1-your-key-here", "sk-xxx", "xxx", "gsk_xxx"}
TUSHARE_TOKEN_PLACEHOLDERS = {"", "your-tushare-token"}
GILDATA_TOKEN_PLACEHOLDERS = {"", "your-gildata-token"}


def _desktop_secure_credential_names() -> set[str]:
    """Return secrets owned by the desktop host when secure storage is active."""
    names = {"TUSHARE_TOKEN", "GILDATA_TOKEN"}
    names.update(
        provider.api_key_env for provider in LLM_PROVIDERS if provider.api_key_env
    )
    return names


def _desktop_secure_credentials_enabled() -> bool:
    return get_env_value("VIBE_TRADING_DESKTOP_SECURE_CREDENTIALS") == "1"


# ---------------------------------------------------------------------------
# Host access helpers (late-binding for test monkeypatch compat)
# ---------------------------------------------------------------------------


def _host():
    """Return the ``api_server`` module for late-access attribute reads.

    Tests monkeypatch ``ENV_PATH``, ``ENV_EXAMPLE_PATH``, ``_baostock_supported``
    and ``_baostock_installed`` directly on the ``api_server`` module; every
    function that reads these symbols goes through ``_host()`` so monkeypatched
    values take effect.
    """
    return _sys.modules.get("api_server") or _sys.modules.get("agent.api_server")


# ---------------------------------------------------------------------------
# Settings-exclusive helpers
# ---------------------------------------------------------------------------


def _baostock_supported() -> bool:
    """Check whether the project has a BaoStock loader implementation."""
    host = _host()
    agent_dir = host.AGENT_DIR if host is not None else _AGENT_DIR
    loader_dir = agent_dir / "backtest" / "loaders"
    return any((loader_dir / name).exists() for name in ("baostock.py", "baostock_loader.py"))


def _baostock_installed() -> bool:
    """Check whether the optional BaoStock package is importable."""
    return importlib.util.find_spec("baostock") is not None


def _read_settings_env_values() -> Dict[str, str]:
    """Read settings without creating a dotenv file.

    Prefer the canonical user config, then the legacy package-local config.
    If neither exists, use ``agent/.env.example`` for display defaults only.
    """
    host = _host()
    env_path = host.ENV_PATH
    legacy_env_path = getattr(host, "LEGACY_ENV_PATH", _AGENT_DIR / ".env")
    env_example_path = host.ENV_EXAMPLE_PATH
    read_env = host._read_env_values
    if env_path.exists():
        values = read_env(env_path)
    elif legacy_env_path.exists():
        values = read_env(legacy_env_path)
    elif env_example_path.exists():
        values = read_env(env_example_path)
    else:
        values = {}

    if _desktop_secure_credentials_enabled():
        for name in _desktop_secure_credential_names():
            runtime_value = get_env_value(name)
            if runtime_value:
                values[name] = runtime_value
            else:
                values.pop(name, None)
    return values


def _model_list_url(base_url: str) -> str:
    """Return the OpenAI-compatible model-list endpoint for a provider URL."""
    url = base_url.strip().rstrip("/")
    for suffix in ("/chat/completions", "/responses"):
        if url.endswith(suffix):
            url = url[: -len(suffix)]
            break
    return f"{url}/models"


def _validate_model_base_url(base_url: str) -> str:
    """Accept HTTP(S) provider endpoints without embedded URL credentials."""
    normalized = base_url.strip().rstrip("/")
    parsed = urlsplit(normalized)
    if (
        parsed.scheme not in {"http", "https"}
        or not parsed.hostname
        or parsed.username is not None
        or parsed.password is not None
    ):
        raise ValueError("Provider base URL must be an HTTP(S) URL without embedded credentials")
    return normalized


def _extract_model_ids(payload: Any) -> List[str]:
    """Normalize common OpenAI-compatible model-list response shapes."""
    if not isinstance(payload, dict):
        return []
    records = payload.get("data")
    if not isinstance(records, list):
        records = payload.get("models")
    if not isinstance(records, list):
        return []

    model_ids: set[str] = set()
    for item in records:
        if isinstance(item, str):
            model_id = item.strip()
        elif isinstance(item, dict):
            model_id = str(item.get("id") or item.get("name") or "").strip()
        else:
            continue
        if model_id:
            model_ids.add(model_id)
    return sorted(model_ids, key=str.casefold)[:1000]


# Codex CLI model discovery requires a client_version query parameter. Keep
# this value explicit and review it when updating Codex OAuth compatibility.
# Verified with the ChatGPT Codex catalog on 2026-10-27.
_CODEX_MODELS_URL = "https://chatgpt.com/backend-api/codex/models"
_CODEX_MODELS_CLIENT_VERSION = "0.159.0"
_CODEX_EFFORT_LEVELS = frozenset(LLM_PROVIDER_BY_NAME["openai-codex"].reasoning_efforts)


async def _list_openai_codex_models(provider: LLMProviderOption) -> LLMModelsResponse:
    """Discover ChatGPT OAuth models without sharing the token with form URLs."""
    from src.providers.openai_codex import _build_headers, _get_codex_token

    fallback = LLMModelsResponse(
        provider=provider.name,
        models=[provider.default_model],
        source="default",
        warning_code="model_list_unavailable",
    )
    try:
        token = await asyncio.to_thread(_get_codex_token)
        async with httpx.AsyncClient(timeout=12.0, follow_redirects=False, trust_env=False) as client:
            for attempt in range(2):
                headers = _build_headers(token.account_id, token.access)
                headers["Accept"] = "application/json"
                response = await client.get(
                    _CODEX_MODELS_URL,
                    params={"client_version": _CODEX_MODELS_CLIENT_VERSION},
                    headers=headers,
                )
                if response.status_code == 401 and attempt == 0:
                    token = await asyncio.to_thread(
                        _get_codex_token, force_refresh=True, rejected_access=token.access
                    )
                    continue
                response.raise_for_status()
                payload = response.json()
                break
        if not isinstance(payload, dict) or not isinstance(payload.get("models"), list):
            return fallback

        models: list[str] = []
        efforts: dict[str, list[str]] = {}
        labels: dict[str, str] = {}
        defaults: dict[str, str] = {}
        for item in payload["models"][:1000]:
            if not isinstance(item, dict):
                continue
            # supported_in_api is an API-key catalog filter, not a ChatGPT
            # entitlement check (Codex ModelPreset::filter_by_auth).
            if item.get("visibility") != "list":
                continue
            slug = item.get("slug")
            if not isinstance(slug, str) or not slug or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}", slug):
                continue
            model_id = f"openai-codex/{slug}"
            if model_id in models:
                continue
            models.append(model_id)
            label = item.get("display_name")
            if isinstance(label, str) and label.strip():
                labels[model_id] = label.strip()[:128]
            levels = item.get("supported_reasoning_levels")
            if isinstance(levels, list):
                supported = []
                for level in levels:
                    effort = level.get("effort") if isinstance(level, dict) else None
                    if isinstance(effort, str) and effort in _CODEX_EFFORT_LEVELS and effort not in supported:
                        supported.append(effort)
                efforts[model_id] = supported
            default = item.get("default_reasoning_level")
            if (isinstance(default, str) and default in _CODEX_EFFORT_LEVELS
                    and (model_id not in efforts or default in efforts[model_id])):
                defaults[model_id] = default
        if not models:
            return fallback
        return LLMModelsResponse(
            provider=provider.name,
            models=models,
            source="provider",
            effort_levels=efforts,
            model_labels=labels,
            default_effort_levels=defaults,
        )
    except (RuntimeError, AttributeError, httpx.HTTPError, ValueError, TypeError) as exc:
        # Never log exception bodies here: the HTTP response could contain secrets.
        logger.warning("OpenAI Codex model discovery unavailable (%s)", type(exc).__name__)
        return fallback


async def _list_provider_models(
    provider: LLMProviderOption,
    *,
    base_url: str,
    api_key: str,
) -> LLMModelsResponse:
    """Best-effort live model discovery with a safe editable fallback."""
    fallback = [provider.default_model]
    # Keep the direct MiniMax picker curated. Saved/custom model names remain
    # editable, and custom endpoints retain their own live model discovery.
    if provider.name == "minimax" and base_url.rstrip("/") in provider.base_url_options:
        return LLMModelsResponse(
            provider=provider.name,
            models=provider.model_options or fallback,
            source="default",
        )
    if provider.auth_type in {"oauth", "gh_cli"}:
        return LLMModelsResponse(
            provider=provider.name,
            models=fallback,
            source="default",
            warning_code="oauth_discovery_unsupported",
        )
    if provider.api_key_required and not api_key:
        return LLMModelsResponse(
            provider=provider.name,
            models=fallback,
            source="default",
            warning_code="api_key_required",
        )

    if provider.name == "ollama" and not base_url.rstrip("/").endswith("/v1"):
        base_url = f"{base_url.rstrip('/')}/v1"

    headers = {"Accept": "application/json"}
    if api_key:
        headers["Authorization"] = f"Bearer {api_key}"
    try:
        async with httpx.AsyncClient(timeout=12.0, follow_redirects=False) as client:
            response = await client.get(_model_list_url(base_url), headers=headers)
            response.raise_for_status()
            models = _extract_model_ids(response.json())
    except (httpx.HTTPError, ValueError):
        return LLMModelsResponse(
            provider=provider.name,
            models=fallback,
            source="default",
            warning_code="model_list_unavailable",
        )

    # Prefer configured recommendations without deleting discovered routes.
    # Paid variants, legacy models and future releases remain selectable.
    official_endpoints = {provider.default_base_url, *provider.base_url_options}
    if base_url.rstrip("/") in official_endpoints:
        preferred = [model for model in provider.model_options if model in models]
        models = preferred + [model for model in models if model not in preferred]

    discovered = bool(models)
    if provider.default_model not in models:
        models.insert(0, provider.default_model)
    return LLMModelsResponse(
        provider=provider.name,
        models=models or fallback,
        source="provider" if discovered else "default",
    )


async def _list_claude_cli_models(
    provider: LLMProviderOption, *, refresh: bool
) -> LLMModelsResponse:
    """List the models the local Claude Code login can run, with their effort levels."""
    from src.providers.claude_cli_models import list_claude_cli_models

    try:
        discovered = await asyncio.to_thread(list_claude_cli_models, refresh=refresh)
    except RuntimeError as exc:
        logger.warning("claude-cli model list unavailable: %s", exc)
        return LLMModelsResponse(
            provider=provider.name,
            models=[provider.default_model],
            source="default",
            warning_code="model_list_unavailable",
        )
    models = [model.model_id for model in discovered]
    if provider.default_model not in models:
        models.insert(0, provider.default_model)
    return LLMModelsResponse(
        provider=provider.name,
        models=models,
        source="provider",
        effort_levels={model.model_id: list(model.effort_levels) for model in discovered},
    )


# ---------------------------------------------------------------------------
# Response builders
# ---------------------------------------------------------------------------


def _build_llm_settings_response(
    values: Optional[Dict[str, str]] = None,
) -> LLMSettingsResponse:
    """Build the public settings payload from dotenv values."""
    host = _host()
    env_values = values if values is not None else _read_settings_env_values()
    provider_name = env_values.get("LANGCHAIN_PROVIDER", "openai").strip().lower()
    provider = LLM_PROVIDER_BY_NAME.get(provider_name, LLM_PROVIDER_BY_NAME["openai"])
    api_key = env_values.get(provider.api_key_env or "", "") if provider.api_key_env else ""
    api_key_configured = host._is_configured_secret(api_key, LLM_API_KEY_PLACEHOLDERS)
    api_key_hint = None
    if provider.auth_type == "oauth":
        try:
            from src.providers.openai_codex import get_openai_codex_login_status

            token = get_openai_codex_login_status()
        except Exception:
            token = None
        api_key_configured = bool(token)
        api_key_hint = None
    elif provider.auth_type == "gh_cli":
        try:
            from src.providers.copilot_auth import get_copilot_auth_status

            authenticated, auth_status = get_copilot_auth_status()
        except Exception:
            authenticated, auth_status = False, ""
        api_key_configured = authenticated
        api_key_hint = auth_status if authenticated else None
    elif provider.auth_type == "claude_cli":
        try:
            from src.providers.claude_cli import get_claude_cli_auth_status

            authenticated, auth_status = get_claude_cli_auth_status()
        except Exception:
            authenticated, auth_status = False, ""
        api_key_configured = authenticated
        api_key_hint = auth_status if authenticated else None
    options = LLM_PROVIDERS
    if provider_name == "custom":
        from src.providers.custom_profiles import CustomProviderStore

        active = next((p for p in CustomProviderStore().list_public() if p["active"]), None)
        active_model = active["model"] if active else env_values.get("LANGCHAIN_MODEL_NAME", "")
        active_url = active["base_url"] if active else ""
        provider = LLMProviderOption(name="custom", label="Custom (credential vault)",
            api_key_env=None, base_url_env="OPENAI_BASE_URL", default_model=active_model,
            default_base_url=active_url, auth_type="credential_vault", reasoning_efforts=[])
        env_values = {**env_values, "LANGCHAIN_MODEL_NAME": active_model, "OPENAI_BASE_URL": active_url}
        api_key_configured, api_key_hint = bool(active and active["api_key_configured"]), None
        options = [*LLM_PROVIDERS, provider]
    return LLMSettingsResponse(
        provider=provider.name,
        model_name=env_values.get("LANGCHAIN_MODEL_NAME", provider.default_model),
        base_url=env_values.get(provider.base_url_env, provider.default_base_url),
        api_key_env=provider.api_key_env,
        api_key_configured=api_key_configured,
        api_key_hint=api_key_hint,
        api_key_required=provider.api_key_required,
        temperature=host._coerce_float(env_values.get("LANGCHAIN_TEMPERATURE", "0.0"), 0.0),
        timeout_seconds=host._coerce_int(env_values.get("TIMEOUT_SECONDS", "120"), 120),
        max_retries=host._coerce_int(env_values.get("MAX_RETRIES", "2"), 2),
        reasoning_effort=env_values.get("LANGCHAIN_REASONING_EFFORT", "").strip().lower(),
        sse_timeout_seconds=host._coerce_int(env_values.get("VIBE_TRADING_SSE_TIMEOUT", "90"), 90),
        env_path=host._project_relative_path(host.ENV_PATH),
        providers=options,
    )


def activate_custom_provider(profile: dict[str, Any], *, store: Any) -> dict[str, Any]:
    """Activate tested vault metadata through the canonical settings writer.

    Secrets remain in the vault. The runtime resolves model, URL and key from
    one active profile, so it never pairs another provider's ambient key with
    the selected endpoint. The caller holds the shared store mutation lock.
    """
    updates = {"LANGCHAIN_PROVIDER": "custom", "LANGCHAIN_MODEL_NAME": profile["model"]}
    previous = store._read()
    store.activate(profile["id"])
    try:
        _persist_settings_updates(updates)
    except Exception:
        store._write(previous)
        raise
    for key, value in updates.items():
        os.environ[key] = str(value)
    reset_env_config()
    return {"status": "ok", "active_id": profile["id"], "model": profile["model"], "base_url": profile["base_url"]}


def _build_source_orders(env_values: Dict[str, str]) -> List[SourceOrderEntry]:
    """Build per-market source-order entries for the settings payload.

    ``effective_order`` reflects the running process (registry state after a
    refresh); ``override`` reflects the persisted dotenv value, with
    ``override_invalid`` flagging values that failed validation (kept in the
    file for transparency, but not applied).
    """
    from backtest.loaders import registry

    registry.refresh_source_order_overrides()
    entries: List[SourceOrderEntry] = []
    for market in sorted(registry._DEFAULT_CHAINS):
        env_var = registry.source_order_env_var(market)
        default_order = registry.get_default_source_order(market)
        parsed = registry.parse_source_order(env_values.get(env_var, ""))
        entries.append(
            SourceOrderEntry(
                market=market,
                env_var=env_var,
                default_order=default_order,
                effective_order=list(registry.FALLBACK_CHAINS.get(market, default_order)),
                override=parsed or None,
                override_invalid=bool(parsed)
                and not registry.is_valid_source_order(market, parsed),
            )
        )
    return entries


def _validate_source_order_update(entry: SourceOrderUpdate) -> tuple[str, str]:
    """Validate one market reorder; return ``(env_var, dotenv value)``.

    A null/empty order — or one equal to the default — maps to an empty
    string, which clears any persisted override for that market.
    """
    from backtest.loaders import registry

    market = entry.market.strip()
    default_order = registry.get_default_source_order(market)
    if not default_order:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=f"Unknown market: {market!r}",
        )
    order = (
        [name.strip().lower() for name in entry.order if name.strip()]
        if entry.order
        else []
    )
    if order and not registry.is_valid_source_order(market, order):
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail=(
                f"Invalid source order for {market}: must be a permutation of "
                f"the default chain {default_order}"
            ),
        )
    return (
        registry.source_order_env_var(market),
        "" if not order or order == default_order else ",".join(order),
    )


def _build_data_source_settings_response(
    values: Optional[Dict[str, str]] = None,
) -> DataSourceSettingsResponse:
    """Build the public data source settings payload."""
    host = _host()
    env_values = values if values is not None else _read_settings_env_values()
    token = env_values.get("TUSHARE_TOKEN", "")
    token_configured = host._is_configured_secret(token, TUSHARE_TOKEN_PLACEHOLDERS)
    gildata = env_values.get("GILDATA_TOKEN", "")
    gildata_configured = host._is_configured_secret(gildata, GILDATA_TOKEN_PLACEHOLDERS)
    # Late-access baostock helpers for monkeypatch compat.
    baostock_sup = getattr(host, "_baostock_supported", _baostock_supported)
    baostock_ins = getattr(host, "_baostock_installed", _baostock_installed)
    supported = baostock_sup()
    installed = baostock_ins()
    if supported:
        baostock_message = "BaoStock loader is available."
    elif installed:
        baostock_message = "BaoStock package is installed, but this project has no BaoStock loader."
    else:
        baostock_message = "No BaoStock loader is registered in this project."
    return DataSourceSettingsResponse(
        tushare_token_configured=token_configured,
        tushare_token_hint=None,
        gildata_token_configured=gildata_configured,
        gildata_token_hint=None,
        gildata_features=selected_features(),
        baostock_supported=supported,
        baostock_installed=installed,
        baostock_message=baostock_message,
        env_path=host._project_relative_path(host.ENV_PATH),
        source_orders=_build_source_orders(env_values),
    )


def _sync_runtime_env(provider: LLMProviderOption, updates: Dict[str, str]) -> None:
    """Apply saved LLM settings to the running API process."""
    host = _host()
    for key, value in updates.items():
        if value:
            os.environ[key] = value
        else:
            os.environ.pop(key, None)

    if provider.auth_type == "credential_vault":
        reset_env_config()
        return
    if provider.auth_type in {"gh_cli", "claude_cli"}:
        # The Copilot SDK / Claude Code CLI own credential discovery and transport.
        os.environ.pop("OPENAI_API_KEY", None)
        os.environ.pop("OPENAI_API_BASE", None)
        os.environ.pop("OPENAI_BASE_URL", None)
        reset_env_config()
        return
    elif provider.api_key_env:
        key_value = os.environ.get(provider.api_key_env, "")  # noqa: env-gate — dynamic provider api_key_env
        if host._is_configured_secret(key_value, LLM_API_KEY_PLACEHOLDERS):
            os.environ["OPENAI_API_KEY"] = key_value
        else:
            os.environ.pop("OPENAI_API_KEY", None)
    elif provider.auth_type == "oauth":
        os.environ.pop("OPENAI_API_KEY", None)
    else:
        os.environ["OPENAI_API_KEY"] = "ollama"

    base_url = os.environ.get(provider.base_url_env, "")  # noqa: env-gate — dynamic provider base_url_env
    if base_url:
        os.environ["OPENAI_API_BASE"] = base_url
        os.environ["OPENAI_BASE_URL"] = base_url
    else:
        os.environ.pop("OPENAI_API_BASE", None)
        os.environ.pop("OPENAI_BASE_URL", None)

    reset_env_config()


def _persist_settings_updates(updates: Dict[str, str]) -> Dict[str, str]:
    """Persist settings to the canonical user config with legacy migration.

    Args:
        updates: Environment keys to upsert.

    Returns:
        Effective values read back from the canonical dotenv.

    Raises:
        HTTPException: If the user config cannot be written.
    """
    host = _host()
    target = host.ENV_PATH
    legacy = getattr(host, "LEGACY_ENV_PATH", _AGENT_DIR / ".env")
    merged = dict(updates)
    if not target.exists() and legacy != target and legacy.exists():
        merged = {**host._read_env_values(legacy), **updates}
    if _desktop_secure_credentials_enabled():
        # Empty known secret keys in dotenv while preserving the decrypted
        # environment values injected by Electron for this process.
        merged.update({name: "" for name in _desktop_secure_credential_names()})
    try:
        host._write_env_values(target, merged)
    except OSError as exc:
        raise HTTPException(
            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
            detail=(
                "Unable to save settings; check ownership and permissions for "
                "~/.vibe-trading/.env"
            ),
        ) from exc
    return _read_settings_env_values()


# ---------------------------------------------------------------------------
# Registration
# ---------------------------------------------------------------------------

AuthDep = Callable[..., Awaitable[Any] | Any]


def register_settings_routes(
    app: FastAPI,
    require_local_or_auth: AuthDep | None = None,
    require_settings_write_auth: AuthDep | None = None,
) -> None:
    """Mount the settings routes onto ``app``."""
    host = _sys.modules.get("api_server") or _sys.modules.get("agent.api_server")

    if host is None:
        raise RuntimeError(
            "register_settings_routes: api_server module not in sys.modules; "
            "ensure api_server is imported before calling this function"
        )

    if require_local_or_auth is None:
        require_local_or_auth = host.require_local_or_auth
    if require_settings_write_auth is None:
        require_settings_write_auth = host.require_settings_write_auth

    # --- Routes ---

    @app.get(
        "/settings/llm",
        response_model=LLMSettingsResponse,
        dependencies=[Depends(require_local_or_auth)],
    )
    async def get_llm_settings():
        """Return project-local LLM settings for the Web UI."""
        # gh_cli / claude_cli providers shell out for their login status; keep
        # that off the event loop so open SSE streams are not stalled.
        return await asyncio.to_thread(_build_llm_settings_response)

    @app.put(
        "/settings/llm",
        response_model=LLMSettingsResponse,
        dependencies=[Depends(require_settings_write_auth)],
    )
    async def update_llm_settings(payload: UpdateLLMSettingsRequest):
        """Persist project-local LLM settings and update the running process."""
        host_ref = _host()
        provider_name = payload.provider.strip().lower()
        provider = LLM_PROVIDER_BY_NAME.get(provider_name)
        if provider_name == "custom":
            from src.providers.custom_profiles import active_provider_credentials

            active = active_provider_credentials()
            if (payload.model_name.strip() != active["model"]
                    or payload.base_url not in (None, active["base_url"])
                    or payload.api_key or payload.clear_api_key):
                raise HTTPException(status_code=400, detail="Edit and test a custom provider in the provider manager before activating it")
            provider = LLMProviderOption(name="custom", label="Custom (credential vault)", api_key_env=None,
                base_url_env="OPENAI_BASE_URL", default_model=active["model"], default_base_url=active["base_url"],
                auth_type="credential_vault", reasoning_efforts=[])
        if provider is None:
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST, detail="Unsupported LLM provider"
            )

        model_name = payload.model_name.strip()
        if not model_name:
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST, detail="Model name is required"
            )

        if payload.temperature < 0 or payload.temperature > 2:
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST,
                detail="Temperature must be between 0 and 2",
            )

        reasoning_effort = (payload.reasoning_effort or "").strip().lower()
        if reasoning_effort and reasoning_effort not in provider.reasoning_efforts:
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST,
                detail=(
                    f"Reasoning effort must be one of {', '.join(provider.reasoning_efforts)}, "
                    "or empty to leave it unset"
                ),
            )

        current_values = _read_settings_env_values()
        base_url = (
            payload.base_url if payload.base_url is not None else provider.default_base_url
        ).strip()
        if provider.auth_type == "oauth":
            try:
                from src.providers.openai_codex import validate_codex_base_url

                base_url = validate_codex_base_url(base_url)
            except ValueError as exc:
                raise HTTPException(
                    status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
                ) from exc
        updates: Dict[str, str] = {
            "LANGCHAIN_PROVIDER": provider.name,
            "LANGCHAIN_MODEL_NAME": model_name,
            provider.base_url_env: base_url,
            "LANGCHAIN_TEMPERATURE": str(payload.temperature),
            "TIMEOUT_SECONDS": str(payload.timeout_seconds),
            "MAX_RETRIES": str(payload.max_retries),
        }
        if reasoning_effort or "LANGCHAIN_REASONING_EFFORT" in current_values:
            updates["LANGCHAIN_REASONING_EFFORT"] = reasoning_effort

        if provider.api_key_env:
            if payload.clear_api_key:
                updates[provider.api_key_env] = ""
            elif payload.api_key is not None and payload.api_key.strip():
                api_key = payload.api_key.strip()
                updates[provider.api_key_env] = (
                    api_key
                    if host_ref._is_configured_secret(api_key, LLM_API_KEY_PLACEHOLDERS)
                    else ""
                )
            elif provider.api_key_env in current_values and host_ref._is_configured_secret(
                current_values[provider.api_key_env],
                LLM_API_KEY_PLACEHOLDERS,
            ):
                updates[provider.api_key_env] = current_values[provider.api_key_env]
        elif payload.clear_api_key:
            os.environ.pop("OPENAI_API_KEY", None)

        saved_values = _persist_settings_updates(updates)
        _sync_runtime_env(provider, updates)
        return await asyncio.to_thread(_build_llm_settings_response, saved_values)

    @app.post(
        "/settings/llm/models",
        response_model=LLMModelsResponse,
        dependencies=[Depends(require_settings_write_auth)],
    )
    async def list_llm_models(payload: ListLLMModelsRequest):
        """Load provider model IDs for an editable UI combobox."""
        provider_name = payload.provider.strip().lower()
        provider = LLM_PROVIDER_BY_NAME.get(provider_name)
        if provider is None:
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST, detail="Unsupported LLM provider"
            )
        if provider.auth_type == "claude_cli":
            # No HTTP endpoint: the base URL checks below would reject it outright.
            return await _list_claude_cli_models(provider, refresh=payload.refresh)
        if provider.name == "openai-codex":
            # OAuth credentials only go to our fixed Codex catalog endpoint.
            # Do not use base_url or api_key values supplied by the settings form.
            return await _list_openai_codex_models(provider)

        current_values = _read_settings_env_values()
        requested_base_url = (payload.base_url or "").strip()
        saved_base_url = (
            current_values.get(provider.base_url_env) or provider.default_base_url
        ).strip()
        try:
            base_url = _validate_model_base_url(requested_base_url or saved_base_url)
        except ValueError as exc:
            raise HTTPException(
                status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)
            ) from exc
        api_key = (payload.api_key or "").strip()
        if not api_key and provider.api_key_env:
            trusted_base_urls = {
                _validate_model_base_url(candidate)
                for candidate in (
                    saved_base_url,
                    provider.default_base_url,
                    *provider.base_url_options,
                )
                if candidate.strip()
            }
            if not requested_base_url or base_url in trusted_base_urls:
                saved_key = current_values.get(provider.api_key_env, "").strip()
                if _host()._is_configured_secret(saved_key, LLM_API_KEY_PLACEHOLDERS):
                    api_key = saved_key
        return await _list_provider_models(
            provider,
            base_url=base_url,
            api_key=api_key,
        )

    @app.get(
        "/settings/data-sources",
        response_model=DataSourceSettingsResponse,
        dependencies=[Depends(require_local_or_auth)],
    )
    async def get_data_source_settings():
        """Return project-local data source credentials for the Web UI."""
        return _build_data_source_settings_response()

    @app.put(
        "/settings/data-sources",
        response_model=DataSourceSettingsResponse,
        dependencies=[Depends(require_settings_write_auth)],
    )
    async def update_data_source_settings(payload: UpdateDataSourceSettingsRequest):
        """Persist project-local data source credentials and update the running process."""
        host_ref = _host()
        current_values = _read_settings_env_values()
        updates: Dict[str, str] = {}

        if payload.clear_tushare_token:
            updates["TUSHARE_TOKEN"] = ""
        elif payload.tushare_token is not None and payload.tushare_token.strip():
            updates["TUSHARE_TOKEN"] = payload.tushare_token.strip()
        elif "TUSHARE_TOKEN" in current_values:
            updates["TUSHARE_TOKEN"] = current_values["TUSHARE_TOKEN"]

        if payload.clear_gildata_token:
            updates["GILDATA_TOKEN"] = ""
        elif payload.gildata_token is not None and payload.gildata_token.strip():
            updates["GILDATA_TOKEN"] = payload.gildata_token.strip()
        elif "GILDATA_TOKEN" in current_values:
            updates["GILDATA_TOKEN"] = current_values["GILDATA_TOKEN"]

        # Per-market source-order overrides: validate first (400 on a bad
        # permutation *before* anything is persisted), then merge only the
        # entries that actually change the dotenv (no-op saves don't grow
        # the file with 12 identical lines).
        order_updates: Dict[str, str] = {}
        if payload.source_orders is not None:
            for order_entry in payload.source_orders:
                env_var, value = _validate_source_order_update(order_entry)
                order_updates[env_var] = value
            for env_var, value in order_updates.items():
                if value != current_values.get(env_var, ""):
                    updates[env_var] = value

        if payload.gildata_features is not None:
            updates[FEATURES_ENV] = ",".join(dict.fromkeys(payload.gildata_features))

        if updates:
            saved_values = _persist_settings_updates(updates)
            for key, placeholders in (
                ("TUSHARE_TOKEN", TUSHARE_TOKEN_PLACEHOLDERS),
                ("GILDATA_TOKEN", GILDATA_TOKEN_PLACEHOLDERS),
            ):
                if key in updates:
                    token = updates[key].strip()
                    if host_ref._is_configured_secret(token, placeholders):
                        os.environ[key] = token
                    else:
                        os.environ.pop(key, None)
            if FEATURES_ENV in updates:
                os.environ[FEATURES_ENV] = updates[FEATURES_ENV]
            # Hot-apply source-order overrides in this process.
            for env_var, value in order_updates.items():
                if value:
                    os.environ[env_var] = value
                else:
                    os.environ.pop(env_var, None)
            if order_updates:
                from backtest.loaders import registry

                registry.refresh_source_order_overrides()
            reset_env_config()

        return _build_data_source_settings_response(
            saved_values if updates else _read_settings_env_values()
        )