Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

10.7 KB
Raw Blame
"""Shared thread-local storage for settings context

This module provides a single thread-local storage instance that can be
shared across different modules to maintain settings context in threads.
"""

import threading
from contextlib import contextmanager

from ..settings.manager import get_typed_setting_value, is_valid_setting_key
from ..utilities.type_utils import to_bool


class NoSettingsContextError(Exception):
    """Raised when settings context is not available in a thread."""

    pass


# Shared thread-local storage for settings context
_thread_local = threading.local()

# Sentinel distinguishing "key absent from snapshot" from "key present with
# value None". Using None for both collapses legitimately-stored null values
# (e.g. embeddings.openai.dimensions, which defaults to JSON null) into the
# "not found" path, raising NoSettingsContextError in Flask request threads
# that have no thread-local context. See #4208.
_NOT_FOUND = object()

# Sentinel distinguishing "caller supplied no default" from "caller
# explicitly wants None when the key is absent". Before #5984, None did
# double duty for both, so the natural spelling of "this setting is
# optional" — default=None — raised NoSettingsContextError instead of
# returning None (the trap behind #5331 and #5766). Mirrors _NOT_FOUND
# above for the lookup half of the same function.
_UNSET = object()


def set_settings_context(settings_context):
    """Set a settings context for the current thread."""
    _thread_local.settings_context = settings_context


def clear_settings_context():
    """Clear the settings context for the current thread.

    Should be called in a finally block after set_settings_context() to prevent
    context from leaking to subsequent tasks when threads are reused in a pool.
    """
    if hasattr(_thread_local, "settings_context"):
        del _thread_local.settings_context


def get_settings_context():
    """Get the settings context for the current thread."""
    if hasattr(_thread_local, "settings_context"):
        return _thread_local.settings_context
    return None


@contextmanager
def settings_context(ctx):
    """Context manager that sets and clears settings context automatically.

    Ensures cleanup even if an exception occurs, preventing context leaks
    when threads are reused in a pool.

    Example:
        with settings_context(my_settings):
            run_research()
    """
    set_settings_context(ctx)
    try:
        yield
    finally:
        clear_settings_context()


def get_setting_from_snapshot(
    key,
    default=_UNSET,
    username=None,
    settings_snapshot=None,
):
    """Get setting from context only - no database access from threads.

    Args:
        key: Setting key to retrieve
        default: Default value if setting not found. Pass ``None``
            explicitly to make the setting optional — ``None`` is
            returned when the key is absent. Omit ``default`` to
            require a value: a missing key then raises, unless a thread
            settings context is bound (its lookup result — ``None``
            for a key it is missing — is returned instead).
        username: Username (unused, kept for backward compatibility)
        settings_snapshot: Optional settings snapshot dict

    Returns:
        Setting value or default

    Raises:
        NoSettingsContextError: If the key is not found in the snapshot,
            no thread settings context is available, and no default was
            provided
    """
    # First check if we have settings_snapshot passed directly.
    # _NOT_FOUND (not None) is the absence sentinel so a key whose stored
    # value is None is still treated as found.  See #4208.
    value = _NOT_FOUND
    if settings_snapshot and key in settings_snapshot:
        raw = settings_snapshot[key]
        # Handle both full format {"value": x} and simplified format (just x)
        if isinstance(raw, dict) and "value" in raw:
            value = get_typed_setting_value(
                key,
                raw["value"],
                raw.get("ui_element", "text"),
            )
        else:
            value = raw
    # Search for child keys.
    elif settings_snapshot:
        for full_key, v in settings_snapshot.items():
            if not full_key.startswith(f"{key}."):
                continue
            # Skip malformed rows (e.g. legacy "foo." / "foo..") so a stray
            # legacy key can't wrap a leaf read into an [object Object] dict
            # (#4840) — mirrors SettingsManager.get_setting's filter on the DB
            # read path.
            if not is_valid_setting_key(full_key):
                continue
            child = full_key.removeprefix(f"{key}.")
            # Handle both full format {"value": x} and simplified format (just x)
            if isinstance(v, dict) and "value" in v:
                v = get_typed_setting_value(
                    full_key, v["value"], v.get("ui_element", "text")
                )
            # else: v is already the raw value from simplified snapshot
            if value is _NOT_FOUND:
                value = {child: v}
            else:
                value[child] = v

    if value is not _NOT_FOUND:
        # Extract value from dict structure if needed
        return value

    # Check if we have a settings context in this thread.
    #
    # This storage is a bare ``threading.local()``, so on a POOLED thread it
    # outlives the task that set it. If a future caller ever sets a context
    # from a handler offloaded onto the shared worker pool (anyio/
    # ``asyncio.to_thread``), the next task landing on that thread would read
    # the previous user's value. Every current ``set_settings_context`` call
    # site runs on a dedicated thread or clears in a ``finally``, so this is
    # not reachable today — but the failure mode is a silent cross-user
    # value, so validate identity rather than relying on that staying true.
    #
    # Mirrors the self-heal that already protects
    # ``ThreadLocalSessionManager.get_session``: on mismatch treat the
    # context as absent and fall through to the default.
    ctx = getattr(_thread_local, "settings_context", None)
    if ctx:
        ctx_username = getattr(ctx, "username", None)
        from ..utilities.request_context import get_current_username

        current_username = get_current_username()
        if (
            ctx_username is not None
            and current_username is not None
            and ctx_username != current_username
        ):
            from loguru import logger

            logger.warning(
                "Discarding stale thread-local settings context for "
                f"'{key}': built for user {ctx_username!r} but the current "
                f"request is {current_username!r}. Falling through to the "
                "default rather than serving another user's value."
            )
        else:
            # Never forward _UNSET: the context's get_setting would return
            # the sentinel itself for a missing key, leaking it to callers.
            value = ctx.get_setting(key, None if default is _UNSET else default)
            # Extract value from dict structure if needed (same as above)
            if isinstance(value, dict) and "value" in value:
                return value["value"]
            return value

    # If a default was provided, return it — including an explicit None,
    # which reads as "optional" (#5984). _UNSET, not None, means "no
    # default was supplied" and falls through to the raise below.
    if default is not _UNSET:
        from loguru import logger

        logger.debug(
            f"Setting '{key}' not found in snapshot or context, using default"
        )
        return default

    # Only raise the exception if no default was provided
    raise NoSettingsContextError(
        f"No settings context available in thread for key '{key}'. All settings must be passed via settings_snapshot."
    )


def get_bool_setting_from_snapshot(
    key,
    default=False,
    username=None,
    settings_snapshot=None,
):
    """Get a boolean setting from snapshot, handling string conversion.

    This centralizes the string-to-boolean conversion logic for settings
    retrieved from snapshots. Handles various truthy string representations
    that may come from API requests, config files, or SQLite.

    Args:
        key: Setting key to retrieve
        default: Default boolean value if setting not found
        username: Username (unused, kept for backward compatibility)
        settings_snapshot: Optional settings snapshot dict

    Returns:
        Boolean value of the setting
    """
    value = get_setting_from_snapshot(
        key,
        default,
        username=username,
        settings_snapshot=settings_snapshot,
    )

    return to_bool(value, default)


def _get_optional_setting(
    param_dict,
    param_name,
    setting_key,
    settings_snapshot,
    *,
    cast=None,
    check="not_none",
):
    """Fetch a setting and, when present, write it into ``param_dict``.

    Consolidates the recurring
    ``try: get_setting_from_snapshot(...) ... except NoSettingsContextError: pass``
    pattern used by the LLM provider ``create_llm`` factories.
    ``NoSettingsContextError`` is silently swallowed because these
    parameters are always optional.

    Args:
        param_dict: Target dict (e.g. ``llm_params``) mutated in place.
        param_name: Key to set on ``param_dict`` when a value is present.
        setting_key: Dotted settings path to retrieve.
        settings_snapshot: Snapshot dict passed through to
            :func:`get_setting_from_snapshot`.
        cast: Optional callable applied to the value before assignment
            (e.g. ``int`` for ``max_tokens``).
        check: ``"not_none"`` (default) writes the value when it is not
            ``None``. ``"falsy"`` writes only when the value is truthy.
            The falsy mode is an intentional safeguard for fields where
            a falsy stored value (``organization=""``) must be dropped
            rather than forwarded.

    The ``max_tokens`` blocks that resolve their value through
    ``compute_max_tokens`` / ``get_context_window_for_provider`` (rather
    than a single settings lookup) do not fit this helper and are left
    in place. The ``api_base`` block in ``openai.py`` is also left in
    place because it wraps an SSRF validation side effect.
    """
    try:
        value = get_setting_from_snapshot(
            setting_key,
            default=None,
            settings_snapshot=settings_snapshot,
        )
    except NoSettingsContextError:
        return
    if check == "not_none":
        if value is not None:
            param_dict[param_name] = cast(value) if cast else value
    elif check == "falsy":
        if value:
            param_dict[param_name] = cast(value) if cast else value
    else:
        raise ValueError(f"Unknown check mode: {check!r}")