facebookresearch/neuroai: four packages for NeuroAI data, training and benchmarking
Python suite for neuroscience research across all modalities.
At a glance
- What is it?
- The repository is a Python suite split into NeuralSet, NeuralFetch, NeuralTrain and NeuralBench, all installable separately from PyPI under MIT. The split is the interesting part, and so is the fact that the README tells you almost nothing about how any of them work.
- Who is it for?
- Adopt neuroai if your work is NeuroAI model training and you want a data loader, a dataset fetcher, a training loop and a benchmark from one organisation rather than wiring four unrelated libraries together. Do not adopt it if you need a mature, widely deployed framework with years of third-party tutorials, or if you are on Python 3.10 or 3.11, since the badge states 3.12+ and that is a hard floor rather than a suggestion.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is that NeuroAI pipelines are four unrelated problems wearing one lab coat
Neuroscience data arrives as EEG, MEG, fMRI, spikes and whatever else a collaborator shipped on a drive. Model code arrives as PyTorch. Evaluation arrives as a script someone wrote for one paper. Gluing these together is the actual work, and it is the work nobody publishes. The neuroai repository is an attempt to name the four seams and give each one a package: NeuralSet for the data loader, NeuralFetch for getting curated datasets, NeuralTrain for training at scale, NeuralBench for a unified benchmark. The intended user is a researcher or engineer who already knows their modality and their model architecture and does not want to rebuild the plumbing. The README's own phrasing is minimal, describing NeuralSet as a way to build an efficient Neuro AI data loader and NeuralTrain as a way to train Neuro AI models at scale. That is the entire scope statement. If you are looking for a library that teaches you neuroscience, this is not it. If you are looking for one that assumes you already have the science and only want the infrastructure, the package boundaries suggest that is the target.
Four packages, four installs, and a backbone called exca
The architecture visible in the README is a set of independently installable PyPI distributions rather than one monolithic import. Each has its own pip install line: neuralset, neuralfetch, neuraltrain, neuralbench. That means you can take the data loader without taking the training loop, which matters if your lab already standardised on a different trainer. The README also names a related project, exca, described as the execution and caching framework powering neuroai's backbone. This is the one architectural detail the README volunteers, and it is worth reading carefully: it implies that job execution and caching are not implemented inside the four packages but delegated downward to exca. The practical consequence is that configuration, caching and re-execution semantics are exca's problem, and if you want to understand why a training run did or did not re-execute, the neuroai documentation may not be where the answer lives. The README does not describe the data flow between NeuralFetch and NeuralSet, or between NeuralSet and NeuralTrain. Based on the package names alone, the plausible reading is fetch then load then train then benchmark, but the README does not state this and I am not going to assert it as fact.
Getting it running: four commands and a Python 3.12 floor
Installation is deliberately unglamorous. The README gives exactly four commands, one per package: pip install neuralset, pip install neuralfetch, pip install neuraltrain, pip install neuralbench. There is no meta-package documented in the README, so installing all four means running all four commands. The Python badge states 3.12+, which is a recent floor and will rule out environments pinned to 3.10 or 3.11 for other dependencies. The README does not list the transitive dependency set, so the size of the install is not something you can predict from this material. There is a CI badge pointing at a GitHub Actions workflow and a documentation badge pointing at facebookresearch.github.io/neuroai/, and the README directs readers there for interactive quickstarts, step-by-step tutorials and the complete API reference. That is the honest answer to how you configure any of this: the README hands you off. No config keys, no YAML schema, no environment variables appear in the README itself. If you need to know what a NeuralSet config file looks like, the README is not the source.
The documentation gap is the real adoption cost
A README that is mostly badges and four install lines tells you the project expects you to live in its docs site. That is a reasonable choice for a research repository, and it is also a real cost. Three of the four package descriptions are single sentences with no example. NeuralBench is described as a unified benchmark for NeuroAI models, which raises more questions than it answers: which models, which tasks, which metrics, and what a submission looks like. None of that is in the README. The citation block points to a paper titled NeuralSet: A High-Performing Python Package for Neuro-AI, which suggests the deepest technical description of at least the data loader lives in arXiv:2605.03169 rather than in the repository. For an engineer deciding whether to adopt, that changes the evaluation order: read the paper for NeuralSet, read the docs site for the other three, and treat the README as an index rather than a manual. The repository is not archived and the release cadence visible in the material is active, with v0.3.1 on 2026-09-10 and v0.3.0 the day before, which suggests a project still moving rather than frozen.
Where neuroai is the wrong tool
The clearest failure mode is version pinning. A Python 3.12+ requirement is not unusual in 2026, but it is incompatible with plenty of lab and cluster images, and the README offers no backport path or older-Python branch. If your institution's shared environment is on 3.11, you are either rebuilding the environment or not using this. A second limitation is the benchmark claim. NeuralBench is described as unified, but the README does not enumerate what is unified, and a benchmark is only useful if the tasks and splits are fixed and comparable across papers. Until you read the docs, you cannot tell whether NeuralBench gives you a leaderboard, a harness, or a set of dataset loaders with agreed splits. Those are very different commitments. A third issue is the exca dependency. Because caching is delegated, debugging a stale result means understanding a second project's semantics, and the README gives no indication of whether exca is a hard dependency of all four packages or only some. Finally, the version numbers are still in 0.x. A 0.x series can be perfectly usable, but it also means the maintainers have not promised API stability, and a suite of four packages multiplies the surface area where a breaking change can land.
What it is up against, and how the approach differs
The obvious comparison is to the general-purpose scientific Python stack that most neuroscience labs already run: MNE for MEG and EEG handling, plus a generic PyTorch training loop. The difference is one of opinionation. MNE is a signal-processing and data-structure library with a long history and no opinion about how you train a model. neuroai is the opposite: it bundles fetching, loading, training and benchmarking into one named suite, which means it can make assumptions across those layers that MNE cannot. Whether that is an advantage depends entirely on whether its assumptions match yours. If your pipeline is standard, the bundled version saves integration work. If your pipeline is unusual, the bundled version is a set of constraints you will spend time working around. The second comparison is to writing your own loader. A custom PyTorch Dataset is a few dozen lines and you understand every one of them. NeuralSet's value proposition, per its own paper title, is performance, and that is a claim you should verify against your own modality rather than accept. The trade is real: you give up transparency for a loader someone else has tuned.
Maintenance, licence and what the upgrade path looks like
The licence is MIT, stated in the README and linked to a LICENSE file. MIT is permissive: it allows commercial and academic use, modification and redistribution, with the requirement that the licence text and copyright notice be preserved. This is not legal advice, and the README adds a note that references to third-party content are subject to their own licenses, which matters because NeuralFetch pulls curated datasets and those datasets carry their own terms. Check the licence of each dataset you fetch, not just the licence of the code that fetches it. On maintenance, the material shows a release on 2026-09-10 and another the previous day, so the project is being actively cut. The upgrade cost is the four-package structure: a breaking change in NeuralSet does not force an upgrade in NeuralBench, which is good, but it also means version skew between the four is possible and the README does not describe a compatibility matrix. Pin all four together unless the docs say otherwise. The 0.x version numbers mean you should read the release notes for each bump rather than assuming a patch release is inert.
Editorial conclusion
Adopt neuroai if your work is NeuroAI model training and you want a data loader, a dataset fetcher, a training loop and a benchmark from one organisation rather than wiring four unrelated libraries together. Do not adopt it if you need a mature, widely deployed framework with years of third-party tutorials, or if you are on Python 3.10 or 3.11, since the badge states 3.12+ and that is a hard floor rather than a suggestion. Before committing, verify three things: that the datasets you actually need are present in NeuralFetch, that NeuralSet's loader matches your modality's sampling rate and channel layout, and that exca's caching behaviour fits your storage budget, because the README names exca as the backbone and never explains what it caches or where.
Community notes