44[ ![ PyPI] ( https://img.shields.io/pypi/v/ml4t-models )] ( https://pypi.org/project/ml4t-models/ )
55[ ![ License: MIT] ( https://img.shields.io/badge/License-MIT-yellow.svg )] ( https://opensource.org/licenses/MIT )
66
7- Finance-native model implementations for latent-factor estimation, stochastic discount factor learning, direct asset prediction, and end-to-end portfolio learning.
7+ Finance-specific models for asset pricing, prediction, and portfolio learning.
88
99Documentation: [ ml4trading.io/docs/models] ( https://www.ml4trading.io/docs/models/ )
1010
@@ -45,7 +45,8 @@ It also keeps the predictive steps explicit:
4545- asset mapping
4646- downstream prediction and weight frames for ` ml4t-backtest ` and ` ml4t-diagnostic `
4747
48- ![ ml4t-models Architecture] ( docs/images/ml4t_models_architecture.svg )
48+ The [ architecture guide] ( https://www.ml4trading.io/docs/models/reference/architecture/ )
49+ connects these data contracts, model outputs, and downstream handoffs.
4950
5051## Installation
5152
@@ -61,104 +62,52 @@ pip install ml4t-models[integration] # polars + ml4t-specs bridges
6162pip install ml4t-models[all] # all runtime capabilities
6263```
6364
64- Supported stable interpreters are Python 3.12, 3.13, and 3.14. Python 3.15 prereleases run a
65- separate compatibility gate and are not yet part of the stable support range.
65+ Supported interpreters for all model families are Python 3.12, 3.13, and 3.14.
66+ Python 3.15 is stable, but this package currently qualifies only its NumPy-based core
67+ workflows. The ` deep ` extra enables Torch only below Python 3.15; use Python 3.12-3.14
68+ for neural models.
6669
6770Documentation tools are contributor dependencies. From a source checkout, run
6871` uv sync --extra docs ` before building the site.
6972
7073## Quick Start
7174
72- ### 1. Latent-Factor Forecast Pipeline
75+ The base package can produce a first forecast on a small synthetic panel without credentials or
76+ an accelerator. Run this complete example with ` pip install ml4t-models ` :
7377
7478``` python
7579import numpy as np
76-
7780from ml4t.models import (
7881 BetaLambdaMapper,
79- CrossSectionBatch,
8082 ExpandingMeanFactorForecaster,
81- IPCAConfig,
82- IPCAModel,
8383 LatentFactorForecastPipeline,
84+ PCAConfig,
85+ PCAModel,
86+ PersistentPanelBatch,
8487)
8588
86- batch = CrossSectionBatch(
87- characteristics = np.random.randn(24 , 200 , 12 ),
88- returns = np.random.randn(24 , 200 ),
89- timestamps = tuple (range (24 )),
89+ asset_ids = tuple (f " asset_ { i} " for i in range (6 ))
90+ train = PersistentPanelBatch(
91+ returns = np.random.default_rng(1 ).normal(scale = 0.02 , size = (12 , 6 )),
92+ timestamps = tuple (f " 2024- { month:02d } " for month in range (1 , 13 )),
93+ asset_ids = asset_ids,
9094)
91-
95+ future = PersistentPanelBatch( timestamps = ( " 2025-01 " , " 2025-02 " ), asset_ids = asset_ids)
9296pipeline = LatentFactorForecastPipeline(
93- model = IPCAModel(IPCAConfig (n_factors = 3 )),
97+ model = PCAModel(PCAConfig (n_factors = 2 )),
9498 forecaster = ExpandingMeanFactorForecaster(),
9599 mapper = BetaLambdaMapper(),
96100)
97- pipeline.fit(batch)
98- prediction = pipeline.predict(batch)
99-
100- print (prediction.asset_forecast.expected_returns.shape)
101- # (24, 200)
102- ```
103-
104- ### 2. Weight-Native Stochastic Discount Factor
105-
106- ``` python
107- import numpy as np
108-
109- from ml4t.models import (
110- CrossSectionBatch,
111- StochasticDiscountFactorConfig,
112- StochasticDiscountFactorModel,
113- )
114-
115- batch = CrossSectionBatch(
116- characteristics = np.random.randn(36 , 300 , 16 ),
117- returns = np.random.randn(36 , 300 ),
118- context_features = np.random.randn(36 , 8 ),
119- timestamps = tuple (range (36 )),
120- )
121-
122- model = StochasticDiscountFactorModel(
123- StochasticDiscountFactorConfig(checkpoint_epochs = (256 , 512 , 768 , 1024 ))
124- )
125- model.fit(batch)
126- state = model.extract(batch, checkpoint = 1280 )
127-
128- print (state.asset_weights.shape)
129- # (36, 300)
101+ pipeline.fit(train)
102+ forecast = pipeline.predict(future).asset_forecast.expected_returns
103+ assert forecast.shape == (2 , 6 ) and np.isfinite(forecast).all()
104+ print (forecast.shape) # (2, 6)
130105```
131106
132- ### 3. End-to-End Portfolio Learning
133-
134- ``` python
135- import numpy as np
136-
137- from ml4t.models import LSTMPortfolioConfig, LSTMPortfolioModel, PortfolioSequenceBatch
138-
139- batch = PortfolioSequenceBatch(
140- features = np.random.randn(8 , 63 , 20 , 10 ),
141- returns = np.random.randn(8 , 63 , 20 ),
142- timestamps = tuple (range (63 )),
143- asset_ids = tuple (f " asset_ { i} " for i in range (20 )),
144- )
145-
146- model = LSTMPortfolioModel(LSTMPortfolioConfig(max_iters = 20 , checkpoint_every = 5 ))
147- model.fit(batch)
148- weights = model.predict(batch, checkpoint = 20 )
149-
150- print (weights.weights.shape)
151- # (8, 63, 20)
152- ```
153-
154- ### 4. Hand Off Predictions To The Rest Of ML4T
155-
156- ``` python
157- from ml4t.models import predictions_frame_from_asset_forecast, write_backtest_frames
158-
159- frame = predictions_frame_from_asset_forecast(prediction.asset_forecast)
160- write_backtest_frames(" artifacts/run_001" , predictions = frame)
161- ```
107+ The forecast uses the training factor history and preserves the future dates and asset order.
108+ It does not imply trading performance. The [ Quickstart] ( docs/getting-started/quickstart.md )
109+ explains the result, and the [ Book Guide] ( docs/book-guide/index.md ) links to pinned teaching files.
110+ The ` deep ` extra is needed for neural models; the ` integration ` extra adds Polars and Specs support.
162111
163112## Model Families
164113
0 commit comments