Skip to content

~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.

30.0 KB
Raw Blame
[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