pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "resdag"
dynamic = ["version"]
description = "PyTorch-native reservoir computing library with GPU acceleration"
readme = "README.md"
requires-python = ">=3.11,<3.15"
license = "MIT"
license-files = ["LICENSE"]
authors = [{ name = "Daniel Estevez-Moya", email = "kemossabee@gmail.com" }]
keywords = [
    "reservoir computing",
    "echo state networks",
    "pytorch",
    "machine learning",
]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
]
dependencies = [
    "torch>=2.10.0",
    "numpy>=2.0.0",
    "networkx>=3.0",
    "pytorch-symbolic>=1.2.1",
    "scipy>=1.17.0",
]

[project.urls]
Homepage = "https://github.com/El3ssar/ResDAG"
Documentation = "https://el3ssar.github.io/ResDAG/"
Repository = "https://github.com/El3ssar/ResDAG"
Issues = "https://github.com/El3ssar/ResDAG/issues"

# Single source of truth for dev tooling: the `dev` extra below. Both
# `pip install -e ".[dev]"` and `uv sync --extra dev` resolve from it, and the
# `dev` dependency-group (used by a bare `uv sync`) just re-exports it via a
# self-reference (see `[dependency-groups]`), so pip and uv install identical
# lint/format/test tool versions.
[project.optional-dependencies]
hpo = ["optuna>=3.0.0"]
# Optional dynamical-systems stack: `resdag.metrics.largest_lyapunov` uses
# `tsdynamics` to estimate Lyapunov exponents from a data series or a built-in
# System. The env marker means pip skips it on Python < 3.12 (tsdynamics needs
# >=3.12) rather than failing to resolve; the pure-math conversions and the
# canonical-constant / reservoir-Jacobian paths in `resdag.metrics` work without
# it. Every `tsdynamics` import in the library is lazy + guarded.
dynamics = ["tsdynamics>=2.5.0; python_version >= '3.12'"]
# Optional adaptive-ODE stack: the continuous reservoir cells
# (`ContinuousReservoirCell`, `EuSNCell`) integrate their vector field with a
# built-in fixed-step Euler / RK4 solver by default (no dependency). Passing
# `solver="torchdiffeq"` switches to an adaptive solver, which lazily imports
# `torchdiffeq` behind a guarded ImportError pointing here. The fixed-step
# solvers — the default and the compilable path — never need this extra.
ode = ["torchdiffeq>=0.2.0"]
# Optional visualization stack: only `ESNModel.plot_model` imports `graphviz`,
# and it does so lazily with a friendly ImportError, so the runtime install
# stays lean. Requires the graphviz *system* binary too (e.g. apt install graphviz).
viz = ["graphviz>=0.21"]
dev = [
    "basedpyright>=1.37.1",
    "pytest>=9.0.2",
    "pytest-cov>=4.0.0",
    "black>=25.12.0",
    "ruff>=0.14.10",
    "mypy>=1.0.0",
    "optuna>=4.0.0",
    "graphviz>=0.21",
]
docs = [
    "mkdocs>=1.6",
    "mkdocs-material>=9.5",
    "mkdocstrings[python]>=0.27",
    "mkdocs-glightbox>=0.4",
    "pymdown-extensions>=10.7",
    "griffe>=1.0",
    "matplotlib>=3.9",  # docs figure pipeline (docs/_tooling/figures)
    "graphviz>=0.21",   # architecture diagrams via ESNModel.plot_model
]


[dependency-groups]
# Re-export the `dev` extra so a bare `uv sync` (which includes the default
# `dev` group) installs exactly the tool versions pinned in
# `[project.optional-dependencies] dev` — no divergence between pip and uv.
dev = ["resdag[dev]"]

[tool.hatch.build.targets.wheel]
packages = ["src/resdag"]

[tool.hatch.version]
path = "src/resdag/__init__.py"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = [
    "-v",
    "--tb=short",
    "--cov=resdag",
    "--cov-report=term-missing",
    "--cov-report=html",
    "-m",
    "not benchmark",
]
markers = [
    "gpu: requires a CUDA device (auto-skipped when unavailable)",
    "slow: long-running test (seconds); always runs, deselect with -m 'not slow'",
    "benchmark: performance assertion, deselected by default; run with -m benchmark",
]

[tool.black]
line-length = 100
target-version = ["py311", "py312", "py313", "py314"]

[tool.ruff]
line-length = 100
target-version = "py311"
lint.select = ["E", "F", "I", "N", "W"]
lint.ignore = ["E501"]                  # Line too long (handled by black)

[tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"]                  # Unused imports in __init__.py are OK
# Math notation (W, A, G, Lk, ...) is the house style in the scientific code:
# renaming matrices and graphs to appease N8xx would hurt readability.
"src/resdag/**" = ["N803", "N806", "N812"]
"tests/**" = ["N803", "N806"]

[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
ignore_missing_imports = true

# The whole package is type-checked in CI with `mypy src/resdag/` and is
# expected to stay at zero errors — there is intentionally no per-module
# baseline / `disable_error_code` escape hatch (see CONTRIBUTING.md).

[tool.coverage.run]
source = ["src"]
omit = ["tests/*", "**/__pycache__/*"]

[tool.coverage.report]
# Gate the FULL-suite coverage in CI (full runs only — selective PR runs use
# --no-cov, see .github/workflows/_test.yml). Held a few points below the
# measured total so noise across the Python 3.11-3.14 matrix can't trip it;
# raise it as coverage climbs.
fail_under = 64
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise AssertionError",
    "raise NotImplementedError",
    "if __name__ == .__main__.:",
]

# -------------------------------------------------------------------------
# Release automation — python-semantic-release
# Version bumps are computed from conventional commit messages on main:
#   feat: -> minor, fix:/perf: -> patch, "BREAKING CHANGE:" -> major
# (major_on_zero=true: a breaking change bumps the major even from 0.x, so the
# first breaking release crosses to 1.0.0 — no artificial holding below 1.0).
# The version lives in src/resdag/__init__.py and is mirrored into
# CITATION.cff; PSR rewrites both, commits, tags vX.Y.Z, and creates the
# GitHub release. CI publishes to PyPI.
# -------------------------------------------------------------------------
[tool.semantic_release]
version_variables = [
    "src/resdag/__init__.py:__version__",
    "CITATION.cff:version",
]
build_command = "python -m pip install build && python -m build"
commit_message = "chore(release): v{version} [skip ci]"
tag_format = "v{version}"
allow_zero_version = true
major_on_zero = true

[tool.semantic_release.commit_parser_options]
parse_squash_commits = true
ignore_merge_commits = true