Upload MODEL_CARD.md with huggingface_hub

MODEL_CARD.md

@@ -0,0 +1,63 @@
+Model: Romeo (V5)
+==================
+
+Short description
+-----------------
+Romeo (V5) is an ensemble trading model for XAUUSD that combines tree-based models (XGBoost / LightGBM) and an optional Keras neural network head. The ensemble outputs a probability score for an up / long trade; entry/exit logic and position sizing are handled by the backtester.
+
+Model artifacts
+---------------
+- `trading_model_romeo_daily.pkl` — joblib pickle containing tree models, model weights, and canonical `features` list.
+- `romeo_keras_daily.keras` — optional Keras model file (if included during training).
+
+Intended use
+------------
+- Research, backtesting, and evaluation on historical XAUUSD data.
+- Not financial advice. Use with caution and proper risk controls in production.
+
+Model structure and transparency
+--------------------------------
+- Ensemble components:
+  - XGBoost classifier(s) and/or LightGBM classifiers stored inside the `.pkl` artifact.
+  - Optional Keras neural network stored in `.keras` format. The code replaces anonymous Lambda layers with a serializable `SumAxis1Layer` to ensure portability.
+- Canonical feature list: stored under the artifact key `features`. Backtester aligns unseen data to that canonical list and fills missing features with zeros.
+
+Backtest and evaluation assumptions
+----------------------------------
+- Entry occurs on next bar open after a signal. Slippage is applied in pips and commission as a percent. TP/SL/timeouts are supported in the backtester.
+- Metrics are computed using per-bar mark-to-market (M2M) equity when requested. This is the preferred risk measure and is reported in the `backtest_results_romeo/` outputs.
+
+Recent evaluation (unseen daily data)
+-----------------------------------
+- initial_capital: 100
+- final_capital: 484.8199412897085
+- CAGR: 0.044435345346789834
+- Annual volatility: 0.4118163868756299
+- Sharpe: 0.31192432046397695
+- Max drawdown: -0.47656310794093215
+- Total trades: 3610
+- Win rate: 0.49473684210526314
+
+Robustness summary (coarse grid)
+--------------------------------
+See `backtest_results_romeo/romeo_robustness_summary.json` for the coarse grid scan. Best scenarios favored low friction (slippage and commission near zero) and a threshold around 0.5. Worst scenarios concentrated at higher commission (0.0005) and higher thresholds (0.6).
+
+How to use
+----------
+1. Load artifacts:
+   - Load `trading_model_romeo_daily.pkl` with `joblib.load()`; this returns a dict with keys like `models`, `weights`, `features`, and optionally `keras_path`.
+2. Align data:
+   - Prepare features matching the canonical `features` list. Any missing features can be filled with zeros.
+3. Make predictions:
+   - For tree ensemble use `model.predict_proba(X)`. For Keras models use `keras.models.load_model()` with the `SumAxis1Layer` custom object if needed.
+4. Backtest:
+   - Use `v5/backtest_v5.py` which accepts `--data <path>` and will align features automatically.
+
+Limitations and caveats
+-----------------------
+- Position sizing in the current backtester is simplified; small-account behavior may not reflect brokerage margin rules. Consider improving position-sizing (fixed risk per trade) before using live.
+- These results are from historical backtests and are not a guarantee of future performance.
+
+Contact
+-------
+For questions or to request model re-training or different artifact flavors, open an issue or contact the repository owner.