DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""
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)