Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

11.6 KB
Raw Blame
"""
Interface (UI) settings reader.

This is the canonical backend source for user-selected UI language/theme stored in:
  data/user/settings/interface.json
"""

from __future__ import annotations

from collections.abc import Callable, Mapping
import json
import os
from pathlib import Path
import tempfile
import threading
from typing import Any, Literal

from deeptutor.response_languages import SUPPORTED_RESPONSE_LANGUAGES
from deeptutor.services.path_service import get_path_service
from deeptutor.tools.builtin import USER_TOGGLEABLE_TOOL_NAMES

UiLanguage = Literal["en", "zh", "fr", "de", "uk", "pl"]

DEFAULT_UI_SETTINGS: dict[str, Any] = {
    # "snow" is the pure-white neutral theme, shown as "Default" in the UI.
    "theme": "snow",
    "language": "en",
    "response_language": "en",
    # When true, TTS verbalizes LaTeX (fractions, powers, Greek). Dollar
    # delimiters are stripped either way so the voice never says "dollar".
    "voice_math_speak": True,
}


_LOCKS_GUARD = threading.Lock()
_LOCKS: dict[str, threading.Lock] = {}

_RESPONSE_LANGUAGE_ALIASES: dict[str, str] = {
    "english": "en",
    "chinese": "zh",
    "simplified chinese": "zh",
    "traditional chinese": "zh-tw",
    "japanese": "ja",
    "korean": "ko",
    "spanish": "es",
    "french": "fr",
    "german": "de",
    "russian": "ru",
    "portuguese": "pt",
    "italian": "it",
    "arabic": "ar",
    "polish": "pl",
    "malay": "ms",
    "bahasa melayu": "ms",
}


def _settings_lock(path: Path) -> threading.Lock:
    """One lock per settings file, so a write only serialises its own file.

    Keyed by resolved path rather than a single global lock because in a
    multi-user deployment each account has its own ``interface.json``; making
    them contend would serialise unrelated users' preference writes.
    """
    # Resolve the directory only: resolving the file can open it on Windows
    # before its lock is acquired, preventing another writer from replacing it.
    key = os.path.normcase(str(path.parent.resolve() / path.name))
    # Windows may return an extended path while a directory is being created.
    # Both spellings must identify the same lock.
    if os.name == "nt":
        if key.startswith("\\\\?\\unc\\"):
            key = "\\\\" + key[8:]
        elif key.startswith("\\\\?\\"):
            key = key[4:]
    with _LOCKS_GUARD:
        lock = _LOCKS.get(key)
        if lock is None:
            lock = threading.Lock()
            _LOCKS[key] = lock
        return lock


def _interface_settings_file():
    # Resolved on every call so a per-user PathService (set after auth)
    # routes reads to the caller's own ``settings/interface.json`` instead
    # of the admin scope frozen at import time.
    return get_path_service().get_settings_file("interface")


def _normalize_language(language: Any, default: str = "en") -> str:
    """
    Normalize language codes:
    - en/english -> en
    - zh/chinese/cn -> zh
    - fr/french -> fr
    - de/german/deutsch -> de
    - uk/ukrainian/ua -> uk
    - pl/polish/polski -> pl

    An unknown code falls back to ``default`` rather than raising, so this is
    also the gate that decides which languages exist at all: a locale shipped
    in ``web/locales/`` but missing here is silently served as English.
    """
    if language is None or language == "":
        language = default

    if isinstance(language, str):
        s = language.lower().strip().replace("_", "-")
        base = s.split("-", 1)[0]
        if s == "english" or base == "en":
            return "en"
        if s == "chinese" or base in {"zh", "cn"}:
            return "zh"
        if s == "french" or base == "fr":
            return "fr"
        if s in {"german", "deutsch"} or base == "de":
            return "de"
        if s == "ukrainian" or base in {"uk", "ua"}:
            return "uk"
        if s in {"polish", "polski"} or base == "pl":
            return "pl"

    # Fall back to default
    if isinstance(default, str):
        return _normalize_language(default, "en")
    return "en"


def _normalize_response_language(language: Any, default: str = "en") -> str:
    """Normalize only the wider model-output-language domain.

    Interface language remains en/zh. This function accepts the labels a user
    may have copied from an issue or another deployment, then maps region
    variants to their supported prompt-language base.
    """
    fallback = default if isinstance(default, str) and default.strip() else "en"
    fallback = _normalize_response_language(fallback, "en") if fallback != "en" else "en"

    if language is None or str(language).strip() == "":
        language = fallback

    if not isinstance(language, str):
        return fallback

    code = language.strip().lower().replace("_", "-")
    code = _RESPONSE_LANGUAGE_ALIASES.get(code, code)
    if code in SUPPORTED_RESPONSE_LANGUAGES:
        return code
    base = code.split("-", 1)[0]
    if base in SUPPORTED_RESPONSE_LANGUAGES:
        return base
    return fallback


def resolve_languages(saved: Mapping[str, Any]) -> dict[str, str]:
    """Normalize the two language fields out of a raw ``interface.json`` dict.

    ``response_language`` was split out of ``language`` after the two had been
    a single setting, so a file written before the split carries only
    ``language`` and must inherit it. That inheritance *is* the migration, and
    it lives here because this module owns the file's shape — both readers of
    ``interface.json`` (this module and the settings router, which layers its
    own superset of defaults on top) go through this one function so they can
    never disagree about what a legacy file means.

    ``_normalize_language`` already falls back to its ``default`` for a value
    that is missing, blank or unrecognized, so absence, ``null`` and junk all
    land on the interface language without a separate key-presence check.
    """
    language = _normalize_language(saved.get("language"), DEFAULT_UI_SETTINGS["language"])
    return {
        "language": language,
        "response_language": _normalize_response_language(saved.get("response_language"), language),
    }


def get_ui_settings() -> dict[str, Any]:
    """
    Read UI settings from interface.json with defaults.

    Returns:
        dict containing at least: {"theme": "...", "language": "...",
        "response_language": "..."}
    """
    settings_file = _interface_settings_file()
    if settings_file.exists():
        try:
            with open(settings_file, encoding="utf-8") as f:
                saved = json.load(f) or {}
            return {**DEFAULT_UI_SETTINGS, **saved, **resolve_languages(saved)}
        except Exception:
            # On any parse error, fall back to defaults (safe)
            return DEFAULT_UI_SETTINGS.copy()

    return DEFAULT_UI_SETTINGS.copy()


def sanitize_enabled_tools(value: Any) -> list[str]:
    """Normalize saved optional-tool names against the runtime catalog."""

    if not isinstance(value, list):
        return list(USER_TOGGLEABLE_TOOL_NAMES)
    allowed = set(USER_TOGGLEABLE_TOOL_NAMES)
    seen: set[str] = set()
    result: list[str] = []
    for name in value:
        if isinstance(name, str) and name in allowed and name not in seen:
            seen.add(name)
            result.append(name)
    return result


def get_enabled_optional_tools() -> list[str]:
    """Read the current user's enabled tools and apply the admin grant."""

    from deeptutor.multi_user.tool_access import allowed_optional_tools

    enabled = sanitize_enabled_tools(get_ui_settings().get("enabled_optional_tools"))
    allowed = allowed_optional_tools()
    if allowed is not None:
        enabled = [name for name in enabled if name in allowed]
    return enabled


def atomic_update(
    settings_file: Path, mutate: Callable[[dict[str, Any]], Mapping[str, Any]]
) -> dict[str, Any]:
    """Read, mutate and replace a settings file as one indivisible step.

    Takes the path rather than resolving it, so every writer of a given file
    shares one lock even though they resolve the path themselves — the settings
    router and the setup capability both write ``interface.json`` and a lock
    only one of them takes is not a lock. Measured with each module writing
    directly: six router writes racing six capability writes lost every one of
    the router's.

    ``mutate`` receives the raw stored mapping — never the defaults-merged view,
    since writing that back would freeze today's defaults as the user's explicit
    choices — and returns what should be on disk. The write is a temp-file
    rename, so a crash or a full disk leaves the previous file rather than a
    truncated one; a half-written ``interface.json`` is what would drop a user
    back to English and the default theme.
    """
    with _settings_lock(settings_file):
        stored: dict[str, Any] = {}
        if settings_file.exists():
            try:
                with open(settings_file, encoding="utf-8") as f:
                    loaded = json.load(f)
                if isinstance(loaded, dict):
                    stored = loaded
            except Exception:
                # A corrupt file is replaced rather than inherited: reads already
                # fall back to defaults, so preserving the broken bytes would only
                # keep the user stuck with settings that do not apply.
                stored = {}
        payload = dict(mutate(stored))
        settings_file.parent.mkdir(parents=True, exist_ok=True)
        fd, temp_name = tempfile.mkstemp(
            prefix=f".{settings_file.name}.", suffix=".tmp", dir=settings_file.parent
        )
        temp_path = Path(temp_name)
        try:
            with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
                json.dump(payload, f, ensure_ascii=False, indent=2)
                f.write("\n")
                f.flush()
                os.fsync(f.fileno())
            os.replace(temp_path, settings_file)
        finally:
            temp_path.unlink(missing_ok=True)
        return payload


def update_ui_settings(patch: Mapping[str, Any]) -> dict[str, Any]:
    """Merge ``patch`` into the stored settings, leaving every other field intact.

    Merged into the *raw* stored mapping rather than into
    :func:`get_ui_settings`, whose return value is defaults-merged. Writing that
    merged view back would materialise every current default as an explicit
    stored value, so a user who once changed their theme would silently stop
    following later changes to any other default — the file would already
    contain a frozen copy of the defaults as they were that day.

    Returns the mapping now on disk.
    """
    updates = dict(patch)

    def _mutate(stored: dict[str, Any]) -> dict[str, Any]:
        stored.update(updates)
        return stored

    return atomic_update(_interface_settings_file(), _mutate)


def replace_ui_settings(settings: Mapping[str, Any]) -> dict[str, Any]:
    """Replace the stored settings wholesale (reset, and full-document saves)."""
    payload = dict(settings)
    return atomic_update(_interface_settings_file(), lambda _stored: payload)


def set_ui_setting(key: str, value: Any) -> dict[str, Any]:
    """Persist one field, leaving every other field intact."""
    return update_ui_settings({key: value})


def get_ui_language(default: str = "en") -> str:
    """
    Get current UI language.

    Priority:
    1) interface.json
    2) provided default
    3) 'en'
    """
    settings = get_ui_settings()
    return _normalize_language(settings.get("language"), default)


def get_response_language(default: str = "en") -> str:
    """Get the preferred reader-facing model output language."""
    settings = get_ui_settings()
    return _normalize_response_language(settings.get("response_language"), default)