pybroker-model-trainer

name

pybroker-model-trainer

description

Register, train, wire, and debug machine learning models for PyBroker backtests using the bundled PyBroker wiki references generated from the local docs. Use when an agent needs to register a model with pybroker.model, write train_fn/predict_fn code for scikit-learn, XGBoost, LightGBM, CatBoost, PyTorch, Keras, statsmodels (ARIMA/SARIMAX), or arch models, build ensembles or regime models, run walkforward analysis, build time-series or lagged-feature models, train pooled multi-symbol models, load pretrained models, cache data and trained models, or prevent lookahead leakage in model-driven backtests.

PyBroker Model Trainer

Overview

Wire machine learning models into PyBroker backtests by registering training and prediction functions with pybroker.model, feeding them indicator features, and evaluating them with walkforward analysis while keeping the train/test flow free of lookahead leakage. Covers per-symbol, pooled multi-symbol, per-bar time-series, lagged-feature, and pretrained models across common libraries such as scikit-learn, XGBoost, and arch.

Workflow

1. Extract the modeling spec: library, prediction target and horizon, features (indicators, lagged columns, custom columns), per-symbol vs pooled training, vectorized vs per-bar prediction, walkforward windows and lookahead, caching, and whether the model is trainable or pretrained.
2. Ask only for missing blockers. If details are absent but noncritical, make conservative assumptions and state them in the final answer or code comments.
3. Read references/wiki-index.md to choose the smallest relevant wiki page. For nontrivial model work, also read references/model-training-patterns.md.
4. Build a complete runnable model surface:
   • define feature indicators with pybroker.indicator or built-ins, and register any non-OHLCV data columns with pybroker.register_columns
   • write a train_fn that builds the target from train data only and returns the model, or (model, input_cols) to pin prediction columns
   • register the model with pybroker.model(name, train_fn, ...), choosing indicators, lags/lag_cols, per_bar, pooled, pretrained, input_data_fn, and predict_fn as needed
   • consume predictions in an execution function via ctx.preds(name) and pass the model source to Strategy.add_execution(models=...)
   • run strategy.walkforward(windows, train_size, lookahead) for evaluation, or backtest(train_size=...) for a single train/test pass
5. Validate the produced code as far as the environment allows. At minimum, run syntax checks for created Python files. Run a small local-data walkforward when the repo and data make that practical.

Implementation Rules

• Treat PyBroker as a backtesting framework, not a source of financial advice. Make modeling assumptions explicit and avoid performance claims that are not supported by the produced backtest, including model fit metrics.
• Use completed historical bar data only. Do not use future prices, future indicator values, or shuffled time series outside the supported train-split shuffle. An indicator value at bar i may depend only on inputs at index i and earlier: no backward shifts such as shift(-1) outside the sanctioned train_fn target, and no negative indexing into full-length arrays inside indicator functions (a negative index silently wraps to the end of the series — the future).
• Set lookahead to the number of bars ahead of the prediction target (default 1 for next-bar targets). Walkforward holds out lookahead bars between each train and test split, so an understated value leaks train-adjacent bars into testing.
• When registering with lags, the current bar's value is the first feature of each lag block, so the training target must be the next bar's value (for example fit(lag_train[:-1], target[1:])). The training fn must accept lag_train and lag_test keyword arguments.
• Keep feature data out-of-band: never widen or mutate the input DataFrame. Work on a .copy() inside train_fn when adding a target column.
• An input_data_fn must return exactly one row per bar. A vectorized predict_fn must return one prediction per input row; for classifiers, slice a single predict_proba column. With per_bar=True, predict_fn is required, receives rows up to and including the current bar, must return a scalar, and cannot be combined with pooled=True.
• A pooled train_fn receives a sorted symbols tuple and combined frames with a symbol column. Build targets with per-symbol operations such as groupby("symbol")[col].shift(-1) so labels never cross a symbol boundary, and return (model, input_cols) to keep symbol out of model input.
• To train a model on a longer time interval, bind it with model_source.intervals("weekly") when passing it to add_execution(models=...); binding is exhaustive, so the base-timeframe model is trained only when is included (e.g. ), and the bound interval is available through without declaring it in (which provides bars only). For interval-bound models, is measured in that interval's compressed bars, and predictions are read with . is then required on /.

Common Deliverables

• Standalone .py walkforward backtest script with a trained model.
• train_fn/predict_fn pairs for a user's chosen library.
• Conversion of an existing single-symbol model to pooled multi-symbol training.
• Debugging notes and patches for leaking targets, misaligned predictions, or invalid pybroker.model registrations.
• Notebook-ready PyBroker model training cells.

Resources

• references/wiki-index.md: start here for topic routing across the bundled references.
• references/wiki-06-training-a-model.md: model registration, train/backtest flow, model caching, and walkforward analysis.
• references/wiki-16-time-series-models.md: GARCH with per_bar=True and Random Forest on lagged returns with lags/lag_cols.
• references/wiki-17-multi-symbol-models.md: pooled multi-symbol training with pooled=True.
• references/model-training-patterns.md: load when writing nontrivial train/predict code; library recipes, session hygiene, and the leakage checklist.
• references/api-public-surface.md: generated public API signatures and first docstring sentences from local source.
• references/pybroker_model.pyi: generated type stubs for model(), indicator(), vector helpers, data sources, and top-level module functions.
• references/pybroker_context.pyi: generated type stubs for ExecContext (including its writable order/stop attributes), IntervalContext, RotationContext, ExecResult, and the slippage models.
• references/pybroker_strategy.pyi: generated type stubs for Strategy, StrategyConfig, TestResult, and the optimization types.
• references/pybroker_types.pyi: generated type stubs for enums, BarData, Portfolio, order/trade/position records, and evaluation result types.
• assets/model_training_template.py: copy and adapt when creating a new standalone model training script.