~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""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}")