Add reproducible v4 weekly champion release

README.md

@@ -0,0 +1,101 @@
+---
+tags:
+  - numerai
+  - tabular-regression
+  - finance
+  - lightgbm
+  - catboost
+  - weekly-model
+pipeline_tag: tabular-regression
+---
+
+# Numerai Weekly Champion v4
+
+This repository publishes the exact model bundle currently used by Noptus' validated Numerai submission pipeline. It is intended as a reproducible research artifact and a starting point for ensemble-diversity work—not as investment advice or a promise of tournament performance.
+
+## Current release
+
+- Release: `v4-20260801-180455`
+- Verified live round: `1333`
+- Data schema: Numerai `v5.2`
+- Inputs: 780 `medium` features plus 8 public benchmark-model columns
+- Components: two benchmark-aware LightGBM models, six multi-target LightGBM models, one residual LightGBM model, and one CatBoost model
+- Bundle size: approximately 142 MiB
+- SHA-256: `79db5f41f3506e8e10a8b96c60a927f6a9ca202e49e03304ceaa9d304116b8d9`
+
+The bundle was promoted over the previous local champion on a 57-era untouched holdout:
+
+| Metric | v4 | previous champion |
+|---|---:|---:|
+| Mean Numerai CORR | 0.010453 | 0.001821 |
+| Sharpe | 0.7712 | 0.1499 |
+| Positive-era consistency | 75.44% | 52.63% |
+| Maximum drawdown proxy | -0.01360 | -0.02329 |
+
+These are historical offline measurements, not live-performance guarantees. The model remains experimental, can decay under regime change, and should not be used to make financial decisions.
+
+## Load and predict
+
+Install the pinned runtime dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Download the files and run inference on the public Numerai live and benchmark-model frames:
+
+```python
+from huggingface_hub import hf_hub_download
+import joblib
+import pandas as pd
+
+from inference import predict_ranked
+
+repo_id = "Noptus/numerai-weekly-v4"
+model_path = hf_hub_download(repo_id, "ensemble_v4.pkl")
+bundle = joblib.load(model_path)
+
+live = pd.read_parquet("live.parquet")
+benchmarks = pd.read_parquet("live_benchmark_models.parquet")
+benchmark_columns = [c for c in benchmarks.columns if c != "era"]
+live = live.join(benchmarks[benchmark_columns], how="left")
+
+submission = pd.DataFrame(
+    {"prediction": predict_ranked(live, bundle)},
+    index=live.index,
+)
+submission.index.name = "id"
+submission.to_csv("predictions.csv")
+```
+
+The included command-line entry point performs the same base inference:
+
+```bash
+python inference.py \
+  --model ensemble_v4.pkl \
+  --live live.parquet \
+  --benchmarks live_benchmark_models.parquet \
+  --output predictions.csv
+```
+
+The production system derives several slot-specific submissions by applying different feature and benchmark neutralization settings after this base ensemble. Those operational credentials and live submissions are intentionally excluded.
+
+## Reproducibility and safety
+
+`manifest.json` records the source revision, metric split, dependency versions, and hashes. Numerai datasets, target labels, live predictions, API credentials, and staking information are not included.
+
+The checkpoint uses Python pickle serialization because it contains native LightGBM and CatBoost estimators. Pickle can execute code while loading: verify the SHA-256 and load only artifacts you trust. Reconstructing the component estimators in native, non-pickle formats is planned for a later release.
+
+## Research context
+
+Three subsequent frozen-prediction experiments did not displace this champion:
+
+- extra tree families were highly redundant with the core (pairwise prediction correlations 0.81–0.94);
+- equal and shrinkage weighting lost to purged walk-forward coordinate ascent;
+- a raw-magnitude residual stack lost to the existing rank blend.
+
+Negative results are retained because they narrow the useful next step: seek genuinely different input signal—currently the official v5.3 feature families—rather than adding more tree implementations over the same v5.2 inputs.
+
+## License and use
+
+No explicit model or software license has been selected for this first release. Numerai data and benchmark-model files are governed by their own terms and are not redistributed here. Verify the applicable terms before reuse or redistribution.

inference.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Standalone, credential-free inference for the Numerai weekly v4 bundle."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+from typing import Any
+
+import joblib
+import numpy as np
+import pandas as pd
+from scipy.stats import norm, rankdata
+
+
+REQUIRED_COMPONENTS = (
+    "benchmark_era_boost",
+    "multi_target",
+    "residual",
+    "catboost",
+)
+
+
+def load_bundle(path: str | Path) -> dict[str, Any]:
+    """Load a trusted model bundle and validate its public inference contract."""
+    bundle = joblib.load(Path(path))
+    if not isinstance(bundle, dict):
+        raise TypeError("expected a dictionary model bundle")
+    missing = [name for name in REQUIRED_COMPONENTS if name not in bundle]
+    if missing:
+        raise ValueError(f"bundle is missing components: {', '.join(missing)}")
+    if "calibrated_weights" not in bundle or "config" not in bundle:
+        raise ValueError("bundle is missing calibrated_weights or config")
+    return bundle
+
+
+def _columns(bundle: dict[str, Any]) -> tuple[list[str], list[str], list[str]]:
+    config = bundle["config"]
+    features = config.get("features")
+    benchmark_columns = config.get("bench_cols")
+    all_columns = config.get("all_feature_cols")
+    if not all(isinstance(value, list) for value in (features, benchmark_columns, all_columns)):
+        raise ValueError("bundle config does not contain serialized feature-name lists")
+    return features, benchmark_columns, all_columns
+
+
+def _gaussianize(values: np.ndarray) -> np.ndarray:
+    ranked = rankdata(values, method="average") / (len(values) + 1)
+    return norm.ppf(ranked)
+
+
+def predict(frame: pd.DataFrame, bundle: dict[str, Any]) -> np.ndarray:
+    """Return the exact pre-neutralization Gaussian v4 ensemble prediction."""
+    features, _, all_columns = _columns(bundle)
+    missing = sorted(set(all_columns) - set(frame.columns))
+    if missing:
+        preview = ", ".join(missing[:8])
+        raise ValueError(f"input is missing {len(missing)} columns; first missing: {preview}")
+
+    n_rows = len(frame)
+    if n_rows < 2:
+        raise ValueError("at least two rows are required for cross-sectional ranking")
+
+    x_full = frame[all_columns].to_numpy()
+    x_features = frame[features].to_numpy()
+    components: dict[str, np.ndarray] = {}
+
+    models = bundle["benchmark_era_boost"]
+    components["benchmark_era_boost"] = np.mean(
+        [model.predict(x_full) for model in models], axis=0
+    )
+
+    target_predictions = [
+        rankdata(model.predict(x_full), method="average") / n_rows
+        for model in bundle["multi_target"].values()
+    ]
+    components["multi_target"] = np.mean(target_predictions, axis=0)
+
+    models = bundle["residual"]
+    components["residual"] = np.mean(
+        [model.predict(x_features) for model in models], axis=0
+    )
+
+    models = bundle["catboost"]
+    components["catboost"] = np.mean(
+        [model.predict(x_full) for model in models], axis=0
+    )
+
+    for optional_name in ("xgboost", "lgb_dart"):
+        models = bundle.get(optional_name)
+        if models:
+            components[optional_name] = np.mean(
+                [model.predict(x_full) for model in models], axis=0
+            )
+
+    horizon_models = bundle.get("horizon60")
+    if horizon_models:
+        components["horizon60"] = np.mean(
+            [
+                rankdata(model.predict(x_full), method="average") / n_rows
+                for model in horizon_models.values()
+            ],
+            axis=0,
+        )
+
+    weights = {
+        name: float(weight)
+        for name, weight in bundle["calibrated_weights"].items()
+        if name in components
+    }
+    total_weight = sum(weights.values())
+    if total_weight <= 0:
+        raise ValueError("bundle has no positively weighted active components")
+
+    ensemble = np.zeros(n_rows, dtype=np.float64)
+    for name, weight in weights.items():
+        component_rank = rankdata(components[name], method="average") / (n_rows + 1)
+        ensemble += (weight / total_weight) * component_rank
+    return _gaussianize(ensemble)
+
+
+def predict_ranked(frame: pd.DataFrame, bundle: dict[str, Any]) -> np.ndarray:
+    """Return submission-shaped predictions strictly between zero and one."""
+    gaussian_prediction = predict(frame, bundle)
+    return rankdata(gaussian_prediction, method="average") / (len(frame) + 1)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--model", type=Path, required=True)
+    parser.add_argument("--live", type=Path, required=True)
+    parser.add_argument("--benchmarks", type=Path, required=True)
+    parser.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args()
+
+    bundle = load_bundle(args.model)
+    live = pd.read_parquet(args.live)
+    benchmarks = pd.read_parquet(args.benchmarks)
+    benchmark_columns = [column for column in benchmarks.columns if column != "era"]
+    live = live.join(benchmarks[benchmark_columns], how="left")
+    predictions = predict_ranked(live, bundle)
+
+    output = pd.DataFrame({"prediction": predictions}, index=live.index)
+    output.index.name = "id"
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    output.to_csv(args.output)
+    print(f"wrote {len(output):,} predictions to {args.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

manifest.json

@@ -0,0 +1,53 @@
+{
+  "release": "v4-20260801-180455",
+  "published_date": "2026-08-14",
+  "verified_live_round": 1333,
+  "source": {
+    "repository": "https://github.com/Noptus/numerai-tournament",
+    "commit": "19fd7d8f6baea4af96f87d7295c83025fde53984",
+    "worktree_had_uncommitted_research_changes": true
+  },
+  "data": {
+    "version": "v5.2",
+    "included": false,
+    "feature_set": "medium",
+    "feature_count": 780,
+    "benchmark_model_column_count": 8
+  },
+  "validation": {
+    "calibration_eras": 120,
+    "purge_eras": 8,
+    "requested_holdout_eras": 60,
+    "scored_holdout_eras": 57,
+    "mean_corr": 0.010453262665121218,
+    "std_corr": 0.01355527777438434,
+    "sharpe": 0.771157561470213,
+    "consistency": 0.7543859649122807,
+    "max_drawdown_proxy": -0.013603461343878933
+  },
+  "inference_verification": {
+    "live_rows": 7016,
+    "production_function": "submit_v4.predict_v4",
+    "max_absolute_difference": 0.0,
+    "exact_array_equal": true,
+    "all_finite": true
+  },
+  "artifacts": {
+    "ensemble_v4.pkl": {
+      "sha256": "79db5f41f3506e8e10a8b96c60a927f6a9ca202e49e03304ceaa9d304116b8d9"
+    },
+    "promotion.json": {
+      "sha256": "fc158b8bbfc1ec33fdb556357c1b6a47db9423622beaac54aacd60649c573d16"
+    }
+  },
+  "runtime": {
+    "python": "3.11.15",
+    "numpy": "2.4.6",
+    "pandas": "3.0.3",
+    "scipy": "1.17.1",
+    "scikit_learn": "1.9.0",
+    "lightgbm": "4.6.0",
+    "catboost": "1.2.10",
+    "joblib": "1.5.3"
+  }
+}

requirements.txt

@@ -0,0 +1,9 @@
+huggingface-hub>=0.34,<2
+joblib==1.5.3
+numpy==2.4.6
+pandas==3.0.3
+scipy==1.17.1
+scikit-learn==1.9.0
+lightgbm==4.6.0
+catboost==1.2.10
+pyarrow>=14