~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
"""Contract tests for the ``arxiv_api_request_gate`` policy utility.
Issue #4783: every ``export.arxiv.org`` API request must traverse one
process-wide monotonic 3-second single-flight gate.
The utility ``local_deep_research.utilities.arxiv_api`` is the sole policy
owner and must expose ``arxiv_api_request_gate()`` as a context manager:
entering marks a spaced start under the process-wide lock (single-flight,
at least three monotonic seconds between starts, failed starts still count
for spacing, lock always released).
Deterministic seams mirror the downloader gate naming so existing test
patches retarget cleanly: ``_arxiv_api_request_lock``,
``_last_request_started_at``, ``_monotonic``, ``_sleep``.
"""
import threading
import types
from collections.abc import Iterator
import pytest
from pytest_mock import MockerFixture
from local_deep_research.utilities import arxiv_api as arxiv_api_module
@pytest.fixture(autouse=True)
def fresh_arxiv_api_gate() -> Iterator[None]:
"""Reset the process-wide gate state around each test."""
with arxiv_api_module._arxiv_api_request_lock:
arxiv_api_module._last_request_started_at = None
yield
with arxiv_api_module._arxiv_api_request_lock:
arxiv_api_module._last_request_started_at = None
class TestArxivApiRequestGate:
"""Tests for the ``arxiv_api_request_gate`` context manager."""
def test_first_gated_start_begins_immediately(
self, mocker: MockerFixture
) -> None:
# Given a fresh process gate and a deterministic monotonic clock
starts: list[float] = []
mocker.patch.object(arxiv_api_module, "_monotonic", return_value=10.0)
hard_sleep = mocker.patch.object(arxiv_api_module, "_sleep")
# When the first gated request starts
with arxiv_api_module.arxiv_api_request_gate():
starts.append(arxiv_api_module._monotonic())
# Then the policy gate starts it immediately
assert starts == [10.0]
hard_sleep.assert_not_called()
def test_starts_are_spaced_process_wide(
self, mocker: MockerFixture
) -> None:
# Given a clock advanced only by policy sleep
now = 100.0
starts: list[float] = []
sleeps: list[float] = []
def monotonic() -> float:
return now
def sleep(duration: float) -> None:
nonlocal now
sleeps.append(duration)
now += duration
mocker.patch.object(
arxiv_api_module, "_monotonic", side_effect=monotonic
)
mocker.patch.object(arxiv_api_module, "_sleep", side_effect=sleep)
# When two independent gated requests start
with arxiv_api_module.arxiv_api_request_gate():
starts.append(now)
with arxiv_api_module.arxiv_api_request_gate():
starts.append(now)
# Then their starts are at least three seconds apart
assert starts == [100.0, 103.0]
assert sleeps == [3.0]
def test_concurrent_gated_starts_are_single_flight(
self, mocker: MockerFixture
) -> None:
# Given two gated bodies that would overlap without the gate lock
now = 200.0
active_requests = 0
maximum_active_requests = 0
call_count = 0
activity_lock = threading.Lock()
first_request_entered = threading.Event()
second_request_waiting_for_gate = threading.Event()
gate_lock = threading.Lock()
class ObservedLock:
def __enter__(self) -> "ObservedLock":
if gate_lock.locked():
second_request_waiting_for_gate.set()
gate_lock.acquire()
return self
def __exit__(
self,
_exc_type: type[BaseException] | None,
_exc_val: BaseException | None,
_exc_tb: types.TracebackType | None,
) -> None:
gate_lock.release()
def monotonic() -> float:
return now
def sleep(duration: float) -> None:
nonlocal now
now += duration
def gated_body() -> None:
nonlocal active_requests, call_count, maximum_active_requests
with arxiv_api_module.arxiv_api_request_gate():
with activity_lock:
call_count += 1
request_number = call_count
active_requests += 1
maximum_active_requests = max(
maximum_active_requests, active_requests
)
try:
if request_number == 1:
first_request_entered.set()
assert second_request_waiting_for_gate.wait(timeout=1)
finally:
with activity_lock:
active_requests -= 1
mocker.patch.object(
arxiv_api_module, "_arxiv_api_request_lock", ObservedLock()
)
mocker.patch.object(
arxiv_api_module, "_monotonic", side_effect=monotonic
)
mocker.patch.object(arxiv_api_module, "_sleep", side_effect=sleep)
first_thread = threading.Thread(target=gated_body)
second_thread = threading.Thread(target=gated_body)
# When both gated requests run concurrently
first_thread.start()
assert first_request_entered.wait(timeout=1)
second_thread.start()
first_thread.join(timeout=1)
second_thread.join(timeout=1)
# Then only one gated body is active at a time
assert not first_thread.is_alive()
assert not second_thread.is_alive()
assert second_request_waiting_for_gate.is_set()
assert maximum_active_requests == 1
def test_failed_start_still_counts_for_spacing(
self, mocker: MockerFixture
) -> None:
# Given a gated start whose body raises and a deterministic clock
now = 400.0
starts: list[float] = []
sleeps: list[float] = []
def monotonic() -> float:
return now
def sleep(duration: float) -> None:
nonlocal now
sleeps.append(duration)
now += duration
mocker.patch.object(
arxiv_api_module, "_monotonic", side_effect=monotonic
)
mocker.patch.object(arxiv_api_module, "_sleep", side_effect=sleep)
# When the failed start is followed by another gated request
with pytest.raises(ConnectionError):
with arxiv_api_module.arxiv_api_request_gate():
starts.append(now)
raise ConnectionError("connection refused")
with arxiv_api_module.arxiv_api_request_gate():
starts.append(now)
# Then the lock is released but the failed start still counts
assert starts == [400.0, 403.0]
assert sleeps == [3.0]