~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
[build-system]
requires = ["pdm-backend>=2.4.3"]
build-backend = "pdm.backend"
[project]
name = "local-deep-research"
dynamic = ["version"]
description = "AI-powered research assistant with deep, iterative analysis using LLMs and web searches"
readme = "README.md"
requires-python = ">=3.12,<3.15"
license = {file = "LICENSE"}
authors = [
{name = "LearningCircuit", email = "[email protected]"},
{name = "HashedViking", email = "[email protected]"},
{name = "djpetti", email = "[email protected]"},
]
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
dependencies = [
"langchain~=1.2", # lock pulls 1.3.9: GHSA-gr75-jv2w-4656 fix
"langchain-community~=0.4",
"langchain-core~=1.2",
"langchain-ollama~=1.0",
"langchain-openai~=1.1",
"langchain-anthropic~=1.3", # lock pulls 1.4.6: GHSA-gr75-jv2w-4656 fix
"openai>=2", # direct dep: error_handling/openai_compat_errors.py imports exception classes
"httpx>=0.27", # direct dep: error_handling/openai_compat_errors.py imports ConnectError/ReadTimeout
"python-dateutil~=2.9",
"typing-extensions~=4.15",
"justext~=3.0",
"readabilipy~=0.3",
"trafilatura>=2.0,<2.3", # 2.3.x markdown-escapes underscores in pre/code content, corrupting stored extracted text (tests/research_library/downloaders/test_html_downloader.py::TestExtractContent::test_pre_blocks_extracted_as_text)
"extruct~=0.18",
"playwright>=1.64.1,<2",
"patchright>=1.64.3,<2",
"beautifulsoup4~=4.14",
# Retained as a security-utility library, NOT Flask/framework residue.
# `safe_join` is load-bearing for security/path_validator.py's traversal
# containment, and `secure_filename` for security/filename_sanitizer.py's
# upload sanitisation — those two imports are the only werkzeug use left.
# The pin covers CVE-2026-27199 (safe_join accepting Windows device names
# in multi-segment paths), which was the last of three point releases
# (3.1.4 -> 3.1.6) needed to close that class of bug. Do not reimplement
# against the stdlib without first adding Windows device-name and unicode
# NFKD-normalisation coverage; tests/security/ currently has none, so a
# regression in exactly the case this pin exists for would be silent.
"werkzeug~=3.1.6",
"alembic~=1.17",
"sqlalchemy>=2.0,<2.1", # #6876: fresh 2.1.1 installs reported a research-time segfault; stay on the tested 2.0 series pending upstream resolution
"sqlalchemy-utc~=0.14",
"wikipedia~=1.4",
"arxiv>=4.0.1,<5",
# Keep the published minimum aligned with the reviewed lock version.
"pypdf>=6.21.4,<7", # Reviewed patch minimum; retain the tested 6.x series.
"sentence-transformers~=5.2",
"faiss-cpu~=1.13.0", # 1.14.x wheels SIGILL on CPUs without AVX2 (#4480); unpin criteria tracked in #4499
"pydantic~=2.12",
"pydantic-settings~=2.12", # lock pulls 2.14.2: GHSA-4xgf-cpjx-pc3j fix
"toml~=0.10",
"platformdirs~=4.5",
"dynaconf~=3.2",
"requests>=2.33,<3", # CVE-2026-25645: enforce the patched floor in published packages too
"certifi>=2026.10.19", # PYSEC-2026-4320 / GHSA-6q48-6c7w-9gw2 (critical): bundled emSign root CAs with compromised intermediate CA keys; fixed only in 2026.10.19
"urllib3~=2.8", # CVE-2026-44431 CVE-2026-44432 fix; 2.8.0 fixes GHSA-8988-9cw3-xx77, GHSA-gh4c-6fx4-qh6g, GHSA-vxq7-64xx-v4gw
"brotli>=1.2.1",
"brotlicffi>=1.2.1.0; platform_python_implementation != \"CPython\"",
"filelock>=4.2.1",
"tiktoken~=0.12",
"xmltodict~=1.0",
"lxml>=5.3", # >=5.3 to satisfy crawl4ai; PDM override ensures >=6.0 in dev
"newspaper4k~=0.9",
"setuptools>=84.1.0",
"crawl4ai~=0.9", # 0.9.0: GHSA-r253-r9jw-qg44 (RCE via Chromium launch-arg injection), GHSA-2jq4-q6vv-4cp3 (path-traversal file write), GHSA-wm69-2pc3-rmmf fixes; supersedes 0.8.9 fixes
"defusedxml~=0.7", # XXE-safe XML parsing
"nh3~=0.3", # Backend HTML sanitization
"pdfplumber~=0.11",
"unstructured~=0.18", # GHSA-4mvj-m6j5-pmf7 (CVE-2026-71428) SSRF fixed only in 0.24+, which requires Python <3.14 — no lockable fix until upstream supports 3.14. Suppressed in .trivyignore/.grype.yaml; sink reachability pinned by tests/security/test_unstructured_url_partition_tripwire.py
"nltk>=3.10.4", # GHSA-8mgp-746c-j5xp fix; transitive via unstructured, floored so non-lock installs cannot resolve 3.10.3
# Runtime parsers for the unstructured office-document loaders. These are
# NOT pulled in by bare `unstructured` (only by its `[docx]`/`[odt]`/`[pptx]`/
# `[xlsx]` extras), yet the loader registry advertises .doc/.docx/.odt/.ppt/
# .pptx/.xls/.xlsx as supported. Without them those uploads fail at runtime
# with `ModuleNotFoundError: No module named 'docx'` (see issue #4414).
"python-docx~=1.2", # .doc, .docx, .odt (odt parser imports python-docx)
"python-pptx~=1.0", # .ppt, .pptx
"python-slugify~=8.0", # citation_formatter._slugify_title
"openpyxl~=3.1", # .xlsx (unstructured Excel partition)
"msoffcrypto-tool~=6.0", # imported at module load by unstructured.partition.xlsx
"xlrd~=2.0", # legacy .xls reading (pandas engine)
"google-search-results~=2.4",
"jaraco-context~=6.1", # CVE GHSA-58pv-8j8x-9vj2 fix for path traversal (also pinned as transitive dep)
"optuna~=4.7",
"elasticsearch~=9.3",
"methodtools~=0.4",
"loguru~=0.7",
"cachetools~=7.0",
"matplotlib~=3.10",
"pandas~=3.0",
"plotly~=6.5",
"kaleido~=1.2",
"aiohttp~=3.13", # lock pulls 3.14.1: CVE-2026-54273..54280 fixes
"tenacity~=9.1",
"apscheduler~=3.11",
"rich~=14.3",
"click~=8.3",
"sqlcipher3-binary~=0.6; sys_platform == \"linux\" and platform_machine == \"x86_64\"",
"sqlcipher3~=0.6; (platform_machine == \"aarch64\" or platform_machine == \"arm64\") and sys_platform == \"linux\"",
"sqlcipher3~=0.6; sys_platform != \"linux\"",
"lxml-html-clean>=0.4.4", # CVE-2026-28350: base tag injection bypass
"weasyprint~=70.0", # GHSA-jf6q-chmf-3h3v (CVE-2026-55073): url_fetcher bypass via write_pdf(stylesheets=[url])/xmp_metadata=[url]; fixed only in 70.0
"Pillow>=13.0.0", # CVE-2026-25990: out-of-bounds write in PSD (fixed 12.1.1); CVE-2026-112390, CVE-2026-112391, CVE-2026-112392, CVE-2026-112393, CVE-2026-112394, CVE-2026-112395, CVE-2026-112396, CVE-2026-112397, CVE-2026-112399, CVE-2026-112400, CVE-2026-112401, CVE-2026-112402, CVE-2026-112403, CVE-2026-112404, CVE-2026-112405, CVE-2026-112406, CVE-2026-112891, CVE-2026-112892, CVE-2026-112893, CVE-2026-112894, CVE-2026-112895, CVE-2026-112896, CVE-2026-112897, CVE-2026-112898, CVE-2026-112899, CVE-2026-112900, CVE-2026-112901, CVE-2026-112902 (GHSA-22hg-r758-rrw9, GHSA-254f-3936-288h, GHSA-27h8-gf7j-v5hc, GHSA-332p-7hrc-92wf, GHSA-4558-3h8r-v8xp, GHSA-462x-pgg6-55fp, GHSA-4rr5-89j8-mwwm, GHSA-58r4-6rv3-gfh8, GHSA-5xm2-6676-qcp9, GHSA-65qm-jvmh-6pqg, GHSA-74r2-7ff9-mjj2, GHSA-7mwm-ghpf-9vrm, GHSA-8g5g-8vmr-9782, GHSA-c6hw-5grf-ff96, GHSA-cp9v-662q-vvx9, GHSA-f2g6-542v-9j58, GHSA-fc9g-5qg7-mf45, GHSA-gg2r-wvfm-q9rx, GHSA-j4m9-6w36-pw47, GHSA-jg86-v3jv-hrpm, GHSA-p4wg-p73j-c528, GHSA-pchr-8j38-3x4p, GHSA-q45j-58j2-45rg, GHSA-rfgq-q3w2-pmv2, GHSA-vx6w-vv9f-6gvg, GHSA-w889-685w-c8fh, GHSA-xgh8-jp6q-p5x8, GHSA-xvh5-g6gv-559v; fixed only in 13.0.0)
"cryptography>=50.0.0,<51", # GHSA-g6cj-pr64-35w5 (CVE-2026-69247): PKCS#7 EnvelopedData Bleichenbacher oracle; only fix is 50.0.0 (no 48.x/49.x backport). 50.0.0 also subsumes CVE-2026-26007, CVE-2026-39892, GHSA-537c-gmf6-5ccf. Absorbs 49.0.0/50.0.0 breaking changes (removed *_KEY_TYPES aliases, stricter X.509/DER) safely: codebase audit found zero first-party cryptography usage — only pyjwt[crypto] touches it transitively
# notification_validator mirrors Apprise's query parser as a security
# boundary (see BLOCKED_APPRISE_QUERY_KEYS). 1.12.0 is the reviewed
# floor: never resolve below it, and re-check the parser contract and
# its tests before raising the ceiling.
"apprise>=1.12.0,<2",
"oauthlib>=4,<5", # Apprise -> requests-oauthlib; 4.0.0 fixes GHSA-hj66-6f7g-4r5v and GHSA-xpv3-w29h-x7cv
"markdown~=3.10",
"pypandoc-binary~=1.16",
"datasets>=5.0.1,<6", # CVE-2026-66007: release carrying the upstream fix
"fsspec>=2026.6.0", # CVE-2026-104851: sandbox reference-filesystem templates
"pyarrow~=23.0",
"langchain-experimental~=0.4",
# Pinned to the 0.136.x line: fastapi 0.138 breaks app.include_router
# route propagation — the app drops from 318 routes to ~22 (routers
# register their routes, but include_router no longer adds them to the
# app). Revisit when the routers are adapted to the newer fastapi API.
#
# The blame originally fell on starlette 1.3 as well; that was wrong.
# fastapi 0.136.3 + starlette 1.3.1 was verified in a clean venv to
# include routers correctly and serve requests, which is what let the
# starlette security floor below be raised without touching this pin.
#
# A future bump carries a second, unrelated cost: fastapi 0.141.1
# REMOVED ``Dependant.is_coroutine_callable`` / ``is_gen_callable`` /
# ``is_async_gen_callable``. Three places read those flags and must be
# rewritten in the same change, or ``WorkerCleanupAPIRoute.__init__``
# raises ``AttributeError`` reading them on the very first route it
# wraps -- a hard crash at app import, not a silently unenforced
# #6095 owner-worker cleanup guarantee. Update:
# - src/local_deep_research/web/dependencies/threadpool.py —
# ``wrap_sync_route_with_cleanup``'s skip branch
# - tests/web/dependencies/test_threadpool.py —
# ``test_production_app_wraps_every_sync_api_route`` (BOTH the
# ``sync_routes`` census and the ``generator_routes`` assertion)
# - tests/web/dependencies/test_threadpool.py —
# ``test_worker_cleanup_gates_on_fastapi_callable_classification
# _not_inspect``
"fastapi~=0.136.3",
# Pin starlette explicitly so the lock cannot float it.
#
# >=1.3.1 is a SECURITY floor: CVE-2026-54283 (CVSS 7.5). request.form()
# silently ignores its max_fields / max_part_size limits for
# application/x-www-form-urlencoded bodies, so an unauthenticated POST to
# /auth/login or /auth/register (both take Form(...) params, so FastAPI
# calls request.form()) can block the event loop. Measured on 1.2.1:
# 1,000,000 fields in a 9.9 MB body parsed in 3.55s, with max_fields=1000
# ignored. This server runs workers=1 (required for Socket.IO without a
# Redis message queue), so that stalls EVERY user, and
# BodySizeLimitMiddleware does not bound it -- its cap computes to
# 200 * 3 GB = 644 GB. On 1.3.1 the same payload is rejected in 0.00s.
#
# The previous comment here claimed starlette 1.3 breaks
# app.include_router (318 routes -> ~22). That was a misdiagnosis:
# verified in a clean venv that fastapi 0.136.3 + starlette 1.3.1 includes
# routers correctly and serves requests. The route collapse came from the
# fastapi 0.138 bump attempted at the same time, which is why fastapi
# stays pinned to the 0.136.x line above.
#
# Upper bound at <1.4 to keep the next minor from arriving unreviewed.
"starlette>=1.3.1,<1.4",
# NOTE on the spec width: PEP 440's `~=` fixes all but the LAST component,
# so a two-component `~=0.34` means >=0.34,<1.0 — not "near 0.34". This
# resolves to 0.52.1 in pdm.lock, eighteen minor versions on. That is
# deliberate here (it is how security patches arrive without a pyproject
# edit) but it does mean a `pdm update` can move uvicorn a long way with no
# diff to review — read pdm.lock, not this line, to know what ships.
# Contrast `fastapi~=0.136.3` above, which IS narrow (>=0.136.3,<0.137.0)
# because that pin is load-bearing: 0.138 breaks include_router.
"uvicorn[standard]~=0.34",
# Imported directly (notification templates' jinja2 Environment, and
# the web UI via Starlette's Jinja2Templates). Previously satisfied
# transitively by Flask; declare explicitly now that Flask is gone.
"jinja2~=3.1",
# Same two-component caveat as uvicorn above: `~=0.0.20` is
# >=0.0.20,<0.1.0, and resolves to 0.0.32. Here the float is doing real
# work — 0.0.26 and 0.0.30 carry multipart DoS fixes this project would
# otherwise still be missing.
"python-multipart~=0.0.20",
"slowapi~=0.1",
"python-socketio~=5.12",
# Session cookie signing — used directly by socketio_asgi.py to verify
# the WebSocket handshake's session cookie (matching Starlette's
# SessionMiddleware signing scheme). Also a transitive dep of Starlette.
"itsdangerous~=2.2",
]
[project.optional-dependencies]
mcp = [
"mcp[cli]~=1.2",
"PyJWT>=2.15.0,<3", # MCP transitive dependency; 2.14.0 fixes GHSA-w6j9-cwv2-h6wq and ten sibling advisories, 2.15.0 fixes GHSA-42vr-xj54-vc7v
]
[project.urls]
"Homepage" = "https://github.com/LearningCircuit/local-deep-research"
"Bug Tracker" = "https://github.com/LearningCircuit/local-deep-research/issues"
[project.scripts]
# `ldr` was removed in commit c1f80e7a8 ("Remove deprecated CLI", #319) but the
# entry-point line was left behind, so the installed binary has crashed on
# import for every release since. Caught by the entry-point smoke in
# release-gate.yml. Restore only when a replacement CLI exists.
ldr-web = "local_deep_research.web.app:main"
ldr-mcp = "local_deep_research.mcp:run_server"
# Note: build backend is pdm.backend (see [build-system]). These
# [tool.setuptools] sections are kept for compatibility with editable
# installs via `pip install -e .` which may fall back to setuptools.
[tool.setuptools]
include-package-data = true
[tool.setuptools.package-data]
"local_deep_research.web" = ["templates/*", "static/*", "static/**/*"]
"local_deep_research.defaults" = ["*.toml", "*.py", "*.template", ".env.template", "*.json"]
"local_deep_research.notifications" = ["templates/*.jinja2"]
# Note: there is no `local_deep_research.data` package any more. Every
# academic dataset is downloaded at runtime into the user data directory
# by the `local_deep_research.journal_quality.data_sources` package.
[tool.pdm]
distribution = true
version = { source = "file", path = "src/local_deep_research/__version__.py" }
[tool.pdm.build]
# PDM includes tests/ in source distributions by default. The complete test
# suite is maintained in Git and CI, but is not needed to build or install the
# package; shipping it made the v1.10.7 sdist roughly twice the necessary size.
# themes.css is generated on boot in a writable source checkout and must not
# make release artifacts depend on whether a build ran after an app test.
excludes = ["tests/", "src/local_deep_research/web/static/css/themes.css"]
[[tool.pdm.source]]
url = "https://download.pytorch.org/whl/cpu"
name = "torch"
include_packages = ["torch", "torch*"]
[tool.pdm.resolution.overrides]
# newspaper4k and crawl4ai pin lxml<6.0 but work fine with 6.x
# (tested). Override to get Python 3.14 pre-built wheels.
lxml = ">=6.0"
[dependency-groups]
dev = [
"virtualenv>=21.14.13,<22",
"pre-commit~=4.5",
"cookiecutter~=2.6",
"pytest-mock~=3.15",
"pytest~=9.0",
"pytest-cov~=7.0",
"pytest-timeout~=2.4",
"pytest-asyncio~=1.3",
"pytest-xdist~=3.8",
"mcp[cli]~=1.2", # exercise MCP caller contracts in ordinary pytest CI
"ruff~=0.15",
"freezegun~=1.5",
"mypy~=1.19",
"types-requests~=2.32",
"types-toml~=0.10",
"hypothesis~=6.151",
"vulture~=2.14",
"towncrier~=24.8",
"xlwt~=1.3", # test-only: writes legacy .xls fixtures for XLSLoader tests
]
[tool.pytest.ini_options]
markers = [
"requires_llm: marks tests that require a real LLM (not fallback)",
"integration: marks integration tests",
"slow: marks slow tests",
"asyncio: marks async tests that use asyncio",
"fd_canary: heavy file-descriptor-leak regression tests (#3816). CPU-bound real-event-loop spins that exceeded the legacy 60s timeout under coverage + '-n auto' contention, and whose FD-count assertions are noisy under parallel execution; run in a dedicated serial, no-coverage CI step instead of the parallel suite.",
"lifespan: enters the app's real lifespan (startup/shutdown). At most ONE such test may run per process: socketio_asgi.init_lock() only assigns when _lock is None, so a second cycle would leave the asyncio.Lock bound to a dead loop. Do not add a second one or convert it into a fixture.",
"real_session_check: opt out of the autouse _legacy_bare_username_auth shim so the real server-side session-id check is exercised. For tests that must prove a destroyed/invalid session is rejected.",
"real_durable_epoch: opt out of the autouse _durable_epoch_projection shim so the real durable rekey-epoch projection is exercised. For tests that must prove epoch-bound sessions fence on password change.",
"serial: tests that mutate PROCESS-GLOBAL state (os.umask, os.chdir, signal handlers) for the duration of an assertion. Correct on their own, but under '-n auto' any other file creation happening concurrently in the same worker process inherits the hostile global -- so they run in a dedicated serial CI step instead of the parallel suite. This marker says NOTHING about privilege by itself: if a serial test's assertions also require a genuinely unprivileged process (e.g. it self-skips with `if os.geteuid() == 0: pytest.skip(...)`), it MUST also carry the 'nonroot' marker explicitly -- do not rely on a CI step happening to invoke pytest under an unprivileged user (docker-tests.yml's serial step uses '--user ldruser', but that is CI wiring, not a property of the marker, and a lane that ran '-m serial' as root would silently no-op every assertion in such a test). docker-tests.yml runs 'serial' and 'nonroot' together in one step selecting '-m serial or nonroot' under '--user ldruser', so a module carrying both markers runs exactly once.",
"connected: marks the connected pytest suite (real per-user encrypted SQLCipher DBs; heavier scenarios run out of the default unit suite).",
"nonroot: tests whose assertions require a genuinely unprivileged process -- they start with `if os.geteuid() == 0: pytest.skip(...)` because permission bits (chmod/O_CREAT denial, read-only dirs, etc.) are not enforced for root. A test may carry 'nonroot' alone (does not mutate process-global state, e.g. tests/security/test_db_connection_create_hostile_dir.py, tests/security/test_db_connection_readonly_hostile_fs.py) or 'nonroot' together with 'serial' (also mutates process-global state, e.g. tests/security/test_db_connection_umask_perms.py). docker-tests.yml runs both markers together in one step, '-m serial or nonroot' under '--user ldruser', so a module carrying both runs exactly once regardless of which marker it also carries. The distinction matters because docker-tests.yml's default (main) container runs as root (it needs write access to the bind-mounted checkout for coverage/junit output), so nonroot-marked tests would silently no-op there unless excluded from the main step ('not serial and not nonroot') and run in that dedicated '--user ldruser' step instead. No exclusion is needed in security-tests.yml, which already executes as the non-root Actions runner user for every step (main and serial alike), so a serial+nonroot module's non-root requirement is satisfied there without a dedicated nonroot step or selector.",
]
# Global timeout for all tests - fail fast instead of hanging.
# "thread" (not "signal") because SIGALRM was firing inside weakref/GC on
# 3.14 in CI, corrupting xdist workers and losing their coverage data.
timeout = 180
timeout_method = "thread"
[tool.coverage.run]
source = ["src"]
branch = true
omit = [
"*/tests/*",
"*/__pycache__/*",
"*/migrations/*",
# Experimental strategies (will be cleaned up)
"*/strategies/*",
# CLI entry points (hard to unit test)
"*/cli.py",
"*/cli/*",
# Visualization code
"*/visualization.py",
# Experimental browsecomp decoding
"*/answer_decoding/*",
]
[tool.coverage.report]
exclude_lines = [
"pragma: no cover",
"if TYPE_CHECKING:",
"raise NotImplementedError",
]
# Conservative baseline — ratchet up as coverage improves
fail_under = 50
show_missing = true
[tool.coverage.html]
directory = "coverage/htmlcov"
[tool.ruff]
# Exclude a variety of commonly ignored directories.
exclude = [
".bzr",
".direnv",
".eggs",
".git",
".git-rewrite",
".hg",
".ipynb_checkpoints",
".mypy_cache",
".nox",
".pants.d",
".pyenv",
".pytest_cache",
".pytype",
".ruff_cache",
".svn",
".tox",
".venv",
".vscode",
"__pypackages__",
"_build",
"buck-out",
"build",
"dist",
"node_modules",
"site-packages",
"venv",
]
# Same as Black.
line-length = 80
indent-width = 4
[tool.ruff.lint]
# Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`) codes by default.
select = [
"E4", "E7", "E9", "F", "S",
# --- Wave 2: logging, performance, return style, exceptions, print, comprehensions ---
"G", # flake8-logging-format: lazy formatting in logger calls
"PERF", # perflint: performance anti-patterns
"RET", # flake8-return: unnecessary assign-before-return, superfluous else
"TRY", # tryceratops: exception handling patterns
"T20", # flake8-print: print statement detection in production code
"C4", # flake8-comprehensions: unnecessary comprehensions/calls
]
ignore = [
# --- Bandit (S) rules suppressed globally for existing code patterns ---
# try-except-pass/continue: pervasive cleanup pattern throughout codebase
"S110", # try-except-pass
"S112", # try-except-continue
# subprocess calls with known-safe partial paths (e.g. "git", "pip")
"S603", # subprocess-without-shell-equals-true
"S606", # start-process-with-no-shell
"S607", # start-process-with-partial-path
# --- Wave 2: rules ignored initially due to high violation counts ---
# TODO: fix violations and remove ignore
"TRY003", # raise-vanilla-args — overly pedantic for built-in exceptions
"TRY004", # type-check-without-type-error — breaks API contracts; ruff autofix was removed
"TRY300", # try-consider-else — unintuitive syntax; conflicts with RET505
"PERF401", # manual-list-comprehension — no reliable autofix; negligible real-world impact
]
# Allow fix for all enabled rules (when `--fix`) is provided.
fixable = ["ALL"]
unfixable = []
# Allow unused variables when underscore-prefixed.
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
[tool.ruff.lint.per-file-ignores]
".semgrep/tests/ldr-security.py" = ["S608", "RET504"] # Intentional SQL rule controls and assignment-flow cases.
# Tests: assert is the standard pattern; hardcoded values are test fixtures; print is fine
"tests/**" = ["S101", "S104", "S105", "S106", "S107", "S108", "S113", "S311", "S324", "S602", "S608", "T20", "TRY201", "G004", "C420", "TRY002", "C408", "C401", "C416", "C414", "PERF102", "PERF402", "PERF403", "RET503", "RET504", "TRY301"]
# Examples: hardcoded values are demo fixtures; print is fine; bare exceptions acceptable
"examples/**" = ["S105", "S311", "T201", "TRY002", "C408", "C401", "C416", "PERF102", "PERF402", "PERF403", "RET503", "RET502", "RET504", "TRY301"]
# Cookiecutter hooks: shell=True is needed for cross-platform compat
"cookiecutter-docker/**" = ["S602", "T201"]
# CI scripts: test password is intentional
"scripts/ci/**" = ["S105"]
# Pre-commit hooks: print is the interface
".pre-commit-hooks/**" = ["T201", "RET503", "RET504"]
# Scripts: print is the interface
"scripts/**" = ["T201"]
".github/scripts/**" = ["T201"]
# CLI modules: print is the interface
"src/local_deep_research/cli/**" = ["T201"]
# Benchmarks: print is used for output/reporting
"src/local_deep_research/benchmarks/**" = ["T201"]
# Web/settings files with intentional print for startup/debug
"src/local_deep_research/settings/logger.py" = ["T201"]
# Server config: binding to 0.0.0.0 is intentional for containerized deployment
"src/local_deep_research/web/server_config.py" = ["S104"]
"src/local_deep_research/security/network_utils.py" = ["S104"]
"src/local_deep_research/security/notification_validator.py" = ["S104"]
"src/local_deep_research/security/url_builder.py" = ["S104"]
"src/local_deep_research/utilities/llm_utils.py" = ["S104"]
"src/local_deep_research/web_search_engines/rate_limiting/llm/wrapper.py" = ["S104"]
# Non-cryptographic random used for jitter/sampling, not security
"src/local_deep_research/scheduler/background.py" = ["S311"]
"src/local_deep_research/web_search_engines/engines/search_engine_google_pse.py" = ["S311"]
"src/local_deep_research/web_search_engines/rate_limiting/tracker.py" = ["S311"]
# Hardcoded password strings are default/placeholder values, not real secrets
"src/local_deep_research/database/models/library.py" = ["S105"]
# Requests without timeout: safe_requests module handles timeouts at a higher level
"src/local_deep_research/security/safe_requests.py" = ["S113"]
# Markup usage is intentional and inputs are pre-sanitized
"src/local_deep_research/web/themes/__init__.py" = ["S704"]
"src/local_deep_research/web/utils/vite_helper.py" = ["S704"]
# SQL expressions use parameterized queries; ruff flags f-string construction
"src/local_deep_research/advanced_search_system/filters/followup_relevance_filter.py" = ["S608"]
"src/local_deep_research/web_search_engines/search_engine_base.py" = ["S608"]
# XML parsing uses defusedxml elsewhere; this specific usage is on trusted data
"src/local_deep_research/research_library/downloaders/arxiv.py" = ["S314"]
[tool.ruff.format]
# Like Black, use double quotes for strings.
quote-style = "double"
# Like Black, indent with spaces, rather than tabs.
indent-style = "space"
# Like Black, respect magic trailing commas.
skip-magic-trailing-comma = false
# Like Black, automatically detect the appropriate line ending.
line-ending = "auto"
[tool.mypy]
python_version = "3.12"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false
check_untyped_defs = true
warn_redundant_casts = true
warn_unused_ignores = true
no_implicit_optional = true
strict_equality = true
show_error_codes = true
# Start permissive - allow missing imports for third-party packages without stubs
ignore_missing_imports = true
# Ignore test files
[[tool.mypy.overrides]]
module = "tests.*"
ignore_errors = true
# Third-party packages without type stubs — suppress import-untyped errors
[[tool.mypy.overrides]]
module = ["cachetools", "cachetools.*", "dateutil", "dateutil.*"]
ignore_missing_imports = true
# Existing modules with type errors — ignore until cleaned up.
# New modules are checked by default. Remove entries as modules are fixed.
[[tool.mypy.overrides]]
module = [
"local_deep_research.advanced_search_system.*",
"local_deep_research.api.*",
"local_deep_research.benchmarks.*",
"local_deep_research.config.*",
"local_deep_research.database.*",
"local_deep_research.domain_classifier.*",
"local_deep_research.embeddings.splitters.*",
"local_deep_research.library.*",
"local_deep_research.metrics.*",
"local_deep_research.research_library.*",
"local_deep_research.security.*",
"local_deep_research.settings.*",
"local_deep_research.storage.*",
"local_deep_research.utilities.*",
"local_deep_research.web.*",
]
ignore_errors = true
# ---------------------------------------------------------------------------
# towncrier — release-notes news fragments
# ---------------------------------------------------------------------------
# Each PR drops a tiny markdown file under changelog.d/ named
# <id>.<category>.md (or +slug.<category>.md for orphan fragments
# without a PR/issue number). At release prep time the maintainer runs:
#
# pdm run towncrier build --version <X.Y.Z> --yes
#
# which renders the fragments into docs/release_notes/<X.Y.Z>.md (per
# the {version}-templated filename below) and `git rm`s the consumed
# fragments. The release workflow (.github/workflows/release.yml) then
# reads that per-version file as the human-narrative input to the
# release body (alongside the AI TL;DR and the auto-generated PR list).
#
# Categories are intentionally lean — the auto-generated PR list already
# catches dep bumps, CI churn, etc., so changelog.d/ fragments are just
# for user-visible changes worth highlighting.
[tool.towncrier]
# `name` is set explicitly so towncrier never tries to import the
# `local_deep_research` package. The release workflow runs towncrier
# in a sparse checkout that omits src/, so an import-based lookup
# would fail with ModuleNotFoundError. `package`/`package_dir` are
# intentionally not set — with `name` provided and `--version` always
# passed on the CLI, towncrier has no remaining reason to import.
name = "local-deep-research"
# single_file=false + a {version}-templated filename makes towncrier
# write a fresh per-release file each build instead of appending to one
# growing CHANGELOG. Matches the pre-existing
# docs/release_notes/<version>.md convention used by the release
# workflow.
single_file = false
filename = "docs/release_notes/{version}.md"
directory = "changelog.d"
# title_format=false suppresses the `## <version> (<date>)` header in
# the rendered output — the GitHub release page already shows the
# version as its title, and per-version files don't need an inline
# version header either.
title_format = false
# Fragments name both issues and PRs. GitHub's /issues/<number> route opens
# issues directly and redirects PR numbers to their pull request pages.
issue_format = "[#{issue}](https://github.com/LearningCircuit/local-deep-research/issues/{issue})"
underlines = ["", "", ""]
[[tool.towncrier.type]]
directory = "breaking"
name = "💥 Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "security"
name = "🔒 Security"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "✨ New Features"
showcontent = true
[[tool.towncrier.type]]
directory = "bugfix"
name = "🐛 Bug Fixes"
showcontent = true
[[tool.towncrier.type]]
directory = "removal"
name = "🗑️ Removed"
showcontent = true
[[tool.towncrier.type]]
directory = "misc"
name = "📝 Other Changes"
showcontent = true