User Settings¶

def get_default_compaction_threshold(self) -> int:
    """The global default compaction threshold, in percent (80 until the
    user changes it).

    Read-only, like ``get_default_reasoning_effort``: conversation
    creation must not write, and a missing singleton row IS the default.
    """
    settings = self.db.query(UserSettings).first()
    value = settings.default_compaction_threshold if settings else None
    return value or DEFAULT_COMPACTION_THRESHOLD

def get_default_reasoning_effort(self) -> str:
    """The global default reasoning effort ("medium" until the user changes it).

    Read-only, like ``get_web_search_enabled``: callers on hot paths
    (conversation creation, arena turns) must not write, and a missing
    singleton row IS the default.
    """
    settings = self.db.query(UserSettings).first()
    value = settings.default_reasoning_effort if settings else None
    return value or DEFAULT_REASONING_EFFORT

def get_or_create(self) -> UserSettings:
    """Retrieve the singleton UserSettings record, creating if absent.

    Returns:
        UserSettings: The singleton settings entity (defaults applied on
        first creation: web_search_enabled=False, language="en",
        auto_update_enabled=True, inference_backend="auto").
    """
    settings = self.db.query(UserSettings).first()
    if not settings:
        logger.info("UserSettings not found, creating singleton with defaults")
        settings = UserSettings(web_search_enabled=False, language=DEFAULT_LANGUAGE)
        self.db.add(settings)
        self.db.flush()
        self.db.refresh(settings)
    return settings

def get_web_search_enabled(self) -> bool:
    """The global web-search default (False until the user opts in).

    Read-only: callers on hot paths (conversation creation, arena turns)
    must not write; a missing singleton row IS the default.
    """
    settings = self.db.query(UserSettings).first()
    return bool(settings.web_search_enabled) if settings else False

def set_auto_update_enabled(self, settings: UserSettings, value: bool) -> UserSettings:
    """Update the automatic-update preference (flushed, not committed).

    Args:
        settings: The singleton entity to update.
        value: New Boolean value (False refuses update checks entirely).

    Returns:
        UserSettings: Updated entity.
    """
    logger.info(f"Updating UserSettings.auto_update_enabled = {value}")
    settings.auto_update_enabled = value
    self.db.flush()
    self.db.refresh(settings)
    return settings

def set_default_compaction_threshold(self, settings: UserSettings, value: int) -> UserSettings:
    """Update the global default compaction threshold (flushed, not committed).

    Args:
        settings: The singleton entity to update.
        value: One of COMPACTION_THRESHOLDS (validated by the entity).

    Returns:
        UserSettings: Updated entity.

    Note:
        Existing conversations keep the threshold they copied at
        creation -- this only changes what the NEXT conversation inherits.
    """
    logger.info(f"Updating UserSettings.default_compaction_threshold = {value}")
    settings.default_compaction_threshold = value
    self.db.flush()
    self.db.refresh(settings)
    return settings

def set_default_reasoning_effort(self, settings: UserSettings, value: str) -> UserSettings:
    """Update the global default reasoning effort (flushed, not committed).

    Args:
        settings: The singleton entity to update.
        value: One of REASONING_EFFORT_LEVELS (validated by the entity).

    Returns:
        UserSettings: Updated entity.

    Note:
        Existing conversations keep the level they copied at creation --
        this only changes what the NEXT conversation inherits (and what
        arena turns, which have no conversation row, run at).
    """
    logger.info(f"Updating UserSettings.default_reasoning_effort = {value}")
    settings.default_reasoning_effort = value
    self.db.flush()
    self.db.refresh(settings)
    return settings

def set_inference_backend(self, settings: UserSettings, value: str) -> UserSettings:
    """Update the inference-backend preference (flushed, not committed).

    Args:
        settings: The singleton entity to update.
        value: One of INFERENCE_BACKENDS (validated by the entity).

    Returns:
        UserSettings: Updated entity.

    Note:
        The engine is a process-level singleton read once per boot, so a
        change here only takes effect on the next backend start.
    """
    logger.info(f"Updating UserSettings.inference_backend = {value}")
    settings.inference_backend = value
    self.db.flush()
    self.db.refresh(settings)
    return settings

def set_language(self, settings: UserSettings, value: str) -> UserSettings:
    """Update the interface language (flushed, not committed).

    Args:
        settings: The singleton entity to update.
        value: One of the supported language codes (validated by the entity).

    Returns:
        UserSettings: Updated entity.
    """
    logger.info(f"Updating UserSettings.language = {value}")
    settings.language = value
    self.db.flush()
    self.db.refresh(settings)
    return settings

def set_web_search_enabled(self, settings: UserSettings, value: bool) -> UserSettings:
    """Update the global web-search default (flushed, not committed).

    Args:
        settings: The singleton entity to update.
        value: New Boolean value.

    Returns:
        UserSettings: Updated entity.
    """
    logger.info(f"Updating UserSettings.web_search_enabled = {value}")
    settings.web_search_enabled = value
    self.db.flush()
    self.db.refresh(settings)
    return settings