facebookresearch/neuroai: four Python packages for neuroscience data, training and benchmarks

What problem facebookresearch/neuroai is meant to solve

Neuroscience groups tend to accumulate private pipelines. One lab has a loader for spike trains, another has a script that pulls EEG from a public archive, a third has a training loop that only its author understands. Comparing results across those setups is difficult because the data representation and the training code differ before any modelling choice is made. The neuroai repository is an attempt to standardise that middle layer. It is organised as four sibling packages, each with its own repository directory at the top level: neuralset-repo, neuralfetch-repo, neuraltrain-repo and neuralbench-repo. NeuralSet is the data loader, NeuralFetch retrieves datasets, NeuralTrain handles model training, and NeuralBench provides a unified benchmark. The intended audience is researchers who write Python and already understand their modality, whether that is electrophysiology, fMRI or something else. The README describes the suite as a Python set of tools for neuroscience research across all modalities, and the citation points to a paper titled NeuralSet: A High-Performing Python Package for Neuro-AI. Nothing in the repository suggests it targets clinicians or people who want a graphical application.

How the four packages fit together

The split is deliberate. NeuralFetch is the entry point for data: it fetches curated datasets rather than asking you to download archives by hand. NeuralSet then turns those recordings into an efficient loader, which is the piece the paper is about and the piece the project treats as its main technical contribution. NeuralTrain sits above that and handles training at scale, and NeuralBench provides the comparison layer so that numbers from different models are measured the same way. The README also names a related project, exca, described as the execution and caching framework powering neuroai's backbone. That detail matters more than it first appears: caching and execution control are inherited from exca rather than reimplemented here, so the reproducibility story depends on a dependency outside the four packages. The root pyproject.toml is not the package definition for any of the four. Its own comment says it is used for the pre-commit hooks and when running from the root folder, for example in CI, and it carries a uv configuration with an exclude-newer window of three days so that compromised uploads get flagged before they are pulled in. That is a supply-chain precaution, and it is applied at the repository root rather than inside each package.

Installing NeuralSet and running a first fetch

Each package installs on its own. The README gives one pip command per package, and there is no documented meta-package that pulls in all four, so you install what you need. Python 3.12 or newer is required according to the badge in the README.

pip install neuralset

That installs the data loader only. If your recordings are not already on disk in a format NeuralSet understands, the next step is the fetch package, which the README describes as the way to get curated datasets.

pip install neuralfetch

Once a dataset is available locally, NeuralSet is what you point your training code at. The README does not reproduce a loader example inline; it directs readers to the documentation site at facebookresearch.github.io/neuroai for interactive quickstarts and step-by-step tutorials, and the per-package documentation pages are linked from each package section. Treat that site as the source for the actual API surface, because the README itself stops at installation. If you plan to train rather than just load, the remaining two commands are the same shape.

pip install neuraltrain
pip install neuralbench

The root pyproject.toml is worth reading before you set up a development environment, because it pins an unusual dependency window. The uv configuration excludes releases younger than three days, with explicit exemptions for exca and submitit, and a deliberate date pin for braindecode at 2026-08-31, which the comment ties to version 1.8.1 as the first release shipping the emg and pose models. If you install the packages individually with pip rather than through the root uv setup, you do not inherit that window, and the comment warns that a package pin replaces the window, so bumping that date should be done on purpose.

Where the suite will not help you

The most obvious limitation is packaging. Four separate pip installs with no documented umbrella package means version drift between NeuralSet and NeuralTrain is possible, and the README does not describe a compatibility matrix between them. If you install NeuralSet today and NeuralTrain in three months, nothing in the repository states that the pair is tested together. The second limitation is scope. NeuralFetch supplies curated datasets, which is useful when your data is one of those datasets and useless when it is not; the README does not document a path for arbitrary private recordings beyond what NeuralSet can load. Third, the repository leans on exca for execution and caching. That is a reasonable design choice, but it means a bug in caching behaviour is not fixed in this repository. Finally, the README does not document rollback, migration between minor versions, or a deprecation policy, and the CHANGELOG is present at the root without its contents being reproduced. If you need a stack that will not change under you during a multi-year study, that silence is the thing to resolve before you commit.

How it differs from Braindecode

Braindecode appears in this repository only as a pinned dependency in the root pyproject.toml, dated 2026-08-31 and tied to version 1.8.1 for its emg and pose models. The two projects do not take the same approach. Braindecode is a library for decoding EEG and related signals, with its own model zoo and preprocessing conventions, and it is treated here as an external input rather than a competitor. Neuroai's own framing is a pipeline: fetch data, load it efficiently, train, benchmark. That makes it broader in intent but thinner at any single step than a library dedicated to one modality. If your work is EEG decoding with established architectures, the pinned dependency suggests Braindecode is doing real work inside this stack rather than being replaced by it. If your work spans modalities and the bottleneck is the loader and the comparison harness, the four-package split is the reason to look here instead.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-10. Releases have been frequent in the period covered by the release list: v0.2.3 on 2026-07-31, v0.3.0 on 2026-09-09, and v0.3.1 on 2026-09-10. A patch release one day after a minor release is worth noting, since it suggests the minor version needed a quick correction, though the repository does not say what changed. The licence is MIT, stated in the README badge and in the LICENSE file, which permits commercial and academic use with attribution. The README adds that references to third-party content are subject to their own licences, which is relevant here because the stack depends on exca, submitit and braindecode. MIT on this repository does not automatically extend to those. The citation request asks that research use cite the NeuralSet paper, which is a convention rather than a licence term. Upgrade cost is hard to judge: the README does not document a migration guide, and the CHANGELOG exists at the root but its contents are not reproduced here, so anyone planning a version bump should read it directly.

Editorial conclusion

Adopt this if your group already works with neural recordings in Python and wants a shared data-loading and training layer instead of another in-house pipeline; skip it if you need a single install that covers preprocessing end to end, because the repository ships four separate packages and the README points you to the documentation site for the tutorials. Before committing, check that your Python is 3.12 or newer, read the NeuralSet paper for what the loader actually guarantees, and confirm which of the four packages you need, since installing all of them is not the documented path.

Frequently asked questions

Official sources

1. facebookresearch/neuroai on GitHub
2. License: MIT
3. Project website
4. README
5. Releases