Upload README.md with huggingface_hub

README.md

@@ -12,254 +12,69 @@ library_name: pytorch
 
 # MAG7 TCN Sequence Model
 
-Public TCN sequence model trained on a private MAG7 daily ML dataset.
+Public Temporal Convolutional Network 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-tcn-a10g-large-v1",
-  "dataset_repo": "kyLELEng/mag7-ml-daily-dataset-5y",
-  "dataset_file": "mag7_ml_daily_dataset_5y.csv",
-  "model_repo": "kyLELEng/mag7-tcn-sequence-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": 4606,
-    "val": 1673,
-    "test": 1673
-  },
-  "feature_count": 187,
-  "lookback": 60,
-  "best_trial": {
-    "trial": 5,
-    "hidden_channels": 96,
-    "levels": 4,
-    "kernel_size": 3,
-    "dropout": 0.1381333485236117,
-    "lr": 0.00011813006897892851,
-    "weight_decay": 6.880481204463462e-05,
-    "best_score": 0.5440268185410438,
-    "epochs": 27,
-    "val_loss": 1.1796759750161852,
-    "val_auc": 0.5440268185410438,
-    "val_accuracy": 0.543335325762104,
-    "val_precision": 0.5676691729323309,
-    "val_recall": 0.5194954128440367
-  },
-  "test_metrics": {
-    "loss": 1.1004198278699602,
-    "auc": 0.5051273914485346,
-    "accuracy": 0.5086670651524208,
-    "precision": 0.5013192612137203,
-    "recall": 0.46116504854368934,
-    "top20pct_avg_future_return": 0.00976730976253748,
-    "bottom20pct_avg_future_return": 0.02428087405860424,
-    "top_minus_bottom_future_return": -0.014513564296066761
-  },
-  "all_trials": [
-    {
-      "trial": 0,
-      "hidden_channels": 64,
-      "levels": 4,
-      "kernel_size": 3,
-      "dropout": 0.18,
-      "lr": 0.0008,
-      "weight_decay": 0.0001,
-      "best_score": 0.5125545476411366,
-      "epochs": 15,
-      "val_loss": 0.8187018079417092,
-      "val_auc": 0.5125545476411366,
-      "val_accuracy": 0.5218170950388523,
-      "val_precision": 0.5596026490066225,
-      "val_recall": 0.3876146788990826
-    },
-    {
-      "trial": 1,
-      "hidden_channels": 128,
-      "levels": 4,
-      "kernel_size": 5,
-      "dropout": 0.2894351363662022,
-      "lr": 0.00015235342538756977,
-      "weight_decay": 7.952411684214868e-06,
-      "best_score": 0.5237847759108454,
-      "epochs": 19,
-      "val_loss": 0.9681848202432904,
-      "val_auc": 0.5237847759108454,
-      "val_accuracy": 0.5343693962940825,
-      "val_precision": 0.5566382460414129,
-      "val_recall": 0.5240825688073395
-    },
-    {
-      "trial": 2,
-      "hidden_channels": 128,
-      "levels": 3,
-      "kernel_size": 5,
-      "dropout": 0.08142163223270518,
-      "lr": 0.001570682160922224,
-      "weight_decay": 0.0002461547871651075,
-      "best_score": 0.5250647126871227,
-      "epochs": 19,
-      "val_loss": 1.1032832307474953,
-      "val_auc": 0.5250647126871227,
-      "val_accuracy": 0.5331739390316796,
-      "val_precision": 0.5486631016042781,
-      "val_recall": 0.588302752293578
-    },
-    {
-      "trial": 3,
-      "hidden_channels": 32,
-      "levels": 4,
-      "kernel_size": 5,
-      "dropout": 0.15517491526720878,
-      "lr": 0.0001711111456311903,
-      "weight_decay": 2.16385879826713e-05,
-      "best_score": 0.5232178240502124,
-      "epochs": 13,
-      "val_loss": 0.6918037618909564,
-      "val_auc": 0.5232178240502124,
-      "val_accuracy": 0.5062761506276151,
-      "val_precision": 0.53125,
-      "val_recall": 0.44839449541284404
-    },
-    {
-      "trial": 4,
-      "hidden_channels": 48,
-      "levels": 4,
-      "kernel_size": 3,
-      "dropout": 0.22944428506011294,
-      "lr": 0.0031070660232048945,
-      "weight_decay": 0.00023877329777338924,
-      "best_score": 0.5051548236722445,
-      "epochs": 18,
-      "val_loss": 1.028452375105449,
-      "val_auc": 0.5051548236722445,
-      "val_accuracy": 0.5212193664076509,
-      "val_precision": 0.5361875637104995,
-      "val_recall": 0.6032110091743119
-    },
-    {
-      "trial": 5,
-      "hidden_channels": 96,
-      "levels": 4,
-      "kernel_size": 3,
-      "dropout": 0.1381333485236117,
-      "lr": 0.00011813006897892851,
-      "weight_decay": 6.880481204463462e-05,
-      "best_score": 0.5440268185410438,
-      "epochs": 27,
-      "val_loss": 1.1796759750161852,
-      "val_auc": 0.5440268185410438,
-      "val_accuracy": 0.543335325762104,
-      "val_precision": 0.5676691729323309,
-      "val_recall": 0.5194954128440367
-    },
-    {
-      "trial": 6,
-      "hidden_channels": 128,
-      "levels": 3,
-      "kernel_size": 2,
-      "dropout": 0.08963367526887096,
-      "lr": 0.00047349019976111593,
-      "weight_decay": 2.503906317853087e-05,
-      "best_score": 0.5291278676883253,
-      "epochs": 31,
-      "val_loss": 1.7204655834606715,
-      "val_auc": 0.5291278676883253,
-      "val_accuracy": 0.5242080095636581,
-      "val_precision": 0.55,
-      "val_recall": 0.4793577981651376
-    },
-    {
-      "trial": 7,
-      "hidden_channels": 128,
-      "levels": 5,
-      "kernel_size": 5,
-      "dropout": 0.21881176458186874,
-      "lr": 0.0004412501237233734,
-      "weight_decay": 5.527703833149022e-06,
-      "best_score": 0.5276761273179168,
-      "epochs": 16,
-      "val_loss": 0.8110667296818325,
-      "val_auc": 0.5276761273179168,
-      "val_accuracy": 0.5098625224148237,
-      "val_precision": 0.521630615640599,
-      "val_recall": 0.7190366972477065
-    },
-    {
-      "trial": 8,
-      "hidden_channels": 96,
-      "levels": 5,
-      "kernel_size": 2,
-      "dropout": 0.13194857887603387,
-      "lr": 0.0009472281705883164,
-      "weight_decay": 3.997791791749733e-06,
-      "best_score": 0.5203902232301367,
-      "epochs": 17,
-      "val_loss": 1.0085366197994776,
-      "val_auc": 0.5203902232301367,
-      "val_accuracy": 0.5146443514644351,
-      "val_precision": 0.5251677852348994,
-      "val_recall": 0.7178899082568807
-    },
-    {
-      "trial": 9,
-      "hidden_channels": 96,
-      "levels": 4,
-      "kernel_size": 3,
-      "dropout": 0.30411288704647127,
-      "lr": 0.0001155004929570295,
-      "weight_decay": 6.350353678482887e-06,
-      "best_score": 0.5126612090391598,
-      "epochs": 13,
-      "val_loss": 0.6987957826682499,
-      "val_auc": 0.5126612090391598,
-      "val_accuracy": 0.4955170352659892,
-      "val_precision": 0.5180878552971576,
-      "val_recall": 0.4598623853211009
-    },
-    {
-      "trial": 10,
-      "hidden_channels": 32,
-      "levels": 5,
-      "kernel_size": 5,
-      "dropout": 0.21764351866447423,
-      "lr": 0.0017384228382429352,
-      "weight_decay": 8.301403060986722e-05,
-      "best_score": 0.5219650895096725,
-      "epochs": 17,
-      "val_loss": 0.8541087976523808,
-      "val_auc": 0.5219650895096725,
-      "val_accuracy": 0.5194261805140467,
-      "val_precision": 0.5374449339207048,
-      "val_recall": 0.5596330275229358
-    },
-    {
-      "trial": 11,
-      "hidden_channels": 32,
-      "levels": 5,
-      "kernel_size": 3,
-      "dropout": 0.22610883177165192,
-      "lr": 0.00046048215182379454,
-      "weight_decay": 0.00041116688533911693,
-      "best_score": 0.5061920878718117,
-      "epochs": 13,
-      "val_loss": 0.692179513829095,
-      "val_auc": 0.5061920878718117,
-      "val_accuracy": 0.5146443514644351,
-      "val_precision": 0.5903614457831325,
-      "val_recall": 0.22477064220183487
-    }
-  ]
-}
-```
+- 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: TCN sequence model
+- Lookback window: 60 daily bars
+- Feature count: 187 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.5440 |
+| Test AUC | 0.5051 |
+| Test accuracy | 0.5087 |
+| Test precision | 0.5013 |
+| Test recall | 0.4612 |
+| Top 20 pct avg future return | 0.0098 |
+| Bottom 20 pct avg future return | 0.0243 |
+| Top minus bottom future return | -0.0145 |
+
+The holdout edge is weak. Treat this as a research artifact, not as a production trading signal.
+
+## Best Trial
+
+- Hidden channels: 96
+- Levels: 4
+- Kernel size: 3
+- Dropout: 0.1381
+- Learning rate: 0.000118
+- Weight decay: 0.0000688
+- Epochs: 27
+
+## Files
+
+- `model.pt`
+- `scaler.joblib`
+- `feature_columns.json`
+- `metrics.json`
+- `training_log.csv`
+- `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.