Create Numerai Tournament model upload pickles (.pkl) with a self-contained predict() function. Use when preparing upload artifacts, debugging numerai_predict import errors, or documenting model-upload requirements and testing steps.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Create Numerai Tournament model upload pickles (.pkl) with a self-contained predict() function. Use when preparing upload artifacts, debugging numerai_predict import errors, or documenting model-upload requirements and testing steps.
Numerai Model Upload
Overview
Create a portable predict(live_features, live_benchmark_models) pickle that runs inside Numerai's numerai_predict container without repo dependencies.
CRITICAL: Python Version Compatibility
Before creating any pkl file, you must ensure your Python environment matches Numerai's compute environment. Mismatched versions cause segfaults and validation failures due to binary incompatibility (especially with numpy).
Step 1: Query the Default Docker Image (MCP Required)
If the numerai MCP server is available, always query the default Python version first:
query{ computePickleDockerImages { id name image tag default }}
Look for the entry with default: true. The image name indicates the Python version:
numerai_predict_py_3_12:a78dedd → Python 3.12 (current default as of 2026)
numerai_predict_py_3_11:a78dedd → Python 3.11
numerai_predict_py_3_10:a78dedd → Python 3.10
If the numerai MCP is not installed, it can be installed through our install script via curl -sL https://numer.ai/install-mcp.sh | bash, this script guides the user through installing the MCP for Codex CLI and configuring an API key with the correct scopes that are required by MCP.
Step 2: Create Matching Virtual Environment with pyenv
Use pyenv to create a virtual environment with the exact Python version:
# 1. List available pyenv Python versionsls ~/.pyenv/versions/
# 2. Find the matching minor version (e.g., for Python 3.12)
PYENV_PY=$(ls -d ~/.pyenv/versions/3.12.* 2>/dev/null | head -1)
# 3. Create the virtual environment$PYENV_PY/bin/python -m venv ./venv
# 4. Activate and install pkl dependenciessource ./venv/bin/activate
pip install --upgrade pip
pip install numpy pandas cloudpickle scipy
# Add lightgbm, torch, etc. only if your model needs them
Step 3: Create pkl in the Correct Environment
Always create pkl files using the matching venv:
./venv/bin/python create_model_pkl.py
Requirements
Implement predict(live_features, live_benchmark_models) and return a DataFrame with a prediction column aligned to the input index.
Avoid imports from local repo modules (no agents.*), because Numerai's container will not have them.
Prefer numpy/pandas/scipy-only inference; do not rely on torch/xgboost unless you verify the container has those packages.
Move any trained model to CPU before exporting and store plain numpy weights.
Validate required columns (era for per-era ranking, benchmark column if used).
Workflow
Query the default Docker image from the MCP to determine the required Python version.
Create/activate a matching venv using pyenv (see above).
Train on the desired full dataset (train + validation) with the same preprocessing and early-stopping scheme as the best model only after your research has plateaued and you have selected the final configuration to deploy.
Export an inference bundle from the trained model:
Feature list and ordering
Imputation values and scaling stats
Model weights/biases (numpy arrays)
Activation name and any constants
Benchmark column name if needed as a feature
Build a predict function that:
Reads only from the bundle and standard libraries
Applies preprocessing and a numpy forward pass
Ranks predictions per era to [0, 1] when required
cloudpickle.dump(predict, "model.pkl") using the matching venv's Python.
Test the pickle with the Numerai container before uploading.
Testing
Run the Numerai debug container locally (use the same image tag as the default):
# Get the default image tag from MCP query, then test:
docker run -i --rm -v "$PWD:$PWD" ghcr.io/numerai/numerai_predict_py_3_12:a78dedd --debug --model $PWD/[PICKLE_FILE]
Common Pitfalls
Segmentation fault / numpy binary incompatibility: The pkl was created with a different Python version than Numerai's container. Always query the default docker image first and create pkl files using a matching pyenv-based venv.
ImportError: No module named 'agents': occurs when the pickle references repo classes. Fix by exporting a pure-numpy inference bundle and rebuilding predict without repo imports.
Missing era column: per-era ranking requires live_features["era"].
Benchmark misalignment: ensure live_benchmark_models is reindexed to live_features (by id) before use.
Feature drift: ensure feature order in inference matches training order exactly.
Debugging Validation Failures
If your pickle fails validation, query the trigger status and logs:
query{
account {
models {
username
computePickleUpload {
filename
validationStatus
triggerStatus
triggers {
id
status
statuses {
status
description
insertedAt
}}}}}}
Common error descriptions:
"Segmentation fault! Ensure python and library versions match our environment." → Python/numpy version mismatch
"No currently open rounds!" → Model validated successfully but no round is open for submission
Reference
Use numerai/example_model.ipynb for the expected predict signature and output format.
Deploying to Numerai via MCP Server
After creating and testing your pkl file, you can deploy it to Numerai using the Numerai MCP server. The MCP server provides tools for creating models and uploading pkl files programmatically.
Available MCP Tools
The numerai MCP server provides these key tools:
check_api_credentials - Verify your API token and see granted scopes
