~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
"""
Utilities for managing settings in the programmatic API.
This module provides functions to create settings snapshots for the API
without requiring database access, reusing the same mechanisms as the
web interface.
"""
import copy
from typing import Any
from loguru import logger
from ..llm.providers.base import normalize_provider
from ..settings import SettingsManager
from ..settings.base import ISettingsManager
from ..settings.env_registry import registry as env_registry
from ..settings.exceptions import SettingsValueError
from ..settings.manager import (
UI_ELEMENT_TO_SETTING_TYPE as UI_ELEMENT_TO_SETTING_TYPE,
validate_imported_setting_value,
check_env_setting,
get_typed_setting_value,
is_operator_only_setting,
is_valid_setting_key,
)
from ..utilities.type_utils import to_bool, unwrap_setting
class InMemorySettingsManager(ISettingsManager):
"""
In-memory settings manager that doesn't require database access.
This is used for the programmatic API to provide settings without
needing a database connection.
"""
def __init__(self):
"""Initialize with default settings from JSON file."""
# Create a base manager to get default settings
self._base_manager = SettingsManager(db_session=None)
self._settings = {}
self._load_defaults()
def _get_typed_value(
self,
setting_data: dict[str, Any],
value: Any,
*,
key: str | None = None,
) -> Any:
"""Validate a stored value without applying environment overrides."""
if not isinstance(setting_data, dict):
raise SettingsValueError(
key or "<in-memory>",
source="value",
reason="invalid setting metadata",
)
return get_typed_setting_value(
key if key is not None else setting_data.get("key", "<in-memory>"),
value,
setting_data.get("ui_element", "text"),
check_env=False,
)
def _load_defaults(self):
"""Load default settings from the JSON file."""
# Get default settings from the base manager
defaults = self._base_manager.default_settings
# Convert to the format expected by get_all_settings
for key, setting_data in defaults.items():
self._settings[key] = setting_data.copy()
# Load search engine configurations from individual JSON files
from importlib import resources
import json
try:
# Load search engines from defaults/settings/search_engines/
search_engines_dir = resources.files(
"local_deep_research.defaults.settings"
).joinpath("search_engines")
if search_engines_dir.exists() and search_engines_dir.is_dir():
for json_file in search_engines_dir.glob("*.json"):
try:
engine_settings = json.loads(
json_file.read_text(encoding="utf-8-sig")
)
# Merge into main settings
for key, setting_data in engine_settings.items():
if key not in self._settings:
self._settings[key] = setting_data.copy()
except Exception:
logger.warning(
f"Failed to load search engine config from {json_file.name}"
)
except Exception:
logger.warning("Failed to load search engine configs")
def _read_setting_value(
self,
key: str,
setting_data: dict[str, Any],
default: Any = None,
check_env: bool = True,
) -> Any:
"""Read the selected value or report invalid configuration."""
if not isinstance(setting_data, dict):
raise SettingsValueError(
key, source="value", reason="invalid setting metadata"
)
ui_element = setting_data.get("ui_element", "text")
return get_typed_setting_value(
key,
setting_data.get("value"),
ui_element,
default=default,
check_env=check_env,
)
def get_setting(
self, key: str, default: Any = None, check_env: bool = True
) -> Any:
"""Read a typed value, or a namespace when no exact entry exists.
An environment override for a key with no entry and no declared
type is returned as the raw string, as ``SettingsManager`` does.
"""
if not isinstance(key, str) or not key:
return default
if env_registry.is_env_only(key):
return env_registry.get_strict(key, default, check_env=check_env)
if key in self._settings:
setting_data = self._settings[key]
return self._read_setting_value(
key, setting_data, default=default, check_env=check_env
)
# Preserve exact-entry precedence and the DB reader's scalar-only
# treatment of operator-owned paths. Malformed legacy children do
# not turn a missing leaf into a namespace.
if not is_operator_only_setting(key):
children = {
child.removeprefix(f"{key}."): self._read_setting_value(
child, data, default=default, check_env=check_env
)
for child, data in self._settings.items()
if is_valid_setting_key(child) and child.startswith(f"{key}.")
}
if children:
return children
if check_env:
env_value = check_env_setting(key)
if env_value is not None:
metadata = self._base_manager.default_settings.get(key)
if isinstance(metadata, dict):
return get_typed_setting_value(
key,
None,
metadata.get("ui_element", "text"),
default=default,
)
# Same as SettingsManager.get_setting: with no declared type
# there is nothing to validate against, so the override is
# returned unconverted. Typed keys still raise above.
logger.warning(
"Setting '{}' has env var override but is not in "
"defaults — returning raw string without type "
"conversion. Add this setting to a defaults JSON "
"file with a ui_element type to enable proper "
"type conversion.",
key,
)
return env_value
return default
def set_setting(self, key: str, value: Any, commit: bool = True) -> bool:
"""Set a setting value (in memory only)."""
if key in self._settings:
# Validate and convert the value to the correct type
typed_value = self._get_typed_value(
self._settings[key], value, key=key
)
self._settings[key]["value"] = typed_value
return True
return False
def get_all_settings(
self,
bypass_cache: bool = False,
include_environment_overrides: bool = True,
strict: bool = False,
) -> dict[str, Any]:
"""Validate effective settings, or return raw storage for repair.
Effective reads validate stored values without changing their saved
representation. Only active environment overrides replace values.
Raw exports skip validation and preserve the stored metadata.
"""
result = copy.deepcopy(self._settings)
if include_environment_overrides:
for key, setting_data in result.items():
value = self._read_setting_value(key, setting_data)
if check_env_setting(key) is not None:
setting_data["value"] = value
setting_data["editable"] = False
return result
def load_from_defaults_file(
self,
commit: bool = True,
preserve_environment_locked: bool = False,
) -> None:
"""Reload defaults while honoring environment-lock preservation.
No ``**kwargs`` passthrough (see the ``ISettingsManager`` contract,
#5841): the in-memory store has no settings lock, so the
``override_locked`` bypass is meaningless here — and now also
structurally rejected.
"""
preserved_values = (
{
key: copy.deepcopy(value["value"])
for key, value in self._settings.items()
if isinstance(value, dict)
and "value" in value
and check_env_setting(key) is not None
}
if preserve_environment_locked
else {}
)
self._settings.clear()
self._load_defaults()
for key, value in preserved_values.items():
if key in self._settings:
self._settings[key]["value"] = value
def create_or_update_setting(
self, setting: dict[str, Any] | Any, commit: bool = True
) -> Any | None:
"""Create or update a setting (in memory only)."""
if isinstance(setting, dict) and "key" in setting:
key = setting["key"]
# Validate metadata even when an optional value is absent.
typed_value = self._get_typed_value(setting, setting.get("value"))
if "value" in setting:
setting = setting.copy() # Don't modify the original
setting["value"] = typed_value
self._settings[key] = setting
return setting
return None
def delete_setting(
self, key: str, commit: bool = True, override_locked: bool = False
) -> bool:
"""Delete a setting (in memory only).
``override_locked`` is accepted to satisfy the ``ISettingsManager``
contract (#5738) and otherwise ignored: the in-memory store has no
settings lock, so there is nothing for it to override.
"""
if key in self._settings:
del self._settings[key]
return True
return False
def get_bool_setting(
self, key: str, default: bool = False, check_env: bool = True
) -> bool:
"""Get a setting value as a boolean."""
value = self.get_setting(key, default, check_env)
return to_bool(value, default)
def get_settings_snapshot(self, strict: bool = False) -> dict[str, Any]:
"""Get a simplified settings snapshot with just key-value pairs."""
all_settings = self.get_all_settings(strict=strict)
snapshot = {}
for key, setting in all_settings.items():
if isinstance(setting, dict) and "value" in setting:
snapshot[key] = setting["value"]
else:
snapshot[key] = setting
return snapshot
def import_settings(
self,
settings_data: dict[str, Any],
commit: bool = True,
overwrite: bool = True,
delete_extra: bool = False,
preserve_environment_locked: bool = False,
override_locked: bool = False,
) -> None:
"""Import settings from a dictionary.
Conversion failures leave the live settings unchanged. Values that
fail schema validation retain the existing skip-and-preserve policy.
``override_locked`` is accepted to satisfy the ``ISettingsManager``
contract (#5738) and otherwise ignored: the in-memory store has no
settings lock, so there is nothing for it to override.
"""
# Schema-aware import (#5589) — validates untrusted file values
# against the current schema; see validate_imported_setting_value's
# docstring for the trusted-vs-untrusted rationale (values retained
# from existing in-memory state are trusted here, not validated).
defaults_for_import = self._base_manager.default_settings
# Rows are replaced, not mutated, during import. Stage those
# replacements so a later conversion error cannot expose a partial
# import or leave live settings cleared by delete_extra.
pending_settings = self._settings.copy()
# Under `delete_extra=True`, entries cleared below must still be
# restorable for keys whose imported value is rejected by
# validation — mirroring the DB manager, where a rejected key keeps
# its existing row (the key is retained before validation runs).
prior_settings = (
{key: copy.deepcopy(value) for key, value in self._settings.items()}
if delete_extra
else None
)
if delete_extra:
preserved = (
{
key: copy.deepcopy(value)
for key, value in self._settings.items()
if check_env_setting(key) is not None
}
if preserve_environment_locked
else {}
)
pending_settings = preserved
for key, value in settings_data.items():
existing_setting = pending_settings.get(key)
preserve_value = (
preserve_environment_locked
and check_env_setting(key) is not None
and isinstance(existing_setting, dict)
and "value" in existing_setting
)
if preserve_value and not isinstance(value, dict):
# A bare-scalar import carries no metadata to merge; keep
# the stored env-locked entry untouched.
continue
if overwrite or key not in pending_settings or preserve_value:
# Ensure proper type handling for imported settings
setting_values = (
value.copy() if isinstance(value, dict) else value
)
if (
isinstance(value, dict)
and "value" in value
and not preserve_value
):
default_meta = defaults_for_import.get(key)
if (
default_meta is not None
and not preserve_value
and validate_imported_setting_value(
key, value["value"], default_meta
)
is not None
):
# The file-supplied value is invalid under the
# current defaults schema (#5589); skip the entry
# and keep any prior entry (mirrors the DB manager,
# which leaves the existing row in place).
logger.warning(
"Skipping import of setting {!r}: value is "
"invalid under the current defaults schema",
key,
)
if prior_settings is not None and key in prior_settings:
pending_settings[key] = prior_settings[key]
continue
typed_value = self._get_typed_value(
value, value["value"], key=key
)
setting_values["value"] = typed_value
if preserve_value:
setting_values["value"] = copy.deepcopy(
existing_setting["value"]
)
pending_settings[key] = setting_values
self._settings = pending_settings
def get_default_settings_snapshot() -> dict[str, Any]:
"""
Get a complete settings snapshot with default values.
This uses the same mechanism as the web interface but without
requiring database access. Environment variables are checked
for overrides.
Returns:
Dict mapping setting keys to their values and metadata
"""
manager = InMemorySettingsManager()
return manager.get_all_settings()
def create_settings_snapshot(
overrides: dict[str, Any] | None = None,
base_settings: dict[str, Any] | None = None,
**kwargs,
) -> dict[str, Any]:
"""
Create a settings snapshot for the programmatic API.
Args:
overrides: Dict of setting overrides (e.g., {"llm.provider": "openai"})
This is the most common use case - pass a dict of settings to override.
Internal snapshot keys (names starting with ``_``, such
as the ``openai_endpoint`` key-owner marker) cannot be
set here and raise ``ValueError``: they are run metadata
written by the code that owns them (the marker only ever
comes from the endpoint-key binder).
A ``llm.openai_endpoint.url`` override keeps the stored
``llm.openai_endpoint.api_key`` only on the same origin,
or on the origin of a set ``LDR_LLM_OPENAI_ENDPOINT_URL``;
a key from ``LDR_LLM_OPENAI_ENDPOINT_API_KEY`` is kept
only on the env URL's origin, or with no env URL the
saved URL's (see config/openai_endpoint_binding.py). A
key in the same dict is the key for that URL.
base_settings: Base settings dict (defaults to get_default_settings_snapshot())
Rarely needed - only for advanced use cases.
**kwargs: Common setting shortcuts:
- provider: Maps to "llm.provider"
- api_key: Maps to "llm.{provider}.api_key"
- temperature: Maps to "llm.temperature"
- max_search_results: Maps to "search.max_results"
- search_engines: Maps to enabled search engines
Returns:
Complete settings snapshot for use with the API
Examples:
# Most common - pass overrides as first argument
settings = create_settings_snapshot({"search.tool": "wikipedia"})
# Or use named parameter
settings = create_settings_snapshot(overrides={"llm.provider": "openai"})
# Use kwargs shortcuts
settings = create_settings_snapshot(provider="openai", temperature=0.7)
# Advanced - provide custom base settings
settings = create_settings_snapshot(
overrides={"search.tool": "wikipedia"},
base_settings=my_custom_defaults
)
"""
# Start with base settings or defaults
if base_settings is None:
settings = get_default_settings_snapshot()
else:
settings = copy.deepcopy(base_settings)
# Apply overrides if provided.
#
# ``llm.openai_endpoint.url`` is not written verbatim: the stored
# ``llm.openai_endpoint.api_key`` belongs to the URL it was configured
# for, so the override goes through the endpoint-key binder instead
# (below), which records the key's owner and withholds the key when the
# override is on another origin (see
# config/openai_endpoint_binding.py). A verbatim write left the stored
# key paired with whatever URL the override named.
url_override_pending = False
endpoint_url_override = None
if overrides:
for key, value in overrides.items():
if isinstance(key, str) and key.startswith("_"):
# Internal snapshot keys are run metadata written by the
# code that owns them — never caller-settable through this
# channel. In particular the openai_endpoint key-owner
# marker (config/openai_endpoint_binding.py) records which
# origin the stored API key belongs to; letting an override
# write it would let a caller steer the stored key to a URL
# of their choosing.
raise ValueError(
f"{key!r} is an internal snapshot key and cannot be set "
"through overrides; names starting with '_' are written "
"by the code that owns them only."
)
if key == "llm.openai_endpoint.url":
url_override_pending = True
endpoint_url_override = value
continue
if key in settings:
if isinstance(settings[key], dict) and "value" in settings[key]:
settings[key]["value"] = value
else:
settings[key] = value
else:
# Create a simple setting entry for unknown keys
# Infer ui_element from value type
ui_element = "text" # default
if isinstance(value, bool):
ui_element = "checkbox"
elif isinstance(value, (int, float)):
ui_element = "number"
elif isinstance(value, dict):
ui_element = "json"
settings[key] = {"value": value, "ui_element": ui_element}
# Handle common kwargs shortcuts
if "provider" in kwargs:
provider = kwargs["provider"]
if "llm.provider" in settings:
settings["llm.provider"]["value"] = provider
else:
settings["llm.provider"] = {"value": provider}
# Handle api_key if provided
if "api_key" in kwargs:
api_key = kwargs["api_key"]
api_key_setting = f"llm.{provider}.api_key"
if api_key_setting in settings:
settings[api_key_setting]["value"] = api_key
else:
settings[api_key_setting] = {"value": api_key}
if "temperature" in kwargs:
if "llm.temperature" in settings:
settings["llm.temperature"]["value"] = kwargs["temperature"]
else:
settings["llm.temperature"] = {"value": kwargs["temperature"]}
if "max_search_results" in kwargs:
if "search.max_results" in settings:
settings["search.max_results"]["value"] = kwargs[
"max_search_results"
]
else:
settings["search.max_results"] = {
"value": kwargs["max_search_results"]
}
# Add any other common shortcuts here...
if url_override_pending:
from ..config.openai_endpoint_binding import (
bind_openai_endpoint_override,
effective_openai_endpoint_url,
)
# A key named in the same call belongs to that call's URL — the
# same rule as the ``openai_endpoint_url=`` + ``api_key=`` pair in
# ``_init_search_system``, which decides this through
# ``normalize_provider`` (case/whitespace-insensitive). It replaces
# the stored key, so nothing stored travels to the overridden URL.
explicit_key = ""
if overrides:
candidate = overrides.get("llm.openai_endpoint.api_key")
if isinstance(candidate, str) and candidate.strip():
explicit_key = candidate.strip()
call_provider = kwargs.get("provider")
if (
not explicit_key
and isinstance(call_provider, str)
and normalize_provider(call_provider) == "openai_endpoint"
and isinstance(kwargs.get("api_key"), str)
and kwargs["api_key"].strip()
):
explicit_key = kwargs["api_key"].strip()
if "llm.openai_endpoint.url" not in settings:
# Match the entry shape the generic override path leaves
# behind (an envelope), so an operator ``LDR_*`` override of
# this key keeps winning on reads: environment values are
# operator policy (see ``effective_openai_endpoint_url``).
settings["llm.openai_endpoint.url"] = {
"value": effective_openai_endpoint_url(settings),
"ui_element": "text",
}
# A ``None`` override in the generic path keeps the entry and stores
# a ``None`` value (reads then fall back to the provider default),
# while the binder reads ``None`` as "keep the current URL"; write
# ``""`` instead, which reads as "unset" the same way and cannot be
# misread as "no change".
bind_openai_endpoint_override(
settings,
"" if endpoint_url_override is None else endpoint_url_override,
explicit_key=explicit_key,
keep_envelope=True,
)
return settings
def extract_setting_value(
settings_snapshot: dict[str, Any], key: str, default: Any = None
) -> Any:
"""
Extract a setting value from a settings snapshot.
Args:
settings_snapshot: Settings snapshot dict
key: Setting key (e.g., "llm.provider")
default: Default value if not found
Returns:
The setting value
"""
if settings_snapshot is None:
return default
if key in settings_snapshot:
setting = settings_snapshot[key]
return unwrap_setting(setting)
return default
def extract_bool_setting(
settings_snapshot: dict[str, Any], key: str, default: bool = False
) -> bool:
"""
Extract a boolean setting value from a settings snapshot.
This is a convenience wrapper around extract_setting_value that
handles string-to-boolean conversion.
Args:
settings_snapshot: Settings snapshot dict
key: Setting key (e.g., "local_search_normalize_vectors")
default: Default boolean value if not found
Returns:
Boolean value of the setting
"""
value = extract_setting_value(settings_snapshot, key, default)
return to_bool(value, default)