pyproject.toml

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"


[tool.setuptools.packages.find]
exclude = [
    "dev*",
    "docs*",
    "temp*",
    "tests*",
    "examples*",
    "build*",
    "dist*",
    "dev*",
    "braintrace.egg-info*",
    "braintrace/__pycache__*",
    "braintrace/__init__.py",
]


[tool.setuptools.dynamic]
version = { attr = "braintrace._version.__version__" }


[project]
name = "braintrace"
description = "Enabling Scalable Online Learning for Brain Dynamics."
readme = "README.md"
license = { text = "Apache-2.0 license" }
requires-python = ">=3.11"
authors = [{ name = "BrainTrace Developers", email = "chao.brain@qq.com" }]
keywords = [
    "computational neuroscience",
    "brain-inspired computing",
    "brain modeling",
    "online learning",
]
classifiers = [
    "Natural Language :: English",
    "Operating System :: OS Independent",
    "Programming Language :: Python",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: Apache Software License",
    "Topic :: Scientific/Engineering :: Bio-Informatics",
    "Topic :: Scientific/Engineering :: Mathematics",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
    "Topic :: Software Development :: Libraries",
]
dependencies = [
    "brainstate>=0.5.2",
    "brainunit",
    "brainevent>=0.1.2",
    "brainpy.state",
    "braintools",
]
dynamic = ["version"]


[project.urls]
"Homepage" = "https://github.com/chaobrain/braintrace"
"Bug Tracker" = "https://github.com/chaobrain/braintrace/issues"
"Documentation" = "https://brainx.chaobrain.com/braintrace/"
"Source Code" = "https://github.com/chaobrain/braintrace"


[project.optional-dependencies]
cpu = ["jax[cpu]"]
cuda12 = ["jax[cuda12]"]
cuda13 = ["jax[cuda13]"]
tpu = ["jax[tpu]"]
testing = ["pytest", "pytest-cov", "jax[cpu]", "hypothesis"]
dev = ["pytest", "pytest-cov", "jax[cpu]", "hypothesis", "mypy>=1.8", "build"]


[tool.setuptools.package-data]
braintrace = ["py.typed"]


[tool.pytest.ini_options]
# Marker vocabulary (test-strategy design section 11). `diagnostic` is random
# hypothesis exploration that broadens the curated matrix; it MUST NOT gate CI
# red/green, so `addopts` deselects it by default. Run it on demand with
# `-m diagnostic` (overrides the default `-m` expression); run everything with
# `-o addopts=""`.
markers = [
    "slow: heavy combinations (e.g. double-leading vmap x deep x float64); opt-in",
    "diagnostic: hypothesis random exploration; deselected by default, does not gate CI",
    "oracle: compares an online algorithm's gradient against the BPTT oracle",
    "xfail_known: pins a known finding (F-xx) documented in dev/superpowers/findings",
]
addopts = "-m 'not diagnostic'"


[tool.mypy]
python_version = "3.14"
files = ["braintrace"]
# Test files, test-only helpers, and non-shipped sources are not part of the
# typed public surface and are excluded from release type checking.
exclude = '''(?x)(
    _test\.py$
    | model4test\.py$
    | scenario_catalog\.py$
)'''
# These None-defaulted parameters are genuinely optional throughout the
# codebase; treat them as Optional rather than rewriting 39 signatures.
implicit_optional = true
# Keep `# type: ignore` honest, but only require error codes (not blanket).
warn_redundant_casts = true
no_implicit_reexport = false

# `exclude` above removes test files from the checked set, but it does NOT apply
# to files pulled in by an import. `_algorithm/oracle_models.py` imports the
# layer classes from `_etrace_model_test.py` (deliberately -- the oracle wraps
# those models rather than duplicating them), which re-admits that file and
# surfaces its `brainpy.state.*` attribute errors. Those come from brainpy's
# dynamic re-exports, the same reason `brainpy.*` is listed as untyped below;
# they are not our errors, and the file is already outside the typed public
# surface by the `exclude` policy. Suppress reporting for it specifically so the
# policy holds however the file is reached.
[[tool.mypy.overrides]]
module = ["braintrace._etrace_model_test"]
ignore_errors = true

# Third-party scientific deps that ship without inline types or a py.typed
# marker. Scoped per-module so missing stubs here never mask errors in our
# own code.
[[tool.mypy.overrides]]
module = [
    "brainstate.*",
    "braintools.*",
    "brainpy.*",
    "brainevent.*",
    "numba.*",
]
ignore_missing_imports = true

# brainunit ships a py.typed marker, but its public API (brainunit.math.*,
# Quantity, units, ...) is merely re-exported via `from saiunit... import *`,
# and saiunit ships NO py.typed. mypy therefore cannot resolve any of the
# re-exported names and emits spurious `attr-defined` errors at every call
# site. Skip following both packages so they are treated as untyped (Any),
# matching how saiunit itself was handled before it was renamed to brainunit.
[[tool.mypy.overrides]]
module = [
    "brainunit",
    "brainunit.*",
    "saiunit",
    "saiunit.*",
]
follow_imports = "skip"
ignore_missing_imports = true

# Public-API surface: every def in these modules must be fully annotated. This
# is what makes "every public API is typed" a property mypy enforces, so it
# cannot silently regress. Explicit module list (no wildcards) so internal /
# test-helper modules are not dragged in. Later changes append to this list.
[[tool.mypy.overrides]]
module = [
    "braintrace._typing",
    "braintrace._op.dense",
    "braintrace._op.elemwise",
    "braintrace._op.conv",
    "braintrace._op.sparse",
    "braintrace._op.lora",
    "braintrace._op._primitive",
    "braintrace._op",
    "braintrace._compile",
    "braintrace",
    "braintrace._input_data",
    "braintrace._grad_exponential",
    "braintrace._misc",
    "braintrace.nn._linear",
    "braintrace.nn._conv",
    "braintrace.nn._readout",
    "braintrace.nn._rnn",
    "braintrace.nn",
    "braintrace._algorithm.base",
    "braintrace._algorithm.graph_executor",
    "braintrace._algorithm.vjp_base",
    "braintrace._algorithm.vjp_graph_executor",
    "braintrace._algorithm.param_dim_vjp",
    "braintrace._algorithm.io_dim_vjp",
    "braintrace._algorithm.d_rtrl",
    "braintrace._algorithm.pp_prop",
    "braintrace._algorithm.e_prop",
    "braintrace._algorithm.ostl",
    "braintrace._algorithm.otpe",
    "braintrace._algorithm.ottt",
    "braintrace._algorithm.osttp",
    "braintrace._algorithm._common",
    "braintrace._algorithm",
]
disallow_untyped_defs = true


# Coverage configuration (coverage.py / pytest-cov). The measured surface is the
# shipped `braintrace` package only: co-located `*_test.py` files and the
# test-only helper modules (mirroring the mypy `exclude` list) are omitted so the
# reported percentage reflects real source coverage rather than the tests
# exercising themselves.
[tool.coverage.run]
source = ["braintrace"]
omit = [
    "*_test.py",
    "*/model4test.py",
    "*/scenario_catalog.py",
    "*/oracle_models.py",
]

[tool.coverage.report]
show_missing = true
exclude_lines = [
    "pragma: no cover",
    "raise NotImplementedError",
    "raise AssertionError",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
    "@(abc\\.)?abstractmethod",
    "\\.\\.\\.",
]