Upload README.md with huggingface_hub

README.md

@@ -14,279 +14,63 @@ library_name: pytorch
 
 Public optimized TabNet classifier trained on a private MAG7 daily ML dataset.
 
-The dataset remains private and is not distributed in this repo.
+## Data Access
 
-## Metrics
+The model is public. The dataset remains private and is not distributed in this repository.
 
-```json
-{
-  "app_version": "mag7-tabnet-a10g-large-v1",
-  "dataset_repo": "kyLELEng/mag7-ml-daily-dataset-5y",
-  "dataset_file": "mag7_ml_daily_dataset_5y.csv",
-  "model_repo": "kyLELEng/mag7-tabnet-model",
-  "target_col": "target_next_10d_outperform_qqq",
-  "hardware_requested": "a10g-large",
-  "device": "cuda",
-  "split_info": {
-    "train_end": "2024-03-06",
-    "validation_end": "2025-02-19",
-    "test_start": "2025-02-20"
-  },
-  "sample_counts": {
-    "train": 5019,
-    "val": 1673,
-    "test": 1673
-  },
-  "feature_count": 247,
-  "best_trial": {
-    "trial": 6,
-    "n_d": 32,
-    "n_a": 32,
-    "n_steps": 5,
-    "gamma": 1.3472923985423138,
-    "lambda_sparse": 5.9536858055136465e-05,
-    "lr": 0.00025119563811957976,
-    "mask_type": "entmax",
-    "auc": 0.5403767080140649,
-    "accuracy": 0.5092647937836222,
-    "precision": 0.624390243902439,
-    "recall": 0.14678899082568808,
-    "best_epoch": 2,
-    "best_cost": 0.5403767080140649
-  },
-  "test_metrics": {
-    "auc": 0.503700813063913,
-    "accuracy": 0.5008965929468021,
-    "precision": 0.48014440433212996,
-    "recall": 0.16140776699029127
-  },
-  "all_trials": [
-    {
-      "trial": 0,
-      "n_d": 32,
-      "n_a": 32,
-      "n_steps": 4,
-      "gamma": 1.4,
-      "lambda_sparse": 0.0001,
-      "lr": 0.002,
-      "mask_type": "entmax",
-      "auc": 0.5317779381277989,
-      "accuracy": 0.5349671249252839,
-      "precision": 0.54510556621881,
-      "recall": 0.6513761467889908,
-      "best_epoch": 10,
-      "best_cost": 0.5317779381277989
-    },
-    {
-      "trial": 1,
-      "n_d": 16,
-      "n_a": 16,
-      "n_steps": 3,
-      "gamma": 1.4494945037080806,
-      "lambda_sparse": 6.375218482218559e-05,
-      "lr": 0.00011188485779759972,
-      "mask_type": "entmax",
-      "auc": 0.5107234076670217,
-      "accuracy": 0.5265989240884639,
-      "precision": 0.5384615384615384,
-      "recall": 0.6422018348623854,
-      "best_epoch": 2,
-      "best_cost": 0.5107234076670217
-    },
-    {
-      "trial": 2,
-      "n_d": 16,
-      "n_a": 16,
-      "n_steps": 4,
-      "gamma": 1.149294403307938,
-      "lambda_sparse": 2.450878873326482e-06,
-      "lr": 0.004094099286627188,
-      "mask_type": "sparsemax",
-      "auc": 0.500190415650162,
-      "accuracy": 0.49731022115959356,
-      "precision": 0.5166130760986066,
-      "recall": 0.5527522935779816,
-      "best_epoch": 7,
-      "best_cost": 0.500190415650162
-    },
-    {
-      "trial": 3,
-      "n_d": 64,
-      "n_a": 64,
-      "n_steps": 4,
-      "gamma": 1.3582951866108537,
-      "lambda_sparse": 3.421133844935391e-05,
-      "lr": 0.0013391616977365564,
-      "mask_type": "sparsemax",
-      "auc": 0.5071226906733556,
-      "accuracy": 0.5200239091452481,
-      "precision": 0.5306122448979592,
-      "recall": 0.6857798165137615,
-      "best_epoch": 20,
-      "best_cost": 0.5071226906733556
-    },
-    {
-      "trial": 4,
-      "n_d": 24,
-      "n_a": 24,
-      "n_steps": 5,
-      "gamma": 1.6516277161527944,
-      "lambda_sparse": 0.00010258450148297295,
-      "lr": 0.0007431045712850257,
-      "mask_type": "entmax",
-      "auc": 0.5032370660527551,
-      "accuracy": 0.5122534369396294,
-      "precision": 0.5347394540942928,
-      "recall": 0.49426605504587157,
-      "best_epoch": 1,
-      "best_cost": 0.5032370660527551
-    },
-    {
-      "trial": 5,
-      "n_d": 64,
-      "n_a": 64,
-      "n_steps": 5,
-      "gamma": 1.4843526882090186,
-      "lambda_sparse": 0.0008764777947850791,
-      "lr": 0.00022267224321802473,
-      "mask_type": "entmax",
-      "auc": 0.530329061150626,
-      "accuracy": 0.4931261207411835,
-      "precision": 0.5214285714285715,
-      "recall": 0.3348623853211009,
-      "best_epoch": 1,
-      "best_cost": 0.530329061150626
-    },
-    {
-      "trial": 6,
-      "n_d": 32,
-      "n_a": 32,
-      "n_steps": 5,
-      "gamma": 1.3472923985423138,
-      "lambda_sparse": 5.9536858055136465e-05,
-      "lr": 0.00025119563811957976,
-      "mask_type": "entmax",
-      "auc": 0.5403767080140649,
-      "accuracy": 0.5092647937836222,
-      "precision": 0.624390243902439,
-      "recall": 0.14678899082568808,
-      "best_epoch": 2,
-      "best_cost": 0.5403767080140649
-    },
-    {
-      "trial": 7,
-      "n_d": 32,
-      "n_a": 32,
-      "n_steps": 5,
-      "gamma": 1.7071334862896903,
-      "lambda_sparse": 2.433767087272514e-06,
-      "lr": 0.0006223353226297901,
-      "mask_type": "sparsemax",
-      "auc": 0.5347272331603844,
-      "accuracy": 0.511655708308428,
-      "precision": 0.5429017160686428,
-      "recall": 0.39908256880733944,
-      "best_epoch": 3,
-      "best_cost": 0.5347272331603844
-    },
-    {
-      "trial": 8,
-      "n_d": 24,
-      "n_a": 24,
-      "n_steps": 3,
-      "gamma": 1.7271610157752573,
-      "lambda_sparse": 1.9491536528703556e-05,
-      "lr": 0.00017826874616773067,
-      "mask_type": "entmax",
-      "auc": 0.5325689505091113,
-      "accuracy": 0.5289898386132695,
-      "precision": 0.541095890410959,
-      "recall": 0.6341743119266054,
-      "best_epoch": 7,
-      "best_cost": 0.5325689505091113
-    },
-    {
-      "trial": 9,
-      "n_d": 64,
-      "n_a": 64,
-      "n_steps": 5,
-      "gamma": 1.2415512194516267,
-      "lambda_sparse": 0.0005061663106438996,
-      "lr": 0.00023396561610545004,
-      "mask_type": "sparsemax",
-      "auc": 0.5177659233297828,
-      "accuracy": 0.5014943215780036,
-      "precision": 0.5372549019607843,
-      "recall": 0.31422018348623854,
-      "best_epoch": 2,
-      "best_cost": 0.5177659233297828
-    },
-    {
-      "trial": 10,
-      "n_d": 16,
-      "n_a": 16,
-      "n_steps": 3,
-      "gamma": 1.3420235116289478,
-      "lambda_sparse": 2.5510824218092704e-05,
-      "lr": 0.0034707903086838303,
-      "mask_type": "entmax",
-      "auc": 0.5203859281402834,
-      "accuracy": 0.4793783622235505,
-      "precision": 0.5068493150684932,
-      "recall": 0.04243119266055046,
-      "best_epoch": 2,
-      "best_cost": 0.5203859281402834
-    },
-    {
-      "trial": 11,
-      "n_d": 48,
-      "n_a": 48,
-      "n_steps": 5,
-      "gamma": 1.3375244625197118,
-      "lambda_sparse": 1.1236515243495598e-06,
-      "lr": 0.0001869391570285696,
-      "mask_type": "entmax",
-      "auc": 0.5245679139607601,
-      "accuracy": 0.5062761506276151,
-      "precision": 0.5515695067264574,
-      "recall": 0.28211009174311924,
-      "best_epoch": 12,
-      "best_cost": 0.5245679139607601
-    },
-    {
-      "trial": 12,
-      "n_d": 64,
-      "n_a": 64,
-      "n_steps": 3,
-      "gamma": 1.5837279414231316,
-      "lambda_sparse": 1.4588283152733528e-06,
-      "lr": 0.0001142576991362432,
-      "mask_type": "entmax",
-      "auc": 0.5068657011304677,
-      "accuracy": 0.5176329946204423,
-      "precision": 0.5301764159702879,
-      "recall": 0.6548165137614679,
-      "best_epoch": 6,
-      "best_cost": 0.5068657011304677
-    },
-    {
-      "trial": 13,
-      "n_d": 16,
-      "n_a": 16,
-      "n_steps": 5,
-      "gamma": 1.5115173584668025,
-      "lambda_sparse": 8.435857396344958e-06,
-      "lr": 0.0003463700123384165,
-      "mask_type": "entmax",
-      "auc": 0.5253324399546438,
-      "accuracy": 0.5182307232516438,
-      "precision": 0.5355603448275862,
-      "recall": 0.569954128440367,
-      "best_epoch": 6,
-      "best_cost": 0.5253324399546438
-    }
-  ]
-}
-```
+- Private training dataset: `kyLELEng/mag7-ml-daily-dataset-5y`
+- Dataset file used internally: `mag7_ml_daily_dataset_5y.csv`
+- No raw dataset rows, target labels, or future-return columns are included here.
 
-Research only. Not investment advice.
+## Training Setup
+
+- Task: binary classification
+- Target: `target_next_10d_outperform_qqq`
+- Architecture: TabNet classifier
+- Feature count: 247 selected numeric features plus ticker dummies
+- Split: chronological train / validation / test
+- Train end: 2024-03-06
+- Validation end: 2025-02-19
+- Test start: 2025-02-20
+- Hardware: Hugging Face Jobs, `a10g-large`
+- Device used: CUDA
+
+## Results
+
+Validation was used for hyperparameter selection. Test metrics are out-of-sample on the final chronological holdout.
+
+| Metric | Value |
+|---|---:|
+| Best validation AUC | 0.5404 |
+| Test AUC | 0.5037 |
+| Test accuracy | 0.5009 |
+| Test precision | 0.4801 |
+| Test recall | 0.1614 |
+
+The holdout edge is weak. Treat this as a research artifact, not as a production trading signal.
+
+## Best Trial
+
+- `n_d`: 32
+- `n_a`: 32
+- `n_steps`: 5
+- `gamma`: 1.3473
+- `lambda_sparse`: 0.0000595
+- Learning rate: 0.000251
+- Mask type: `entmax`
+- Best epoch: 2
+
+## Files
+
+- `tabnet_model.zip`
+- `scaler.joblib`
+- `feature_columns.json`
+- `metrics.json`
+- `trial_results.csv`
+- `test_scores_public.csv`
+
+`test_scores_public.csv` contains dates, tickers, and model scores only. It intentionally excludes labels and future returns.
+
+## Intended Use
+
+This model is for personal research and model comparison on MAG7 daily technical features. It is not investment advice and should not be used for live trading without separate validation, walk-forward testing, slippage assumptions, and risk controls.