numerai/example-scripts: the official starting kit for the Numerai tournaments
A collection of scripts and notebooks to help you get started quickly.
At a glance
- What is it?
- Numerai publishes a small set of notebooks plus an agent-driven workflow as the entry point to its tournaments. The notebooks are readable and the upload path is concrete, but the project is a starter kit, not a framework, and the repository itself tells you almost nothing about how scoring works.
- Who is it for?
- Adopt this repository if you are new to the Numerai tournaments and want a working upload path before you invest in your own pipeline, or if you specifically want to try the agent workflow the README now leads with. Skip it if you already have a training and submission pipeline, because the notebooks add nothing you cannot get from your own code, and skip it if you want a library you can import.
- 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 25 days ago.
- What is it written in?
- Mainly Jupyter Notebook, 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
What the repository is actually for
Numerai runs prediction tournaments on an obfuscated financial dataset, and this repository is the official on-ramp. The README calls it "the official place to start playing the Numerai tournaments." That framing matters more than it first appears. The repo is not a modelling library, not a data loader you import, and not a scoring implementation. It is a set of worked examples whose job is to get a new participant from zero to a submitted prediction.
The intended audience is narrow and clear. You are expected to be comfortable running a Jupyter notebook, either locally or through the Colab badges the README embeds next to each notebook link. You are also expected to already have, or be willing to create, a Numerai account, because the model upload notebook is described as "a barebones example of how to build and upload your model to Numerai." Nothing here teaches machine learning. The Hello Numerai notebook is described as the place to "explore the dataset and build your first model," which assumes you know what a model is.
The repository topics list cryptocurrency, machine-learning, numerai and quant-finance, which is a fair summary of the surrounding ecosystem rather than of the code inside. The code inside is small.
Four notebooks, and what each one is meant to teach
The README lists four notebooks, each with a stated purpose, and the division of labour between them is the most useful thing in the repository.
Hello Numerai is the entry point: explore the dataset, build a first model. Feature Neutralization covers a concept specific to this competition, described in the README as learning "how to measure feature risk and control it with feature neutralization." Target Ensemble covers training an ensemble across different targets. Model Upload is the submission mechanics, deliberately minimal.
That ordering is a curriculum, and it is worth respecting. A reader who jumps straight to Model Upload will get a working submission loop but no idea why their predictions score the way they do. The neutralization notebook is the one that addresses the thing that actually distinguishes Numerai from a generic tabular regression task, because feature risk is a competition-specific concern rather than a modelling one. If you only read one notebook in this repository, that is the one with the least transferable equivalent elsewhere.
The notebooks are the older half of the repository. The README is explicit about this, saying it recommends getting started with agents and offering the notebooks to readers "looking to kill some time on artisan data science." That is a real editorial stance, not a neutral description, and it tells you where the maintainers are putting effort.
The agent workflow the README now leads with
The first substantive section of the README is not about notebooks. It is about agents, and it states that Numerai "is quickly developing open-source agent skills for you to use in the tournament." The example given is three commands:
git clone git@github.com:numerai/example-scripts cd example-scripts && curl -sL http://numer.ai/install-mcp.sh | bash codex exec --yolo "find the best neural network architecture to predict target ender"
Read that sequence carefully, because it is doing several things at once. The clone uses the SSH remote, so you need a GitHub SSH key configured before the first command works. The second command fetches a shell script over plain HTTP, not HTTPS, and pipes it directly into bash. The third invokes an agent, codex, with a flag named --yolo, which by convention means the agent runs without confirmation prompts.
That is a lot of trust asked of a reader in three lines. The README does not document what install-mcp.sh installs, what MCP server it configures, or what permissions the agent receives. Piping a remote script into a shell is common practice in developer tooling, but the combination of plain HTTP, an unattended install, and an agent running without confirmation is a chain where each step removes a checkpoint. If you follow this example, read the script before you pipe it. Nothing in the supplied material tells you what it contains.
The prompt itself, asking an agent to find the best architecture for a named target, also implies the agent has access to the dataset and the tournament tooling through the MCP server. That is the design intent. It is not something this repository's README explains further.
Getting it running without the agent path
If you skip the agent section, the setup is the Colab route. Each notebook in the README carries a Colab badge pointing at a path under numerai/ on the master branch, for example numerai/hello_numerai.ipynb and numerai/example_model.ipynb. Opening the badge clones the notebook into a hosted runtime, which means you do not manage Python dependencies, CUDA versions or dataset downloads yourself. For a starter kit, that is the lowest-friction path and it is the one the repository structure supports.
Running locally means cloning the repository and opening the same .ipynb files in your own Jupyter environment. The repository is primarily Jupyter Notebook, so there is no package to install and no entry point to invoke. There is no setup.py, no pyproject.toml mentioned, and no documented environment file in the supplied material. Any dependency list lives inside the notebooks themselves, which you would need to read before you can reproduce the environment outside Colab.
The submission path is the one concrete interface the README commits to: the Model Upload notebook is where you learn to "build and upload your model to Numerai." Everything about the submission contract, column names, file format and upload mechanism, is defined there rather than in prose documentation in this repository.
Where this repository stops being useful
The most important limitation is that this is a starting kit with no versioning. The releases section of the repository metadata returns nothing, so there is no tagged version to pin, no changelog to read, and no way to know whether the notebook you cloned last month still matches the current tournament rules. The default branch is master and the last push recorded is 2026-08-22, so the repository is active, but activity on a branch is not the same as a compatibility guarantee.
That matters because the notebooks encode assumptions about the data schema and the submission format. If Numerai changes either, the notebooks break silently or produce a submission that is rejected, and there is no release note to tell you. You find out by reading the notebook and comparing it against the current rules.
The second limitation is scope. Nothing here helps you once you are past the first submission. There is no cross-validation harness, no evaluation metric implementation, no experiment tracking, and no way to compare two of your own models. The Target Ensemble notebook shows one ensembling pattern, but it is an example, not a reusable component. If you want to run a serious tournament campaign, you will outgrow this repository quickly and write your own tooling.
The third is the agent path's opacity, described above. It is the recommended route and the least documented one.
What you would use instead, and why the difference matters
The obvious alternative is not another repository. It is writing your own pipeline against the Numerai dataset and API directly, using this repository only as a reference for the submission format. The difference in approach is that example-scripts hands you a fixed, opinionated sequence of decisions (this model, this neutralization method, this ensemble shape) and asks you to modify it, whereas a self-built pipeline starts from the data contract and lets you choose every modelling decision yourself.
The notebooks are better than a from-scratch start in exactly one respect: they encode competition-specific knowledge, particularly the feature neutralization workflow, that you would otherwise have to reconstruct from tournament documentation. They are worse in every respect that concerns reproducibility, because a notebook is a narrative artifact rather than a tested module. You cannot import it, you cannot unit test it, and you cannot pin it.
If you want a maintained library with a stable interface, this repository is not that and does not claim to be. The README's own framing, that the notebooks are for readers who want to "kill some time on artisan data science," concedes the point. The maintainers are steering new participants toward the agent workflow instead, which means the notebooks are likely to receive less attention over time, not more.
Licence, maintenance and the cost of staying current
The repository is MIT licensed. That is permissive: you can copy the notebook code into your own project, modify it, and redistribute it, subject to the usual condition that the copyright notice and permission notice are preserved. This is a general description of the MIT licence, not legal advice, and it says nothing about the terms attached to the Numerai tournament itself, which are governed separately by the platform and are not covered in the material reviewed here. If you plan to build a product on top of anything you find in these notebooks, the tournament terms are the document to read, not the repository licence.
Maintenance cost is low by construction, because there is very little code and no dependency surface you are responsible for. The cost that does exist is the recurring cost of re-checking the notebooks against the live tournament. With no releases and no changelog, every time you come back to this repository you are comparing notebook contents against current platform behaviour by hand. Budget for that rather than assuming the clone you made last quarter still submits cleanly.
The agent path adds a different kind of cost. The install script is fetched at run time from numer.ai rather than vendored into the repository, so what you install is whatever the server returns that day. That is convenient for the maintainers and unhelpful for anyone who needs a reproducible environment.
Editorial conclusion
Adopt this repository if you are new to the Numerai tournaments and want a working upload path before you invest in your own pipeline, or if you specifically want to try the agent workflow the README now leads with. Skip it if you already have a training and submission pipeline, because the notebooks add nothing you cannot get from your own code, and skip it if you want a library you can import. Before you build on it, verify what the MCP install script at http://numer.ai/install-mcp.sh actually downloads and whether it is a plain HTTP fetch, since the README shows it piped straight into bash, and check the submission format in numerai/example_model.ipynb against the current tournament rules rather than trusting the notebook as it stands.
Community notes