Skip to content

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

11.0 KB
Raw Blame
#!/usr/bin/env python
"""
System Setup and Initialization
Combines user directory initialization and port configuration management.
"""

import json
import logging
from pathlib import Path
from typing import Any

import yaml

from deeptutor.services.config.loader import (
    DEFAULT_EXPLORE_CONTEXT_PARAMS,
    DEFAULT_QUESTION_PARAMS,
    DEFAULT_RESEARCH_PARAMS,
)
from deeptutor.services.path_service import get_path_service

# Initialize logger for setup operations
_setup_logger = None

DEFAULT_INTERFACE_SETTINGS = {
    # "snow" is the pure-white neutral theme, shown as "Default" in the UI.
    "theme": "snow",
    "language": "en",
    "sidebar_description": "✨ Data Intelligence Lab @ HKU",
    "sidebar_nav_order": {
        "start": ["/", "/history", "/knowledge-bases", "/notebooks"],
        "learnResearch": ["/question", "/solver", "/research", "/co_writer"],
    },
}


DEFAULT_MAIN_SETTINGS = {
    "system": {
        "language": "en",
    },
    "logging": {
        "level": "WARNING",
        "save_to_file": True,
        "console_output": True,
    },
    "tools": {
        "exec": {
            "allowed_roots": ["./data/user"],
        },
        "web_search": {
            "enabled": True,
        },
    },
    "capabilities": {
        "solve": {
            "max_rounds": 12,
            "max_replans": 2,
        },
        "research": {
            "researching": {
                "note_agent_mode": "auto",
                "tool_timeout": 60,
                "tool_max_retries": 2,
                "paper_search_years_limit": 3,
            },
        },
        "question": {
            "exploring": {
                "max_iterations": 8,
                "tool_summarizer": {
                    "enabled": True,
                    "max_tokens": 800,
                },
            },
        },
    },
}

DEFAULT_AGENTS_SETTINGS: dict[str, Any] = {
    "capabilities": {
        "solve": {"temperature": 0.3, "max_tokens": 8192},
        "research": {"temperature": 0.5, "max_tokens": 12000},
        "question": {"temperature": 0.7, "max_tokens": 4096},
        "co_writer": {"temperature": 0.7, "max_tokens": 4096},
        "visualize": {"temperature": 0.15, "max_tokens": 16000},
        # A book spine is one JSON payload holding a concept graph plus every
        # chapter, and a reasoning model pays for its hidden tokens out of the
        # same budget. 4096 (the old, unreachable global fallback) truncated
        # both (#1316). Matched to `research` rather than pushed higher: the
        # same "long structured output" shape, the same accepted risk against
        # providers that cap `max_tokens`, and the low-effort retry in
        # `services/llm/structured_retry.py` is what actually rescues a starved
        # round.
        "book": {"temperature": 0.5, "max_tokens": 12000},
        "chat": {
            "temperature": 0.2,
            "responding": {"max_tokens": 8000},
        },
    },
    "tools": {
        "brainstorm": {"temperature": 0.8, "max_tokens": 2048},
    },
    "services": {
        "personalization": {"temperature": 0.5, "max_tokens": 8192},
    },
    "plugins": {
        "vision_solver": {"temperature": 0.3, "max_tokens": 12000},
        "math_animator": {"temperature": 0.4, "max_tokens": 12000},
        # A whole Remotion lesson in one reply, plus a reasoning model's thinking.
        "video_lesson": {"temperature": 0.5, "max_tokens": 48000},
    },
    # Settings' "test this model" probe. A reasoning model spends its budget
    # thinking before it answers, so the 1024 that sufficed for a chat model
    # returned an empty completion and the probe reported the model broken.
    "diagnostics": {
        "llm_probe": {"temperature": 0.1, "max_tokens": 4096},
    },
}

# Per-stage budgets are seeded from the same tables the pipelines read, so a
# fresh agents.yaml shows every knob that governs a run and Settings can edit
# it. Derived rather than copied: two lists of the same numbers is how a
# default and its seed drift apart, which is the shape of #1316.
for _capability, _stages in (
    ("question", DEFAULT_QUESTION_PARAMS),
    ("research", DEFAULT_RESEARCH_PARAMS),
    ("explore_context", DEFAULT_EXPLORE_CONTEXT_PARAMS),
):
    _section = DEFAULT_AGENTS_SETTINGS["capabilities"].setdefault(_capability, {})
    for _stage, _values in _stages.items():
        _section.setdefault(_stage, dict(_values))
del _capability, _stages, _section, _stage, _values


def _get_setup_logger():
    """Get logger for setup operations"""
    global _setup_logger
    if _setup_logger is None:
        _setup_logger = logging.getLogger(__name__)
    return _setup_logger


# ============================================================================
# User Directory Initialization
# ============================================================================


def init_user_directories(project_root: Path | None = None) -> None:
    """
    Initialize essential user data files if they don't exist.

    This function uses lazy initialization - directories are created on-demand
    when files are saved, rather than pre-creating all directories at startup.

    Only essential configuration files (like settings/interface.json) are
    created at startup if they don't exist.

    Directory structure (created on-demand by each module):
    data/user/
    ├── chat_history.db
    ├── logs/
    ├── settings/
    │   ├── interface.json
    │   ├── main.yaml
    │   └── agents.yaml
    └── workspace/
        ├── notebook/
        ├── memory/
        ├── co-writer/
        ├── book/
        └── chat/
            ├── chat/
            ├── deep_solve/
            ├── deep_question/
            ├── deep_research/
            ├── math_animator/
            └── _detached_exec/

    Args:
        project_root: Project root directory (ignored, kept for API compatibility)
    """
    # Use PathService for all paths
    path_service = get_path_service()
    path_service.ensure_all_directories()

    # Only initialize essential configuration files
    # Directories will be created on-demand when files are saved
    _ensure_essential_settings(path_service)


def _ensure_essential_settings(path_service) -> None:
    """
    Ensure essential settings files exist.

    This is the minimal initialization needed at startup.
    All other directories are created on-demand when files are saved.
    """
    interface_file = path_service.get_settings_file("interface")
    _write_json_if_missing(interface_file, DEFAULT_INTERFACE_SETTINGS)

    main_file = path_service.get_runtime_config_file("main")
    _write_yaml_if_missing(main_file, DEFAULT_MAIN_SETTINGS)

    agents_file = path_service.get_runtime_config_file("agents")
    _write_yaml_if_missing(agents_file, DEFAULT_AGENTS_SETTINGS)

    try:
        from deeptutor.services.config import ensure_runtime_settings_files

        ensure_runtime_settings_files()
    except Exception as e:
        _get_setup_logger().warning(f"Failed to initialise runtime JSON settings: {e}")

    _seed_default_personas()


def _seed_default_personas() -> None:
    """Seed the bundled persona presets into the admin workspace on first run.

    Fresh installs otherwise show an empty Persona list even though the docs
    advertise peer / teacher / research-assistant presets (issue #659). Seeding
    the admin workspace surfaces them as read-only presets for every user.
    Best-effort — never blocks startup.
    """
    try:
        from deeptutor.multi_user.paths import get_admin_path_service
        from deeptutor.services.persona.service import PersonaService

        admin_personas = get_admin_path_service().get_workspace_dir() / "personas"
        seeded = PersonaService(root=admin_personas).seed_presets()
        if seeded:
            _get_setup_logger().info(f"Seeded default personas: {', '.join(seeded)}")
    except Exception as e:
        _get_setup_logger().warning(f"Failed to seed default personas: {e}")


def _write_json_if_missing(file_path: Path, payload: dict) -> None:
    """Write JSON defaults once; never overwrite user-managed files."""
    if file_path.exists():
        return
    try:
        file_path.parent.mkdir(parents=True, exist_ok=True)
        with open(file_path, "w", encoding="utf-8") as f:
            json.dump(payload, f, indent=2, ensure_ascii=False)
        _get_setup_logger().info(f"Created default settings: {file_path}")
    except Exception as e:
        _get_setup_logger().warning(f"Failed to create default JSON file {file_path}: {e}")


def _write_yaml_if_missing(file_path: Path, payload: dict) -> None:
    """Write YAML defaults once; never overwrite user-managed files."""
    if file_path.exists():
        return
    try:
        file_path.parent.mkdir(parents=True, exist_ok=True)
        with open(file_path, "w", encoding="utf-8") as f:
            yaml.safe_dump(payload, f, sort_keys=False, allow_unicode=True)
        _get_setup_logger().info(f"Created default settings: {file_path}")
    except Exception as e:
        _get_setup_logger().warning(f"Failed to create default YAML file {file_path}: {e}")


# ============================================================================
# Port Configuration Management
# ============================================================================
# Ports are configured via data/user/settings/system.json.
# ============================================================================


def get_backend_port(project_root: Path | None = None) -> int:
    """
    Get backend port from runtime settings.

    Returns:
        Backend port number (default: 8001)
    """
    try:
        from deeptutor.services.config.launch_settings import load_launch_settings

        return load_launch_settings(project_root).backend_port
    except Exception as exc:
        logger = _get_setup_logger()
        logger.warning(f"Failed to load backend port from runtime settings: {exc}")
        return 8001


def get_frontend_port(project_root: Path | None = None) -> int:
    """
    Get frontend port from runtime settings.

    Returns:
        Frontend port number (default: 3782)
    """
    try:
        from deeptutor.services.config.launch_settings import load_launch_settings

        return load_launch_settings(project_root).frontend_port
    except Exception as exc:
        logger = _get_setup_logger()
        logger.warning(f"Failed to load frontend port from runtime settings: {exc}")
        return 3782


def get_ports(project_root: Path | None = None) -> tuple[int, int]:
    """
    Get both backend and frontend ports from configuration.

    Args:
        project_root: Project root directory (if None, will try to detect)

    Returns:
        Tuple of (backend_port, frontend_port)

    Raises:
        SystemExit: If ports are not configured
    """
    backend_port = get_backend_port(project_root)
    frontend_port = get_frontend_port(project_root)
    return (backend_port, frontend_port)


__all__ = [
    # User directory initialization
    "init_user_directories",
    # Port configuration
    "get_backend_port",
    "get_frontend_port",
    "get_ports",
]