~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
"""Boolean query-string parameters keep ``parse_bool_arg``'s exact contract.
Ported from ``tests/web/utils/test_request_helpers.py`` on main (deleted by
the FastAPI migration, together with the helper it tested).
main centralised boolean query args in ``web/utils/request_helpers.py``::
def parse_bool_arg(name: str, default: bool = False) -> bool:
raw = request.args.get(name)
if raw is None:
return default
return raw.lower() == "true"
and the deleted file existed to lock that contract down against exactly the
"helpful" widenings someone reaches for later: ``"yes"``/``"1"``/``"on"`` are
NOT truthy, and whitespace is NOT stripped, so ``?flag=%20true%20`` is False.
A widened parser silently changes what a checked box means; a stripping one
diverges from every other reader of the same query string.
The port deleted the helper and inlined the pattern at each call site as
``request.query_params.get(name, "false").lower() == "true"``. That is the
same contract — but it is now several independent copies, none of them named,
none of them tested. Testing the helper is no longer possible; testing the
property is, so this file does it two ways:
1. **Census.** Every query-param comparison in the shipped source is located
by AST walk and classified. Ones in the ``parse_bool_arg`` shape are held
to its full contract; every other shape must appear in ``EXEMPT`` below
with a reason. That list is closed, so a *new* boolean read written in a
widened or stripping shape fails here rather than shipping.
2. **Oracle.** Each canonical site's comparison is then *executed* — the real
expression, unparsed from the real file, against a real
``starlette.datastructures.QueryParams`` — and its answer compared to
main's ``parse_bool_arg`` on the same input, for the whole truth table the
deleted file pinned. The oracle is what makes the census non-vacuous: it
fails on a widening the shape check might not anticipate.
The absent-value case is per-site: main's helper took an explicit ``default``
argument, the inline form encodes it as ``.get(name, "false")``. The oracle
reads that literal out of the AST and feeds it to the reference helper as
``default``, so the two stay comparable.
Checked while writing this file: all four ``EXEMPT`` sites are byte-identical
in shape to their pre-migration originals (``library_routes.py:343``,
``metrics_routes.py:2640``, ``benchmark_routes.py:645``,
``research_routes.py:1882`` on ``origin/main``). They are inherited quirks,
not port damage, and are recorded rather than "fixed" here.
"""
import ast
from pathlib import Path
from urllib.parse import quote
import pytest
from starlette.datastructures import QueryParams
import local_deep_research
SRC_ROOT = Path(local_deep_research.__file__).resolve().parent
# (file, param) -> why this comparison is not held to parse_bool_arg's shape.
EXEMPT = {
("research.py", "priority"): (
"not a boolean at all — `== 'diagnostic'` selects a log ordering. "
"Identical to main's research_routes.py:1882."
),
("benchmark.py", "include_settings"): (
"deliberately widened to ('1','true','yes','on') because the export "
"checkbox posts '1'. Identical to main's benchmark_routes.py:645, "
"which never used parse_bool_arg either."
),
("library.py", "favorites"): (
"case-SENSITIVE `== 'true'`, no .lower(). Inherited verbatim from "
"main's library_routes.py:343; the UI only ever sends lowercase."
),
("metrics.py", "include_summary"): (
"case-SENSITIVE `== 'true'`, no .lower(). Inherited verbatim from "
"main's metrics_routes.py:2640."
),
}
# ---------------------------------------------------------------------------
# main's helper, verbatim, as the oracle
# ---------------------------------------------------------------------------
def parse_bool_arg_reference(raw: str | None, default: bool = False) -> bool:
"""``web/utils/request_helpers.py::parse_bool_arg`` from main, with the
Flask ``request.args.get`` lookup lifted out so it can be driven with a
value instead of a request context."""
if raw is None:
return default
return raw.lower() == "true"
# The truth table from main's deleted test file, one row per test it had.
TRUTH_TABLE = [
("true", True), # test_value_true_lowercase
("TRUE", True), # test_value_true_uppercase
("True", True), # test_value_true_mixed_case
("false", False), # test_value_false
("", False), # test_empty_value_returns_false
("yes", False), # test_value_yes_returns_false
("1", False), # test_value_one_returns_false
("on", False), # test_value_on_returns_false
(" true ", False), # test_whitespace_padded_true_returns_false
]
# ---------------------------------------------------------------------------
# Locating the call sites
# ---------------------------------------------------------------------------
class _Site:
__slots__ = ("path", "lineno", "param", "default", "attrs", "compare")
def __init__(self, path, lineno, param, default, attrs, compare):
self.path = path
self.lineno = lineno
self.param = param
self.default = default
self.attrs = attrs
self.compare = compare
@property
def key(self):
return (self.path.name, self.param)
@property
def expr(self):
return ast.unparse(self.compare)
@property
def canonical(self):
"""The ``parse_bool_arg`` shape: ``....lower() == "true"``."""
node = self.compare
return (
"lower" in self.attrs
and len(node.ops) == 1
and isinstance(node.ops[0], ast.Eq)
and isinstance(node.comparators[0], ast.Constant)
and node.comparators[0].value == "true"
)
def __repr__(self):
rel = self.path.relative_to(SRC_ROOT)
return f"{rel}:{self.lineno} {self.param!r}"
def _is_query_params_get(node):
"""``<anything>.query_params.get(...)``"""
return (
isinstance(node, ast.Call)
and isinstance(node.func, ast.Attribute)
and node.func.attr == "get"
and isinstance(node.func.value, ast.Attribute)
and node.func.value.attr == "query_params"
)
def _unwrap_calls(node):
"""Peel ``x.a().b()`` down to the ``query_params.get()`` call, returning
``(that call or the innermost node, [method names applied to it])``."""
attrs = []
while isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute):
if _is_query_params_get(node):
return node, attrs
attrs.append(node.func.attr)
node = node.func.value
return node, attrs
def _bool_sites():
"""Every ``Compare`` in the shipped source whose left-hand side is a
(possibly method-chained) ``request.query_params.get(...)``.
Restricted to ``Compare`` nodes because that is the only shape a boolean
query arg can take — a bare ``.get()`` feeding a string parameter is not
a boolean read and is not this file's business.
"""
sites = []
for path in sorted(SRC_ROOT.rglob("*.py")):
try:
tree = ast.parse(path.read_text(encoding="utf-8"))
except SyntaxError: # pragma: no cover - shipped source parses
continue
for node in ast.walk(tree):
if not isinstance(node, ast.Compare):
continue
base, attrs = _unwrap_calls(node.left)
if not _is_query_params_get(base):
continue
param = (
base.args[0].value
if base.args and isinstance(base.args[0], ast.Constant)
else None
)
default = (
base.args[1].value
if len(base.args) > 1 and isinstance(base.args[1], ast.Constant)
else None
)
sites.append(_Site(path, node.lineno, param, default, attrs, node))
return sites
SITES = _bool_sites()
CANONICAL = [s for s in SITES if s.canonical and s.key not in EXEMPT]
# ---------------------------------------------------------------------------
# 1. Census
# ---------------------------------------------------------------------------
def test_the_walker_actually_finds_the_ported_call_sites():
"""Guard the guard. main's ``parse_bool_arg`` had three call sites
(``rag_routes.py`` x2, ``settings_routes.py``); their successors are the
first two entries below. If the walk silently found nothing, every
parametrised assertion in this file would collapse to zero tests.
"""
found = {s.key for s in CANONICAL}
for expected in [
("rag.py", "force_reindex"),
("settings.py", "force_refresh"),
("notes.py", "pinned_only"),
("news_flask_api.py", "use_cache"),
]:
assert expected in found, (
f"the AST walk no longer sees {expected}; found {sorted(found)}"
)
assert len(CANONICAL) >= 5, [repr(s) for s in CANONICAL]
def test_every_non_canonical_bool_read_is_a_recorded_exemption():
"""The closed half of the census. A boolean query param written in any
shape other than ``.lower() == "true"`` must be listed in ``EXEMPT``
with a reason — which is where a widening or a ``.strip()`` added later
gets caught, since the author has to justify it here first."""
unlisted = sorted(
repr(s) + f" -> {s.expr}"
for s in SITES
if not s.canonical and s.key not in EXEMPT
)
assert not unlisted, (
"query-param comparisons that are neither in parse_bool_arg's shape "
f"nor recorded in EXEMPT: {unlisted}"
)
def test_the_exemption_list_has_no_dead_entries():
"""An exemption for a call site that no longer exists hides the next
one written at the same place."""
live = {s.key for s in SITES}
assert not (set(EXEMPT) - live), (
f"EXEMPT names call sites that are gone: {sorted(set(EXEMPT) - live)}"
)
@pytest.mark.parametrize("site", CANONICAL, ids=repr)
def test_the_value_is_lowercased_and_not_stripped(site):
"""``.lower()`` gives the case-insensitivity main had; ``.strip()``
would give whitespace tolerance main deliberately did NOT have."""
assert "lower" in site.attrs, (
f"{site}: value is not lowercased, so ?{site.param}=TRUE stops "
f"working: {site.expr}"
)
assert "strip" not in site.attrs, (
f"{site}: whitespace is stripped, so ?{site.param}=%20true%20 now "
f"reads as true — main's helper explicitly did not: {site.expr}"
)
@pytest.mark.parametrize("site", CANONICAL, ids=repr)
def test_the_read_names_a_literal_parameter_and_default(site):
"""``.get(name)`` with no default returns ``None``, and ``None.lower()``
is an AttributeError — a 500 on an absent param."""
assert isinstance(site.param, str) and site.param, (
f"{site}: parameter name is not a literal: {site.expr}"
)
assert isinstance(site.default, str), (
f"{site}: no literal default; an absent ?{site.param} makes .lower() "
f"raise on None: {site.expr}"
)
# ---------------------------------------------------------------------------
# 2. Oracle
# ---------------------------------------------------------------------------
class _FakeRequest:
def __init__(self, query_params):
self.query_params = query_params
def _evaluate(site, query_string):
"""Execute the site's REAL comparison against a real QueryParams."""
base, _ = _unwrap_calls(site.compare.left)
root = base.func.value.value
assert isinstance(root, ast.Name), (
f"{site}: expected `<name>.query_params.get(...)`, got {site.expr}"
)
env = {root.id: _FakeRequest(QueryParams(query_string))}
# noqa S307: the compiled input is an AST node lifted out of this repo's
# own checked-in source, not user data. Executing the REAL expression is
# the point — a hand-written model of it would pass a widening that the
# shipped code does not have, which is exactly the failure this oracle
# exists to catch.
return eval( # noqa: S307
compile(ast.Expression(site.compare), "<site>", "eval"), env
)
@pytest.mark.parametrize("raw,expected", TRUTH_TABLE, ids=lambda v: repr(v))
@pytest.mark.parametrize("site", CANONICAL, ids=repr)
def test_a_present_value_matches_mains_helper(site, raw, expected):
"""The whole truth table from the deleted file, run against the shipped
expression rather than a model of it."""
got = _evaluate(site, f"{quote(site.param)}={quote(raw)}")
assert got is expected, (
f"{site}: ?{site.param}={raw!r} reads as {got}, main's "
f"parse_bool_arg says {expected}"
)
assert got is parse_bool_arg_reference(raw), "oracle disagrees with itself"
def test_each_default_still_matches_the_value_main_shipped():
"""The absent-value test below derives its expectation from the site's
OWN declared default, so it is self-consistent by construction: flipping
``.get(name, "false")`` to ``.get(name, "true")`` leaves it green
(verified by mutation). The default is business logic the AST cannot
infer — so pin it against what main actually shipped instead.
Sources on ``origin/main`` (all pre-migration):
* ``rag_routes.py:935,2598`` ``parse_bool_arg("force_reindex")`` -> False
* ``settings_routes.py:1756`` ``parse_bool_arg("force_refresh")`` -> False
* ``news/flask_api.py:265`` ``.get("use_cache", "true")`` -> True
* ``notes_routes.py:293`` ``.get("pinned_only", "")`` -> False
"""
expected = {
("rag.py", "force_reindex"): False,
("settings.py", "force_refresh"): False,
("news_flask_api.py", "use_cache"): True,
("notes.py", "pinned_only"): False,
}
for site in CANONICAL:
if site.key not in expected:
continue
got = site.default.lower() == "true"
assert got is expected[site.key], (
f"{site}: an absent ?{site.param} now defaults to {got}; main "
f"defaulted it to {expected[site.key]} — flipping this silently "
"changes what every existing client request means"
)
@pytest.mark.parametrize("site", CANONICAL, ids=repr)
def test_an_absent_value_returns_the_sites_own_default(site):
"""main: ``parse_bool_arg(name, default)`` returns ``default`` when the
param is absent. Inline, the default is the second ``.get()`` argument,
which then goes through the same ``== "true"`` comparison."""
got = _evaluate(site, "unrelated=value")
expected = parse_bool_arg_reference(None, site.default.lower() == "true")
assert got is expected, (
f"{site}: absent ?{site.param} reads as {got}; the declared default "
f"{site.default!r} means {expected}"
)
@pytest.mark.parametrize("site", CANONICAL, ids=repr)
def test_a_present_empty_value_beats_the_default(site):
"""``?flag=`` is PRESENT-but-empty, so the default never applies and the
answer is False even where the default is ``"true"``. main pinned this as
``test_empty_value_returns_false``: it is the one row where "absent" and
"empty" must not be conflated."""
assert _evaluate(site, f"{quote(site.param)}=") is False, (
f"{site}: ?{site.param}= fell back to the {site.default!r} default "
"instead of reading the empty value that was actually sent"
)