Add live-forward paper trading workflow

Author: HanSun103

README.md

@@ -47,21 +47,22 @@ The right claim is therefore:
 ### Development Performance
 
 ```mermaid
-xychart-beta
-    title "Net CAGR, repaired development window"
-    x-axis ["SPY", "Smart + Rank40", "Full Rank40"]
-    y-axis "Net CAGR (%)" 0 --> 40
-    bar [13.84, 27.15, 37.22]
+flowchart LR
+    SPY["SPY<br/>13.84% CAGR"]
+    SMART["Smart + Rank40<br/>27.15% CAGR"]
+    FULL["Full Rank40<br/>37.22% CAGR"]
+    SPY --> SMART --> FULL
 ```
 
 ### Model Signal Quality
 
 ```mermaid
-xychart-beta
-    title "Rank signal by year: top-40 excess weekly return"
-    x-axis ["2020", "2021", "2022", "2023 H1"]
-    y-axis "Excess weekly return (%)" -0.10 --> 0.60
-    bar [0.5215, -0.0375, -0.0411, 0.2941]
+flowchart LR
+    Y2020["2020<br/>+0.5215% weekly excess"]
+    Y2021["2021<br/>-0.0375%"]
+    Y2022["2022<br/>-0.0411%"]
+    Y2023["2023 H1<br/>+0.2941%"]
+    Y2020 --> Y2021 --> Y2022 --> Y2023
 ```
 
 The portfolio result is strong, but the signal chart explains why the documentation stays
@@ -195,6 +196,21 @@ python -m src.cli evaluate-rank-model \
   --top-k 40
 ```
 
+Create a frozen live-forward paper snapshot from the latest yfinance close:
+
+```bash
+python -m src.cli run-live-forward-snapshot --as-of 2026-07-17
+```
+
+By default this rebuilds a rolling daily-proxy training panel from recent yfinance prices, trains
+candidate Ridge and XGBoost rankers on all known one-session forward residual-rank labels, selects
+the winner on a trailing temporal validation window, refits the selected model, scores the active
+membership list using the latest close, and saves a local paper portfolio plus
+`model_selection.csv` under `reports/live_forward/YYYY-MM-DD/`. Do not edit a saved snapshot
+before measuring realized next-session returns; otherwise the forward test stops being clean. This
+daily proxy is designed to collect evidence faster than waiting ten calendar weeks for ten weekly
+rebalance observations.
+
 Build the earlier conservative final-reference package:
 
 ```bash

src/cli.py

@@ -820,6 +820,120 @@ def run_exit_prediction_v8_command(
     click.echo(json.dumps(summary, indent=2))
 
 
+@main.command("run-live-forward-snapshot")
+@click.option(
+    "--base-config",
+    default="configs/base.yaml",
+    show_default=True,
+    type=click.Path(exists=True),
+)
+@click.option(
+    "--data-config",
+    default="configs/data.yaml",
+    show_default=True,
+    type=click.Path(exists=True),
+)
+@click.option(
+    "--experiment-config",
+    default="configs/experiments/sparse_rank_v3_fnspid_2018_2023.yaml",
+    show_default=True,
+    type=click.Path(exists=True),
+)
+@click.option(
+    "--training-dataset",
+    default="data/processed/residual_rank_v2_repaired/features.parquet",
+    show_default=True,
+    type=click.Path(exists=True),
+)
+@click.option(
+    "--membership-file",
+    default="data/raw/sp500_ticker_start_end_source.csv",
+    show_default=True,
+    type=click.Path(exists=True),
+)
+@click.option(
+    "--sector-file",
+    default="data/processed/residual_rank_v2_repaired/inferred_sector_history.csv",
+    show_default=True,
+    type=click.Path(exists=True),
+)
+@click.option("--output-root", default="reports/live_forward", show_default=True)
+@click.option("--as-of", default=None, help="Decision date, defaults to today.")
+@click.option("--holdings", default=40, show_default=True, type=int)
+@click.option(
+    "--label-horizon-sessions",
+    default=1,
+    show_default=True,
+    type=int,
+    help="Forward sessions for the live proxy label; 1 collects evidence fastest.",
+)
+@click.option("--recent-training-start", default="2024-01-01", show_default=True)
+@click.option(
+    "--use-static-training-dataset",
+    is_flag=True,
+    help="Use the old repaired weekly parquet instead of rebuilding recent daily proxy labels.",
+)
+@click.option(
+    "--skip-hyperparameter-tuning",
+    is_flag=True,
+    help="Train fixed config parameters only; intended for debugging, not evidence runs.",
+)
+@click.option("--validation-days", default=42, show_default=True, type=int)
+@click.option("--selection-metric", default="top40_raw_excess", show_default=True)
+def run_live_forward_snapshot_command(
+    base_config: str,
+    data_config: str,
+    experiment_config: str,
+    training_dataset: str,
+    membership_file: str,
+    sector_file: str,
+    output_root: str,
+    as_of: str | None,
+    holdings: int,
+    label_horizon_sessions: int,
+    recent_training_start: str,
+    use_static_training_dataset: bool,
+    skip_hyperparameter_tuning: bool,
+    validation_days: int,
+    selection_metric: str,
+) -> None:
+    """Create a frozen paper-trading snapshot from latest yfinance data."""
+    import json
+
+    from .experiments.live_forward_test import run_live_forward_snapshot
+
+    cfg = load_config(base_config, data_config)
+    result = run_live_forward_snapshot(
+        cfg,
+        experiment_config,
+        training_dataset=training_dataset,
+        membership_file=membership_file,
+        sector_file=sector_file,
+        output_root=output_root,
+        as_of=as_of,
+        holdings=holdings,
+        label_horizon_sessions=label_horizon_sessions,
+        recent_training_start=recent_training_start,
+        use_static_training_dataset=use_static_training_dataset,
+        tune_hyperparameters=not skip_hyperparameter_tuning,
+        validation_days=validation_days,
+        selection_metric=selection_metric,
+    )
+    click.echo(json.dumps({
+        "decision_date": result["decision_date"],
+        "latest_price_date": result["latest_price_date"],
+        "training_mode": result["training_mode"],
+        "training_end": result["training_end"],
+        "label_horizon_sessions": result["label_horizon_sessions"],
+        "model": result["model"],
+        "model_params": result["model_params"],
+        "model_selection": result["model_selection"],
+        "live_scored_names": result["live_scored_names"],
+        "holdings": result["holdings"],
+        "output": result["output"],
+    }, indent=2))
+
+
 @main.command("run-sparse-sentiment-ablation")
 @click.option(
     "--v2-base-config", default="configs/experiments/residual_rank_v2.yaml",