~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
"""
Environment-only settings that are loaded early and never stored in database.
These settings are:
1. Required before database initialization
2. Used for testing/CI configuration
3. System bootstrap configuration
They are accessed through SettingsManager but always read from environment variables.
Why some settings must be environment-only:
- Bootstrap settings (the plaintext-SQLite fallback policy) are needed to initialize the database itself
- Database configuration settings must be available before connecting to the database
- Testing flags need to be checked before any database operations occur
- CI/CD variables control build-time behavior before the application starts
These settings cannot be stored in the database because they are prerequisites for
accessing the database. This creates a bootstrapping requirement where certain
configuration must come from the environment to establish the system state needed
to access persisted settings.
"""
import os
import re
from pathlib import Path
from typing import Any, Dict, Optional, List, Set, TypeVar, Generic
from abc import ABC, abstractmethod
from loguru import logger
from .exceptions import (
EnvironmentPathNotFoundError,
EnvironmentValueRangeError,
InvalidEnvironmentValueError,
MissingEnvironmentVariableError,
SettingsValueError,
)
T = TypeVar("T")
class EnvSetting(ABC, Generic[T]):
"""Base class for all environment settings."""
def __init__(
self,
key: str,
description: str,
default: Optional[T] = None,
required: bool = False,
deprecated_env_var: Optional[str] = None,
):
self.key = key
# Auto-generate env_var from key
# e.g., "testing.test_mode" -> "LDR_TESTING_TEST_MODE"
self.env_var = "LDR_" + key.upper().replace(".", "_")
self.description = description
self.default = default
self.required = required
self.deprecated_env_var = deprecated_env_var
def get_value(
self, *, strict: bool = False, check_env: bool = True
) -> Optional[T]:
"""Get the value from environment with type conversion."""
raw = self._get_raw_value() if check_env else None
if raw is None:
if self.required and self.default is None:
raise MissingEnvironmentVariableError(self.env_var)
return self.default
if strict:
return self._convert_value(raw, strict=True)
return self._convert_value(raw)
@abstractmethod
def _convert_value(self, raw: str, *, strict: bool = False) -> T:
"""Convert raw string value to the appropriate type."""
pass
def _get_raw_value(self) -> Optional[str]:
"""Get raw string value from environment.
Checks the canonical env var first. If not set and a deprecated
alias is configured, falls back to the deprecated name with a
warning guiding users to migrate.
"""
value = os.environ.get(self.env_var)
if value is not None:
return value
if self.deprecated_env_var:
deprecated_value = os.environ.get(self.deprecated_env_var)
if deprecated_value is not None:
logger.warning(
f"Environment variable '{self.deprecated_env_var}' is deprecated "
f"and will be removed in a future release. "
f"Please use '{self.env_var}' instead."
)
return deprecated_value
return None
@property
def is_set(self) -> bool:
"""Check if the environment variable is set."""
return self.env_var in os.environ
def __repr__(self) -> str:
"""String representation for debugging."""
return f"{self.__class__.__name__}(key='{self.key}', env_var='{self.env_var}')"
class BooleanSetting(EnvSetting[bool]):
"""Boolean environment setting."""
def __init__(
self,
key: str,
description: str,
default: bool = False,
deprecated_env_var: Optional[str] = None,
):
super().__init__(
key, description, default, deprecated_env_var=deprecated_env_var
)
def _convert_value(self, raw: str, *, strict: bool = False) -> bool:
"""Convert string to boolean."""
if strict:
normalized = raw.strip().lower()
if normalized in ("true", "1", "yes", "on", "enabled"):
return True
if normalized in ("false", "0", "no", "off", "disabled", ""):
return False
raise ValueError("Expected a boolean token")
return raw.lower() in ("true", "1", "yes", "on", "enabled")
class StringSetting(EnvSetting[str]):
"""String environment setting."""
def __init__(
self,
key: str,
description: str,
default: Optional[str] = None,
required: bool = False,
deprecated_env_var: Optional[str] = None,
):
super().__init__(
key,
description,
default,
required,
deprecated_env_var=deprecated_env_var,
)
def _convert_value(self, raw: str, *, strict: bool = False) -> str:
"""Return string value as-is."""
return raw
#: Plain ASCII decimal integer, optionally negative. Deliberately NOT what
#: ``int()`` accepts: ``int`` also takes underscore separators (``"1_0"``
#: -> 10), a leading ``"+"``, surrounding whitespace, and any Unicode
#: decimal digit (``"٣"`` -> 3). For a setting that defines a trust
#: boundary those spellings are a review hazard -- ``"1_0"`` reads as one
#: hop and means ten -- so ``strict_digits`` settings reject them. The
#: optional ``-`` is matched (rather than rejected outright) so a negative
#: value still reaches the ``min_value`` check and gets the specific
#: "below minimum" range error instead of a generic parse error.
_STRICT_INTEGER_LITERAL = re.compile(r"-?[0-9]+")
class IntegerSetting(EnvSetting[int]):
"""Integer environment setting.
``raise_on_validation_error`` makes malformed and out-of-range values
propagate instead of falling back through ``SettingsRegistry``.
``strict_digits`` restricts accepted spellings to a plain ASCII
decimal literal (see ``_STRICT_INTEGER_LITERAL``).
An empty value is treated as UNSET in every mode: ``LDR_X=""`` falls
back to the default rather than failing, because orchestrators
(Compose, k8s manifests, Unraid templates) routinely emit an empty
string for an unconfigured variable -- the repo-wide contract pinned
by ``tests/test_config_env_var_contracts.py::
test_empty_env_var_is_treated_as_unset_not_as_false``.
"""
def __init__(
self,
key: str,
description: str,
default: Optional[int] = None,
min_value: Optional[int] = None,
max_value: Optional[int] = None,
deprecated_env_var: Optional[str] = None,
raise_on_validation_error: bool = False,
strict_digits: bool = False,
):
super().__init__(
key,
description,
default,
deprecated_env_var=deprecated_env_var,
)
self.min_value = min_value
self.max_value = max_value
self.raise_on_validation_error = raise_on_validation_error
self.strict_digits = strict_digits
def _convert_value(
self, raw: str, *, strict: bool = False
) -> Optional[int]:
"""Convert string to integer with validation."""
candidate = raw.strip()
if not candidate:
logger.warning(
f"Empty value for {self.env_var}, treating it as unset and using default: {self.default}"
)
return self.default
value: Optional[int] = None
parse_error: Optional[ValueError] = None
if self.strict_digits and not _STRICT_INTEGER_LITERAL.fullmatch(
candidate
):
parse_error = ValueError(
f"invalid literal for int() with base 10: {raw!r}"
)
else:
try:
value = int(candidate)
except ValueError as exc:
parse_error = exc
if parse_error is not None:
if strict:
raise parse_error
if self.raise_on_validation_error:
raise InvalidEnvironmentValueError(
self.env_var, raw, expected_type="integer"
) from parse_error
logger.warning(
f"Invalid integer value '{raw}' for {self.env_var}, using default: {self.default}"
)
return self.default
if self.min_value is not None and value < self.min_value:
raise EnvironmentValueRangeError(
self.env_var, value, min_val=self.min_value
)
if self.max_value is not None and value > self.max_value:
raise EnvironmentValueRangeError(
self.env_var, value, max_val=self.max_value
)
return value
class PathSetting(StringSetting):
"""Path environment setting with validation."""
def __init__(
self,
key: str,
description: str,
default: Optional[str] = None,
must_exist: bool = False,
create_if_missing: bool = False,
):
super().__init__(key, description, default)
self.must_exist = must_exist
self.create_if_missing = create_if_missing
def get_value(
self, *, strict: bool = False, check_env: bool = True
) -> Optional[str]:
"""Get path value with optional validation/creation."""
path_str = super().get_value(strict=strict, check_env=check_env)
if path_str is None or not check_env:
return path_str
if strict and not path_str.strip():
raise ValueError("Expected a nonempty path")
# Use pathlib for path operations
path = Path(path_str).expanduser()
# Expand environment variables manually since pathlib doesn't have expandvars
# Note: os.path.expandvars is kept here as there's no pathlib equivalent
# noqa: PLR0402 - Suppress pathlib check for this line
path_str = os.path.expandvars(str(path))
path = Path(path_str).resolve()
if (
strict
and self.create_if_missing
and path.exists()
and not path.is_dir()
):
raise ValueError("Expected a directory")
if self.create_if_missing and not path.exists():
# Lazy import: this module is loaded very early (bootstrap
# env-only settings), before the database and app are
# initialized, so importing security at module load time
# risks an import cycle.
from ..security.directory_creation import (
DirectoryCreationSecurityError,
create_directory,
)
try:
create_directory(
path,
context=f"env-configured path setting '{self.key}'",
)
except DirectoryCreationSecurityError:
if strict:
raise ValueError(
"Could not prepare configured path"
) from None
raise
except OSError:
if strict:
raise
logger.warning("Failed to create directory")
elif self.must_exist and not path.exists():
# Only raise if explicitly required to exist
raise EnvironmentPathNotFoundError(self.env_var, path)
return str(path)
class SecretSetting(StringSetting):
"""Secret/sensitive environment setting."""
def __init__(
self,
key: str,
description: str,
default: Optional[str] = None,
required: bool = False,
):
super().__init__(key, description, default, required)
def __repr__(self) -> str:
"""Hide the value in string representation."""
return f"SecretSetting(key='{self.key}', value=***)"
def __str__(self) -> str:
"""Hide the value in string conversion."""
value = "SET" if self.is_set else "NOT SET"
return f"{self.key}=<{value}>"
class EnumSetting(EnvSetting[str]):
"""Enum-style setting with allowed values."""
def __init__(
self,
key: str,
description: str,
allowed_values: Set[str],
default: Optional[str] = None,
case_sensitive: bool = False,
deprecated_env_var: Optional[str] = None,
):
super().__init__(
key, description, default, deprecated_env_var=deprecated_env_var
)
self.allowed_values = allowed_values
self.case_sensitive = case_sensitive
# Store lowercase versions for case-insensitive comparison
if not case_sensitive:
self._allowed_lower = {v.lower() for v in allowed_values}
# Create a mapping from lowercase to original case
self._canonical_map = {v.lower(): v for v in allowed_values}
def _convert_value(self, raw: str, *, strict: bool = False) -> str:
"""Convert and validate value against allowed values."""
if self.case_sensitive:
if raw not in self.allowed_values:
raise InvalidEnvironmentValueError(
self.env_var, raw, list(self.allowed_values)
)
return raw
# Case-insensitive matching
raw_lower = raw.lower()
if raw_lower not in self._allowed_lower:
raise InvalidEnvironmentValueError(
self.env_var, raw, list(self.allowed_values)
)
# Return the canonical version (from allowed_values)
return self._canonical_map[raw_lower]
class SettingsRegistry:
"""Registry for all environment settings."""
def __init__(self):
self._settings: Dict[str, EnvSetting] = {}
self._categories: Dict[str, List[EnvSetting]] = {}
def register_category(self, category: str, settings: List[EnvSetting]):
"""Register a category of settings."""
self._categories[category] = settings
for setting in settings:
self._settings[setting.key] = setting
def get(self, key: str, default: Optional[Any] = None) -> Any:
"""
Get a setting value.
Args:
key: Setting key (e.g., "testing.test_mode")
default: Default value if not set or on error
Returns:
Setting value or default
"""
setting = self._settings.get(key)
if not setting:
return default
try:
value = setting.get_value()
# Use provided default if setting returns None
return value if value is not None else default
except ValueError:
if (
isinstance(setting, IntegerSetting)
and setting.raise_on_validation_error
):
raise
logger.warning(
"Validation error for setting '{}', using default", key
)
return default
def get_strict(
self,
key: str,
default: Optional[Any] = None,
*,
check_env: bool = True,
) -> Any:
"""Read for a settings manager without hiding invalid configuration.
Missing optional settings retain their registered or caller default.
Disabling environment lookup also disables path resolution/creation.
The legacy bootstrap ``get`` API retains its historical behavior.
"""
setting = self._settings.get(key)
if setting is None:
return default
source = "default"
if check_env and (
setting.env_var in os.environ
or (
setting.deprecated_env_var is not None
and setting.deprecated_env_var in os.environ
)
):
source = "environment"
# A custom converter has no strict-read contract. Do not call it and
# accidentally accept a fallback or suppress its validation failure.
reasons = {
BooleanSetting: "expected a boolean token",
IntegerSetting: "expected an integer within the allowed range",
EnumSetting: "expected one of the declared choices",
PathSetting: "could not resolve or prepare the configured path",
StringSetting: "required value is missing",
SecretSetting: "required value is missing",
}
reason = reasons.get(type(setting))
if reason is None:
raise SettingsValueError(
key,
source=source,
reason="unsupported environment setting type",
)
try:
value = setting.get_value(strict=True, check_env=check_env)
except (ValueError, TypeError, OSError, RuntimeError):
# Converters and filesystem errors can contain configured secrets
# or paths. Raise outside the handler so no raw exception is kept
# as the exception context or emitted in the traceback.
pass
else:
return value if value is not None else default
raise SettingsValueError(key, source=source, reason=reason)
def get_setting_object(self, key: str) -> Optional[EnvSetting]:
"""Get the setting object itself for introspection."""
return self._settings.get(key)
def is_env_only(self, key: str) -> bool:
"""Check if a key is an env-only setting."""
return key in self._settings
def get_env_var(self, key: str) -> Optional[str]:
"""Get the environment variable name for a key."""
setting = self._settings.get(key)
return setting.env_var if setting else None
def get_all_env_vars(self) -> Dict[str, str]:
"""Get all environment variables and descriptions."""
return {
setting.env_var: setting.description
for setting in self._settings.values()
}
def get_category_settings(self, category: str) -> List[EnvSetting]:
"""Get all settings in a category."""
return self._categories.get(category, [])
def get_bootstrap_vars(self) -> Dict[str, str]:
"""Get bootstrap environment variables (bootstrap + db_config)."""
result = {}
for category in ["bootstrap", "db_config"]:
for setting in self._categories.get(category, []):
result[setting.env_var] = setting.description
return result
def get_testing_vars(self) -> Dict[str, str]:
"""Get testing environment variables."""
result = {}
for setting in self._categories.get("testing", []):
result[setting.env_var] = setting.description
return result
def list_all_settings(self) -> List[str]:
"""List all registered setting keys."""
return list(self._settings.keys())
# Export list for better IDE discovery
__all__ = [
"EnvSetting",
"BooleanSetting",
"StringSetting",
"IntegerSetting",
"PathSetting",
"SecretSetting",
"EnumSetting",
"SettingsRegistry",
]