pyproject.toml

[build-system]
requires = ["setuptools>=77", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "delfin-complat"
version = "1.3.3"
description = "DELFIN is a modular computational chemistry platform that automates end-to-end molecular workflows — from SMILES input to realistic property predictions. It combines structure generation, DFT, semi-empirical methods, ML potentials, and AI tools behind a unified interface with an interactive browser-based dashboard."
readme = { file = "README.md", content-type = "text/markdown" }
requires-python = ">=3.10,<3.13"
authors = [{ name = "Maximilian Hartmann" }]
# PEP 639: an SPDX expression and the files that carry the texts.
# LGPL-3.0 is a set of additional permissions on top of GPL-3.0, and a
# conveyed copy carries both texts (GPL-3.0 section 4, LGPL-3.0 section
# 4(b)), so both land in the wheel's .dist-info/licenses/ and the sdist.
license = "LGPL-3.0-or-later"
# THIRD_PARTY_NOTICES.md carries the notices of the bundled 3Dmol.js and the
# OpenTUI patches, and the licences of what the installers download.
license-files = ["LICENSE", "COPYING", "COPYING.LESSER", "THIRD_PARTY_NOTICES.md"]
urls = { "Homepage" = "https://github.com/ComPlat/DELFIN", "Repository" = "https://github.com/ComPlat/DELFIN" }
keywords = ["quantum-chemistry", "orca", "xtb", "redox", "spin-state", "workflow", "dashboard", "smiles"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Science/Research",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Scientific/Engineering :: Chemistry",
]
# Every entry carries an upper bound. DELFIN's results are produced by the
# numerics underneath it, so an install today and an install next year
# resolving to different majors is not a packaging detail — it decides whether
# a published number can be reproduced. The ceilings are the next major above
# what the project is known to run on, so patch and minor releases still flow
# in and only a genuine breaking release needs a person to look. Raising one is
# a deliberate step, verified against real calculations; Dependabot is
# configured not to propose it.
dependencies = [
    "mendeleev>=0.14,<1.0",
    "psutil>=5.9,<8",
    "ase>=3.22.0,<4",
    # numpy 2 is admitted because it is what the construction runs on: the
    # MANTA build environment behind the published data is Python 3.12.11
    # with numpy 2.2.2, rdkit 2025.9.3, openbabel-wheel 3.1.1.22 and scipy
    # 1.16.2 (env/reference-environment.lock lists every version). The old
    # ceiling <2 dates from 2026-01-15, when the stack around numpy was not
    # ready for 2.x; kept today, it would rule out the very environment the
    # published numbers come from.
    #
    # The exception to "next major" above: the ceiling is the highest minor
    # anything has been measured on, not <3. It replaces a ceiling that
    # protected against a real break, and numpy 2.3 to 2.5 have been run by
    # nobody. CI holds both ends: numpy 1.26 on 3.11, the reference versions
    # on 3.12. Raising it means adding a CI leg on the newer minor first.
    "numpy>=1.26,<2.3",
    "scipy>=1.6.0,<2",
    "networkx>=2.6,<4",
    "matplotlib>=3.3.4,<4",
    # rdkit versions by release year; the ceiling only rules out a jump into a
    # future year's series without anyone checking.
    #
    # 2026.3.6 is excluded, and the exclusion is dated because it is meant to
    # be removed. Same commit, two CI runs, nothing between them but a patch
    # release upstream:
    #
    #   2026-09-03 19:57  80fb85cb  push      success   rdkit 2026.3.5
    #   2026-09-04 07:56  80fb85cb  schedule  failure   rdkit 2026.3.6
    #
    # Under 2026.3.6 the isomer builder returns the metal skeleton without
    # its hydrogens — Fe(OH)7 comes back with 8 atoms instead of 15 and 0
    # hydrogens instead of 7 — so six tests in
    # test_an_isomer_is_the_molecule_that_was_asked_for.py fail. Excluding
    # the one release restores the signal; it does not fix the chemistry,
    # and the code has to be made to work with the new series before this
    # line can go.
    #
    # The 2026.9 series is held back the same way, dated for the same
    # reason. Between two slow-tests runs on 2026-10-09 nothing changed
    # but rdkit, 2026.3.5 -> 2026.9.1, and ten builder tests failed
    # (chelate backbone, metalloid donors, isomer benchmark and
    # determinism, multihapto, UFF determinism). Measured on the same
    # checkout: 2026.9.1 -> 4 failed / 12 passed over three of those
    # files; 2026.3.5 -> 14 passed, 2 xfailed. The fast gate passes on
    # 2026.9.1; only the construction tests notice. Lift this when they
    # pass on 2026.9.
    "rdkit>=2023.3.1,!=2026.3.6,<2026.10",
    "stk>=2024.1,<2027",
    "openbabel-wheel>=3.1.0,<4",
    "ipykernel>=6.0,<8",
    "ipywidgets>=8.0,<9",
    "py3Dmol>=2.0.4,<3",
    "python-docx>=0.8.11,<2",
    # pymol-open-source is the [pymol] extra below, not a core dependency.
    # PyPI carries it only as manylinux_2_35 wheels (3.2.0a0; 3.1.0a0 is
    # cp311/manylinux_2_34 only, and there is no sdist), so on a glibc 2.34
    # system such as RHEL 9 with Python 3.12 the requirement has no
    # candidate at all and pip refuses to install DELFIN. A conda-forge
    # pymol-open-source does not help either: it carries no pip dist-info
    # under that name, so pip still looks for it on the index. PyMOL renders
    # report pictures (ESP, dipole and orbital PNGs); nothing in the
    # construction needs it.
    # voila serves the dashboard over HTTP through jupyter-server and
    # tornado, which it requires with floors from 2022. The floors here are
    # the first releases that fix every advisory known on 2026-10-16
    # (GHSA ids in tests/test_the_dashboard_server_requires_patched_releases.py):
    # voila 0.5.6 (local file inclusion), jupyter-server 2.20.0 (stored XSS
    # in the nbconvert handlers; 2.18.0 path traversal, CORS, open redirect),
    # tornado 6.5.9 (StaticFileHandler following symlinks out of its root,
    # request-size limits).
    "voila>=0.5.6,<0.6",
    "jupyter-server>=2.20.0,<3",
    "tornado>=6.5.9,<7",
    "Pillow>=13,<14",
    # PyMuPDF (the PDF viewer) is the [pdf] extra below, not a core
    # dependency: it is AGPL-3.0, stronger copyleft than DELFIN's own
    # licence.
    "mammoth>=1.6,<2",
    "openpyxl>=3.1,<4",
    "pexpect>=4.8,<5",
    "umap-learn>=0.5,<0.7",
    "scikit-learn>=1.3,<2",
    # Reads the outputs of programs other than ORCA (Gaussian, xtb, Psi4,
    # GAMESS, Molpro, ...) for the agent's energy profiles; ORCA stays on
    # DELFIN's own parser, which cclib 1.8.1 cannot replace (it stops with
    # an IndexError on ORCA 6 outputs). Core rather than [analysis] so a
    # profile from a Gaussian run works where the agent runs. Capped below
    # 1.9 because what energy_profile corrects was measured on 1.8.1 against
    # real outputs: xtb's free energy arrives in eV, Psi4's energies not at
    # all. Its own requirements (numpy, scipy, packaging, periodictable)
    # move nothing DELFIN pins.
    "cclib>=1.8.1,<1.9",
]

[project.optional-dependencies]
messenger = ["websockets"]
# PyMOL renders the ESP, dipole-moment and orbital pictures of the Word and
# ESD reports (delfin/reporting/esp_report.py, delfin_docx_report.py). Without
# it those pictures are skipped with a logged notice and every other part of
# DELFIN -- construction, dashboard, 3D viewer (py3Dmol), agent -- is unchanged.
# An extra because the only PyPI wheels need glibc >= 2.35; RHEL 9 and its
# clones, the usual HPC login nodes, have 2.34 (see the core dependencies).
# The reference lock still pins its version for whoever can install it.
pymol = [
    "pymol-open-source>=2.5,<4",
]
# Page rendering, in-document search and form-field geometry for the file
# browser's PDF viewer (delfin/dashboard/pdf_view.py), page images for OCR
# and chat previews (delfin/agent/office.py, tab_agent.py). PyMuPDF is
# "Dual Licensed - GNU AFFERO GPL 3.0 or Artifex Commercial License". AGPL
# section 13 adds a source offer to users of a modified version over a
# network, and whether a dashboard served to other users (the multi-user
# login deployment) is such a use is a legal question, not a packaging one.
# An extra, so whoever installs it takes that on by choice.
# Without it every import site degrades: the viewer says why it cannot show
# the page, the OCR check names the missing renderer, a chat card shows no
# preview, and PDF text, forms and merging keep working through pypdf.
pdf = [
    "pymupdf>=1.24,<2",
]
# API keys in the operating system's credential store (macOS Keychain,
# Secret Service, Windows Credential Manager) instead of the 0600 file
# ~/.delfin/credentials.json (delfin/agent/credentials.py). Optional: on a
# headless cluster node there is usually no usable backend, and without
# the package DELFIN keeps using the file.
keyring = [
    "keyring>=24",
]
# A page the agent edits is also loaded in a headless browser by the
# turn-end check (delfin/agent/artifact_check.py), which then reports its
# uncaught errors and console errors. Optional: without it the page's
# scripts and references are still checked; `playwright install chromium`
# fetches the browser once.
browser = [
    "playwright>=1.40,<2",
]
csp = [
    "mpi4py",
]
mlp = [
    "torchani",
]
mlp-full = [
    "torchani",
    "mace-torch",
    "chgnet",
    "matgl",
    "schnetpack",
    "nequip",
    "alignn",
]
mlp-materials = [
    "chgnet",
    "matgl",
]
analysis = [
    "morfeus-ml",
    "cclib",
    "nglview",
    "plotly",
]
# ORCA's own Python interface, OPI (github.com/faccts/opi; on PyPI as
# orca-pi -- "opi" finds nothing). An extra, not core, measured 2026-09-25
# and again 2026-10-15 on 2.0.0: it requires numpy>=2.2.6,<3 and
# rdkit>=2025.3.2,<2026, and the core runs CI on numpy 1.26 and admits
# rdkit 2026.x on purpose, so a hard requirement would move the chemistry
# stack. Two limits it brings: it reads ORCA >= 6.1.1 only (6.0.1 and
# 6.1.0 outputs are refused), and orca_2json from 6.1.1 writes a 6.0.1
# property file's JSON WITHOUT its energies and without a word, so
# get_final_energy() returns None for an energy that exists. DELFIN's
# text parser stays the reader of record; OPI is the structured witness.
orca = [
    "orca-pi>=2,<3",
]
ai-foundation = [
    "transformers",
    "torch",
]
ai-retro = [
    "aizynthfinder",
    "rxnmapper",
]
ai-screening = [
    "deepchem",
]
ai-complex = [
    # SMILES constructors behind the ARCHITECTOR / MOLSIMPLIFY buttons and
    # smiles_converter=ARCHITECTOR|MOLSIMPLIFY (delfin/common/external_builders.py).
    "molSimplify",
    "architector",
    "numba",   # architector imports it without declaring it
    # epic-MACE (the MACE button, smiles_converter=MACE) is no extra: it needs
    # Python 3.7 + RDKit 2020.09 and gets an environment of its own,
    # python -m delfin.installer --install epic-mace.
]
agent = [
    "anthropic>=0.40",
    "openai>=1.0",
    "pyyaml",
    # Document handling travels with the agent: the tools that need it
    # are part of its surface, and shipping the agent without them means
    # read_file refuses a spreadsheet while pointing at a tool that was
    # never advertised.
    #
    # Listed rather than pulled in as "delfin-complat[office]". The
    # self-reference reads cleaner and cost a CI run: this project is
    # published under that name, so pip resolved it against the index and
    # installed the RELEASED wheel beside the editable checkout. Imports
    # then landed partly in the wheel, and a module of the checkout
    # resolved as an empty namespace — "cannot import name ... (unknown
    # location)" in a file nobody had touched. An extra must never be able
    # to pull a published copy of the project into the environment that is
    # testing it.
    "openpyxl>=3.1",
    "pypdf>=4.0",
    "python-docx>=0.8.11",
    "reportlab>=4.0",
    "formulas>=1.2",
    "odfpy>=1.4",
]
docs = [
    # The floor is the oldest release DELFIN's three MCP servers can
    # actually run on, measured rather than assumed: 1.0.0 and 1.1.0 ship
    # no server class at all, and 1.2.0's FastMCP takes no ``instructions``
    # argument, which all three pass. 1.3.0 is the first that starts and
    # answers ``tools/list``. There is deliberately no ceiling — the class
    # that 2.0.0 moved is reached through ``delfin.mcp_compat``, and both
    # lines were started and measured to advertise the same tools.
    "mcp>=1.3",
    "pypdf>=4.0",
]
# Office-document handling for the agent (read_document / edit_sheet /
# fill_pdf_form). These were previously reachable only because other
# packages happened to pull them in, so a clean install had spreadsheet
# and form support by accident or not at all. Without them the three
# tools are not advertised and the agent keeps working without them.
office = [
    "openpyxl>=3.1",
    "pypdf>=4.0",
    "python-docx>=0.8.11",
    # pypdf takes PDF pages apart and puts them together but cannot lay
    # out a page, so producing a document needs a second library.
    "reportlab>=4.0",
    # Works out what a formula comes to. openpyxl stores formulas and never
    # evaluates them, so without this a cell shows =SUM(A1:A10) where a
    # spreadsheet shows the sum. Optional at runtime: missing, the grid
    # shows the formula and says why.
    "formulas>=1.2",
    # OpenDocument (.ods/.odt). LibreOffice is what a great many public
    # authorities and universities run, so these arrive as ordinary
    # attachments; without a reader they stop a document task dead.
    # Reading only — writing ODF is refused rather than approximated.
    "odfpy>=1.4",
]
# What it takes to RUN the suite, and nothing else. Separate from `dev`
# because the agent's own test tool needs exactly this and has no use for
# the formatters: pytest was declared only inside `dev`, which the default
# install does not select, so the agent's `run_tests` landed in an
# environment with no pytest. It was told "no report file produced" and
# reached for a runner of its own -- a venv or a wrapper script in the home
# directory. Shipping the runner removes the reason.
test = [
    "pytest>=6.0",
    # A per-TEST deadline. The slow suite contains a call that waits on a
    # thread with no timeout of its own, and without this the whole job
    # sits behind it until the runner's limit — which is why the slow
    # tests were never run to the end and their failures went unnamed.
    # It was installed in one developer's environment and declared
    # nowhere, so the same command measured different things per machine.
    "pytest-timeout",
]
dev = [
    # The two from `test`, written out rather than pulled in as
    # "delfin-complat[test]": a self-referential extra resolves against
    # PyPI and installs the released wheel beside the editable checkout
    # (see tests/test_packaging_selfreference.py, which asserts this).
    # The duplication is the price of that, and it is pinned by a test.
    "pytest>=6.0",
    "pytest-timeout",
    "pytest-cov",
    # Property-based tests of the parsers of outside input
    # (tests/test_outside_input_parsers_hold_on_any_text.py). Exact: a new
    # hypothesis release changes which inputs a derandomized run generates,
    # and a test of "any text" should not change verdict with the tool.
    # 6.168.3 is the newest that still supports Python 3.10 (6.169 needs
    # 3.11) and was more than two weeks old on 2026-10-16.
    "hypothesis==6.168.5",
    # The [pdf] extra, written out for the same reason, so the PDF tests
    # run in CI (which installs dev) instead of skipping.
    "pymupdf>=1.24,<2",
    "black",
    "flake8",
    "ruff",
]

[project.scripts]
delfin = "delfin.main:main"
delfin_ESD = "delfin.cli_esd_report:main"
delfin_IR = "delfin.cli_ir_report:main"
delfin_NMR = "delfin.cli_nmr_report:main"
delfin-json = "delfin.cli_delfin_collect:main"
delfin-build = "delfin.build_up_complex:main"
delfin-manta = "delfin.cli_manta:main"
delfin-cluster = "delfin.cluster_bench.cli:main"
delfin-guppy = "delfin.guppy_sampling:main"
delfin-guppy-batch = "delfin.guppy_batch:main"
delfin-fukui = "delfin.cli_fukui:main"
delfin-voila = "delfin.cli_voila:main"
delfin-step = "delfin.cli_step:main"
delfin-pipeline = "delfin.cli_pipeline:main"
delfin-docs-index = "delfin.doc_server.indexer:main"
delfin-tools-server = "delfin.tools.mcp_server:main"
delfin-app = "delfin.cli_app:main"
delfin-agent = "delfin.agent.cli:main"
delfin-docs-server = "delfin.doc_server.__main__:main"
delfin-ops-server = "delfin.ops_server.__main__:main"

[tool.setuptools.packages.find]
where = ["."]
include = ["delfin*"]

[tool.setuptools.package-data]
"delfin" = [
    "installers/*.sh",
    "logo/*.png",
    "logo/*.PNG",
    # The submit tab loads MANTA_readme_demo.gif through importlib.resources
    # and falls back to an empty data URI when it is missing, so leaving the
    # animations out of the wheel loses the viewer's loading animation with
    # no error anywhere.
    "logo/*.gif",
    # The installer scripts and notes only. The programs and parameter
    # files they fetch (xtb4stda, stda, xtb, crest, ...) are third-party
    # software under their own licences and are downloaded from upstream
    # by install_qm_tools.sh into qm_tools/bin and qm_tools/share, or
    # ~/.delfin/qm_tools; qm_runtime searches both. Shipping them would
    # convey LGPL object code without its licence text and Corresponding
    # Source. scripts/check_distribution.py fails a build that does.
    "qm_tools/*.txt",
    "qm_tools/*.sh",
    "csp_tools/*.sh",
    "mlp_tools/*.sh",
    "analysis_tools/*.sh",
    "analysis_tools/*.txt",
    "ai_tools/*.sh",
    "ai_tools/*.txt",
    "submit_templates/*.sh",
]
# 3Dmol is vendored so viewers work without outbound network; leaving it
# out of the wheel silently returns every viewer to the two CDNs.
"delfin.dashboard" = ["static/*.js", "static/*.txt"]
"delfin.agent.pack" = ["**/*.md", "**/*.yaml", "skills/*.md"]
"delfin.agent.pack_lite" = ["**/*.md", "**/*.yaml"]
"delfin.notebooks" = ["*.ipynb"]
"delfin.manta" = ["*.md"]
"delfin.voila_assets" = ["login_templates/*.html"]

# Whatever an installer left in the source tree stays out of the wheel even
# when MANIFEST.in would let it in (MANIFEST.in prunes the same directories
# for the sdist).
[tool.setuptools.exclude-package-data]
"delfin" = [
    "qm_tools/bin/*",
    "qm_tools/share/*",
    "qm_tools/share/*/*",
    "qm_tools/downloads/*",
    "qm_tools/build/*",
    "qm_tools/third_party/*",
    "qm_tools/logs/*",
    "csp_tools/bin/*",
    "mlp_tools/bin/*",
    "analysis_tools/bin/*",
    "ai_tools/bin/*",
]

[tool.black]
line-length = 88
target-version = ["py310"]

[tool.ruff]
line-length = 88
target-version = "py310"

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors
    "F",   # pyflakes
    "I",   # isort
    "UP",  # pyupgrade
]
ignore = [
    "E501", # handled by black (line length)
]

[tool.ruff.lint.isort]
known-first-party = ["delfin"]