Markdown Converter
Agent skill for markdown-converter
This repository contains example scripts and an agentic research framework for the [Numerai data science tournaments](https://numer.ai/). AI coding agents can use this file to understand how to help with Numerai-related tasks.
Sign in to like and favorite skills
This repository contains example scripts and an agentic research framework for the Numerai data science tournaments. AI coding agents can use this file to understand how to help with Numerai-related tasks.
| Task | Resource |
|---|---|
| Run experiments | skill |
| Add new model types | skill |
| Create & deploy pkl files | skill |
| Query tournament data | Numerai MCP server |
| Upload models programmatically | Numerai MCP server |
"Numerai" is the original tournament in which you are provided anonymized and obfuscated data. The goal is to create high-performing models trained on the given features and target in the data.
"Signals" is the second tournament in which you are expected build your own stock market dataset. You are given a basic dataset with a target and rudimentary features. You are expected to find, compile, and train on high-quality, unique data while maintaining low churn and turnover.
"Crypto" is a toy tournament for cryptocurrency prediction. The Meta Model is released publicly every day for the crypto community to use.
example-scripts/ ├── numerai/ │ ├── agents/ # Agentic research framework │ │ ├── AGENTS.md # Detailed agent instructions │ │ ├── baselines/ # Baseline model configurations │ │ ├── code/ # Shared packages │ │ │ ├── analysis/ # Reporting & plotting │ │ │ ├── data/ # Dataset builders │ │ │ ├── metrics/ # BMC/corr scoring utilities │ │ │ └── modeling/ # Training pipeline & model wrappers │ │ ├── experiments/ # Experiment results (not in git) │ │ └── skills/ # Codex skills for agent workflows │ └── *.ipynb # Tournament-specific notebooks ├── signals/ # Signals tournament examples ├── crypto/ # Crypto tournament examples ├── cached-pickles/ # Pre-built model pickles
The
numerai/agents/skills/ folder contains structured workflows for common tasks. Each skill has a SKILL.md file with detailed instructions.
numerai-experiment-designPurpose: Design, run, and report Numerai experiments for any model idea.
When to use:
Key workflow:
agents/experiments/<name>/configs/python -m agents.code.modeling --config <config>Entry points:
python -m agents.code.modeling --config <config_path>python -m agents.code.analysis.show_experimentpython -m agents.code.data.build_full_datasetsnumerai-model-implementationPurpose: Add new model types to the training pipeline.
When to use:
Key steps:
agents/code/modeling/models/agents/code/modeling/utils/model_factory.pynumerai-model-uploadPurpose: Create and deploy pickle files for Numerai's automated submission system.
When to use:
Critical requirements:
predict(live_features, live_benchmark_models) signature requiredWorkflow:
predict functionnumerai_predict Docker containerThe
numerai MCP server provides programmatic access to the Numerai Tournament API. If available, agents should use it for tournament operations.
It can be installed via curl through:
curl -sL https://numer.ai/install-mcp.sh | bash
This install script sets Codex CLI up with the MCP configuration as well as configures an environment variable for an MCP API key.
| Tool | Purpose |
|---|---|
| Verify API token and scopes |
| Create new model slots |
| Upload pkl files (multi-step workflow) |
| Query model stats |
| Get round-by-round performance |
| View tournament rankings |
| List active tournaments |
| Get current round info |
| List available dataset files |
| Run diagnostics on predictions |
| Execute custom GraphQL queries |
corr20Rep - 20-day rolling correlation score (main metric)mmc20Rep - Meta-model contribution (unique signal)return13Weeks - 13-week return on staked NMRnmrStaked - Amount of NMR stakedMCP tools require a Numerai API token with appropriate scopes:
Authorization: Token PUBLIC_ID$SECRET_KEYNUMERAI_MCP_AUTH environment variable.export NUMERAI_MCP_AUTH="Token PUBLIC_ID\$SECRET_KEY"
Since the PUBLIC_ID and SECRET_KEY are separated by a $ character, it likely needs to be escaped when set through the export command.
List account's models:
query { account { models { id name } } }
Get default Python runtime:
query { computePickleDockerImages { id name image tag default } }
Check pickle validation status:
query { account { models { username computePickleUpload { filename validationStatus triggerStatus triggers { id status statuses { status description insertedAt } } } } } }
1. create_model(name, tournament=8) # Optional: create new model slot 2. upload_model(operation="get_upload_auth") # Get presigned S3 URL 3. PUT file to presigned URL # Upload the pkl file 4. upload_model(operation="create") # Register upload 5. upload_model(operation="list") # Wait for validation 6. upload_model(operation="assign") # Assign to model slot
CRITICAL: Pickle files must be created with a Python version matching Numerai's compute environment to avoid segfaults and binary incompatibility.
# 1. Query default Docker image (via MCP) to get Python version # Look for default: true, e.g., numerai_predict_py_3_12 = Python 3.12 # 2. Create matching venv with pyenv PYENV_PY=$(ls -d ~/.pyenv/versions/3.12.* 2>/dev/null | head -1) $PYENV_PY/bin/python -m venv ./venv # 3. Activate and install dependencies source ./venv/bin/activate pip install numpy pandas cloudpickle scipy lightgbm
docker run -i --rm -v "$PWD:$PWD" \ ghcr.io/numerai/numerai_predict_py_3_12:a78dedd \ --debug --model $PWD/model.pkl
pipeline.py, numerai_cv.py, and metrics stay genericagents/code/modeling/models/ wrappersBuild datasets with
python -m agents.code.data.build_full_datasets:
| File | Description |
|---|---|
| Full training data |
| Benchmark model predictions |
| Every 4th era (fast iteration) |
| Downsampled benchmarks |
numerai/agents/AGENTS.md for detailed instructionsnumerai/agents/skills/numerai/agents/experiments/numerai-model-upload skillhello_numerai.ipynb for basicsfeature_neutralization.ipynb for feature risktarget_ensemble.ipynb for ensemble strategiesnumerai/ (so agents is importable), or from repo root with PYTHONPATH=numerainumerai/<data_version>/ (e.g. numerai/v5.2/), which is often gitignored locallyln -s $PWD/numerai/agents/skills/* ~/.codex/skills/--yolo flag)v52_lgbm_ender20 benchmark predictions in *_benchmark_models.parquet