~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
"""
Protocol-based interface tests for SettingsManager.
Ported from ``tests/web/services/test_settings_manager_protocol.py`` (deleted
in the Flask->FastAPI migration). The only translation is the consumer
module: main's ``research_library/routes/rag_routes.py`` became
``web/routers/rag.py`` on this branch. The contract being pinned -- that the
SettingsManager the RAG routes import is the unified
``settings.manager.SettingsManager``, which alone has ``get_bool_setting``
and ``get_settings_snapshot`` -- is unchanged.
These tests define and verify the contract that SettingsManager must fulfill
for consumers like web/routers/rag.py. Using Python's Protocol (PEP 544) enables:
- Static type checking with mypy to catch wrong imports at development time
- Runtime verification with @runtime_checkable
- Clear documentation of required interface
This prevents regressions like issue #1877 where the wrong SettingsManager
was imported, causing 'object has no attribute' errors at runtime.
"""
from typing import Any, Protocol, runtime_checkable
from unittest.mock import Mock
@runtime_checkable
class RagRoutesSettingsProtocol(Protocol):
"""
Protocol defining the SettingsManager interface required by web/routers/rag.py.
This protocol specifies the exact methods that web/routers/rag.py calls on
SettingsManager. Any class used as a SettingsManager in web/routers/rag.py
MUST implement all these methods.
Usage in web/routers/rag.py:
- get_setting(): Called throughout for retrieving settings
- get_bool_setting(): Called for boolean settings (e.g. the auto-index gate)
- get_settings_snapshot(): Called for background thread operations
"""
def get_setting(
self, key: str, default: Any = None, check_env: bool = True
) -> Any:
"""Retrieve a setting value by key."""
...
def get_bool_setting(self, key: str, default: bool = False) -> bool:
"""Retrieve a setting value as a boolean."""
...
def get_settings_snapshot(self) -> dict[str, Any]:
"""Get a snapshot of all settings as a flat dictionary."""
...
class TestSettingsManagerProtocolCompliance:
"""
Tests verifying SettingsManager implements the required protocol.
These tests use Python's @runtime_checkable Protocol to verify that
the SettingsManager class implements all required methods with the
correct signatures.
"""
def test_settings_manager_implements_protocol(self):
"""
Verify settings.manager.SettingsManager implements protocol.
This is the single unified SettingsManager used throughout the app.
"""
from local_deep_research.settings.manager import (
SettingsManager,
)
manager = SettingsManager()
# Runtime protocol check - this verifies the class has all required methods
assert isinstance(manager, RagRoutesSettingsProtocol), (
"settings.manager.SettingsManager must implement "
"RagRoutesSettingsProtocol. Missing methods will cause runtime errors "
"in web/routers/rag.py. See issue #1877."
)
class TestSettingsManagerImportIdentity:
"""
Tests verifying the correct SettingsManager is imported in web/routers/rag.py.
These tests check that web/routers/rag.py imports SettingsManager from
settings.manager (the unified implementation).
"""
def test_rag_routes_imports_correct_settings_manager(self):
"""
Verify web/routers/rag.py imports SettingsManager from settings.manager.
This test checks the actual imported class identity, ensuring that
web/routers/rag.py uses the correct SettingsManager that has all required
methods (get_bool_setting, get_settings_snapshot).
"""
from local_deep_research.web.routers import rag as rag_routes
from local_deep_research.settings.manager import (
SettingsManager as ExpectedManager,
)
# Get the SettingsManager class that rag_routes is using
# It should be imported at module level or used in functions
assert hasattr(rag_routes, "SettingsManager"), (
"web/routers/rag.py should have SettingsManager available. "
"Check the import statements."
)
# Verify it's the correct class
assert rag_routes.SettingsManager is ExpectedManager, (
f"web/routers/rag.py imports SettingsManager from wrong module. "
f"Expected: {ExpectedManager.__module__}.{ExpectedManager.__name__}, "
f"Got: {rag_routes.SettingsManager.__module__}.{rag_routes.SettingsManager.__name__}. "
f"This will cause 'has no attribute' errors. See issue #1877."
)
def test_rag_routes_settings_manager_has_required_methods(self):
"""
Verify the SettingsManager in rag_routes has all methods it calls.
This is a defense-in-depth test that checks the imported class
has all the methods that web/routers/rag.py actually calls.
"""
from local_deep_research.web.routers import rag as rag_routes
manager_class = rag_routes.SettingsManager
manager = manager_class()
# Methods called in web/routers/rag.py
required_methods = [
("get_setting", True), # (method_name, is_callable)
("get_bool_setting", True),
("get_settings_snapshot", True),
]
for method_name, should_be_callable in required_methods:
assert hasattr(manager, method_name), (
f"web/routers/rag.py's SettingsManager missing '{method_name}'. "
f"This method is called in web/routers/rag.py and will cause "
f"AttributeError at runtime. See issue #1877."
)
if should_be_callable:
attr = getattr(manager, method_name)
assert callable(attr), (
f"web/routers/rag.py's SettingsManager.{method_name} is not callable. "
f"Expected a method, got {type(attr)}."
)
class TestSettingsManagerMethodSignatures:
"""
Tests verifying method signatures match expected usage patterns.
These tests ensure that the methods not only exist but accept the
arguments that web/routers/rag.py passes to them.
"""
def test_get_bool_setting_accepts_key_and_default(self):
"""
Verify get_bool_setting accepts (key, default) arguments.
web/routers/rag.py calls: settings.get_bool_setting("key", True)
"""
from local_deep_research.settings.manager import (
SettingsManager,
)
mock_session = Mock()
mock_query = Mock()
mock_query.filter.return_value.all.return_value = []
mock_session.query.return_value = mock_query
manager = SettingsManager(db_session=mock_session)
# This should not raise TypeError
result = manager.get_bool_setting(
"research_library.auto_index_enabled", True
)
assert isinstance(result, bool)
def test_get_settings_snapshot_returns_mutable_dict(self):
"""
Verify get_settings_snapshot returns a dict that can be modified.
web/routers/rag.py modifies the snapshot: snapshot["_username"] = username
"""
from local_deep_research.settings.manager import (
SettingsManager,
)
mock_session = Mock()
mock_query = Mock()
mock_query.all.return_value = []
mock_session.query.return_value = mock_query
manager = SettingsManager(db_session=mock_session)
snapshot = manager.get_settings_snapshot()
# Should be a dict
assert isinstance(snapshot, dict)
# Should be mutable (web/routers/rag.py adds keys to it)
snapshot["_username"] = "testuser"
snapshot["_db_password"] = "testpass"
assert snapshot["_username"] == "testuser"
assert snapshot["_db_password"] == "testpass"
def test_get_setting_accepts_check_env_parameter(self):
"""
Verify get_setting accepts check_env parameter.
web/routers/rag.py calls: settings.get_setting("key", default, check_env=True)
"""
from local_deep_research.settings.manager import (
SettingsManager,
)
mock_session = Mock()
mock_query = Mock()
mock_query.filter.return_value.all.return_value = []
mock_session.query.return_value = mock_query
manager = SettingsManager(db_session=mock_session)
# These should not raise TypeError
result1 = manager.get_setting("some.key", "default", check_env=True)
result2 = manager.get_setting("some.key", "default", check_env=False)
# Should return the default when key not found
assert result1 == "default"
assert result2 == "default"
class TestSettingsManagerHasAllMethods:
"""
Tests verifying that the unified SettingsManager has all required methods.
"""
def test_settings_manager_has_all_methods(self):
"""Verify settings.manager.SettingsManager has all expected methods."""
from local_deep_research.settings.manager import (
SettingsManager,
)
manager = SettingsManager()
expected_methods = [
"get_setting",
"get_bool_setting",
"get_settings_snapshot",
"get_all_settings",
"set_setting",
"delete_setting",
]
for method in expected_methods:
assert hasattr(manager, method), (
f"settings.manager.SettingsManager should have {method}"
)
class TestProtocolUsageInTypeChecking:
"""
Tests demonstrating how to use the protocol for type checking.
These tests show patterns that can be used elsewhere in the codebase
to ensure type safety when working with SettingsManager.
"""
def test_function_accepting_protocol(self):
"""
Demonstrate a function that accepts any SettingsManager implementing protocol.
This pattern can be used in web/routers/rag.py to ensure type safety:
def get_rag_service(settings: RagRoutesSettingsProtocol) -> RAGService:
enabled = settings.get_bool_setting("auto_index", True)
...
"""
from local_deep_research.settings.manager import (
SettingsManager,
)
def requires_protocol(settings: RagRoutesSettingsProtocol) -> bool:
"""Function that requires the protocol."""
return settings.get_bool_setting("test.key", False)
mock_session = Mock()
mock_query = Mock()
mock_query.filter.return_value.all.return_value = []
mock_session.query.return_value = mock_query
manager = SettingsManager(db_session=mock_session)
# This should work because SettingsManager implements the protocol
result = requires_protocol(manager)
assert isinstance(result, bool)
def test_protocol_enables_mock_verification(self):
"""
Demonstrate using protocol to create properly-shaped mocks.
When mocking SettingsManager, the protocol ensures mocks have
all required methods.
"""
def create_mock_settings() -> RagRoutesSettingsProtocol:
"""Create a mock that satisfies the protocol."""
mock = Mock(spec=RagRoutesSettingsProtocol)
mock.get_setting.return_value = "test_value"
mock.get_bool_setting.return_value = True
mock.get_settings_snapshot.return_value = {"key": "value"}
return mock
mock_settings = create_mock_settings()
# Verify the mock satisfies the protocol
assert hasattr(mock_settings, "get_setting")
assert hasattr(mock_settings, "get_bool_setting")
assert hasattr(mock_settings, "get_settings_snapshot")
# Use the mock
assert mock_settings.get_bool_setting("test", False) is True
assert mock_settings.get_settings_snapshot() == {"key": "value"}