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.

25.3 KB
Raw Blame
"""
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)