stock-embeddings 0.1.0__tar.gz

stock_embeddings-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tomasz Rymaszeski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stock_embeddings-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: stock-embeddings
+Version: 0.1.0
+Summary: Train stock embeddings (Node2Vec, spectral, NetMF, raw baselines) from price data
+Author: Tomasz Rymaszeski
+License: MIT License
+        
+        Copyright (c) 2026 Tomasz Rymaszeski
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/tomaszrymaszewski/stock_embeddings
+Project-URL: Documentation, https://docs.stockscore.live/
+Project-URL: Repository, https://github.com/tomaszrymaszewski/stock_embeddings
+Project-URL: Changelog, https://github.com/tomaszrymaszewski/stock_embeddings/blob/main/CHANGELOG.md
+Project-URL: Paper, https://dx.doi.org/10.2139/ssrn.7591058
+Keywords: stocks,embeddings,node2vec,graph,finance,correlation,quantitative-finance,representation-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.0
+Requires-Dist: networkx>=3.1
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: scipy>=1.11
+Requires-Dist: gensim>=4.3
+Requires-Dist: node2vec>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9; extra == "docs"
+Dynamic: license-file
+
+# stock-embeddings
+
+Train vector embeddings of stocks from their price history. Give the library a dict of
+`{ticker: prices}`, and it builds a stock-similarity graph from return correlations and
+embeds every stock into a dense vector — stocks that move together (and belong to similar
+businesses) end up close in embedding space.
+
+```python
+from stock_embeddings import train_embeddings
+
+data = {"AAPL": aapl_prices, "MSFT": msft_prices, "XOM": xom_prices, ...}
+embeddings = train_embeddings(data)   # -> {"AAPL": [64 floats], "MSFT": [...], ...}
+```
+
+**Full documentation: [docs.stockscore.live](https://docs.stockscore.live/)**
+
+## Summary
+
+`stock-embeddings` turns raw price panels into a `{ticker: vector}` dictionary using the
+pipeline from our research on correlation-graph stock embeddings:
+
+```
+prices -> returns -> correlation matrix -> graph -> embedding -> {ticker: vector}
+```
+
+Every stage is configurable with sane defaults: co-movement removal (market-neutral
+residuals, cross-sectional demeaning, spectral/RMT cleaning), graph construction
+(threshold + Forced Connectivity repair, MST, kNN), and the embedding family itself
+(Node2Vec, Laplacian Eigenmaps, NetMF, or raw-feature baselines).
+
+## Why this is useful
+
+- **Semantic stock similarity.** Embedding-space neighbours capture economic similarity
+  (sector, industry, business model) that raw correlation misses, because the graph +
+  random walks propagate relationships beyond direct pairwise correlation.
+- **Ready-made features.** The vectors are a compact, dense feature representation for
+  downstream ML: sector classification, clustering, peer selection, retrieval, or risk
+  models.
+- **Turnkey.** One function call, no data plumbing, no graph code, no tuning required —
+  defaults come from a seed-averaged, significance-tested research benchmark.
+- **Honest and reproducible.** All randomness is seeded; alternative embedding families
+  and no-embedding baselines are built in, so you can verify the embedding actually adds
+  value on your data.
+
+## Setup
+
+Requires Python 3.10+.
+
+```bash
+pip install stock-embeddings
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/tomaszrymaszewski/stock_embeddings.git
+cd stock_embeddings
+pip install .
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from stock_embeddings import train_embeddings
+
+# Any dict of ticker -> prices works: pandas Series (optionally with a
+# DatetimeIndex), lists, or numpy arrays.
+prices = pd.read_csv("prices.csv", index_col=0, parse_dates=True)
+data = {ticker: prices[ticker].dropna() for ticker in prices.columns}
+
+embeddings = train_embeddings(data)
+
+# Nearest neighbours of a stock:
+from stock_embeddings import fit
+result = fit(data)
+result.most_similar("AAPL", k=10)     # [("MSFT", 0.98), ("AMZN", 0.97), ...]
+result.to_dataframe()                 # embeddings as a DataFrame
+```
+
+## Usage
+
+Every parameter has a default; pass only what you want to change:
+
+```python
+embeddings = train_embeddings(
+    data,
+    dimensions=32,               # embedding size (default 64)
+    embedder="spectral",         # node2vec | spectral | netmf | raw_corr | raw_returns
+    graph_filtering="knn",       # threshold | mst | knn | signed_knn
+    knn_k=10,
+    market_neutral=True,         # regress out the market factor before building the graph
+    spectral_clean="market",     # remove the market eigenmode from the correlation matrix
+    seed=42,
+)
+```
+
+Use `fit()` instead of `train_embeddings()` to get the full `TrainResult` — embeddings,
+the returns matrix actually used, the similarity graph, and the resolved config — plus
+helpers like `to_dataframe()` and `most_similar()`.
+
+See the [documentation](https://docs.stockscore.live/) for the complete parameter
+reference and guides.
+
+## Research
+
+This library implements the method developed in our paper
+[*Stock Embeddings from Return-Correlation Graphs*](https://dx.doi.org/10.2139/ssrn.7591058),
+which benchmarks how well correlation-graph embeddings recover the GICS classification of
+stocks against honest baselines (raw correlation, MST, kNN, PMFG), with seed-averaged,
+significance-tested results. Read the paper for how we got here — the method choices,
+the defaults shipped in this library, and what the embeddings can and cannot do.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

stock_embeddings-0.1.0/README.md

@@ -0,0 +1,116 @@
+# stock-embeddings
+
+Train vector embeddings of stocks from their price history. Give the library a dict of
+`{ticker: prices}`, and it builds a stock-similarity graph from return correlations and
+embeds every stock into a dense vector — stocks that move together (and belong to similar
+businesses) end up close in embedding space.
+
+```python
+from stock_embeddings import train_embeddings
+
+data = {"AAPL": aapl_prices, "MSFT": msft_prices, "XOM": xom_prices, ...}
+embeddings = train_embeddings(data)   # -> {"AAPL": [64 floats], "MSFT": [...], ...}
+```
+
+**Full documentation: [docs.stockscore.live](https://docs.stockscore.live/)**
+
+## Summary
+
+`stock-embeddings` turns raw price panels into a `{ticker: vector}` dictionary using the
+pipeline from our research on correlation-graph stock embeddings:
+
+```
+prices -> returns -> correlation matrix -> graph -> embedding -> {ticker: vector}
+```
+
+Every stage is configurable with sane defaults: co-movement removal (market-neutral
+residuals, cross-sectional demeaning, spectral/RMT cleaning), graph construction
+(threshold + Forced Connectivity repair, MST, kNN), and the embedding family itself
+(Node2Vec, Laplacian Eigenmaps, NetMF, or raw-feature baselines).
+
+## Why this is useful
+
+- **Semantic stock similarity.** Embedding-space neighbours capture economic similarity
+  (sector, industry, business model) that raw correlation misses, because the graph +
+  random walks propagate relationships beyond direct pairwise correlation.
+- **Ready-made features.** The vectors are a compact, dense feature representation for
+  downstream ML: sector classification, clustering, peer selection, retrieval, or risk
+  models.
+- **Turnkey.** One function call, no data plumbing, no graph code, no tuning required —
+  defaults come from a seed-averaged, significance-tested research benchmark.
+- **Honest and reproducible.** All randomness is seeded; alternative embedding families
+  and no-embedding baselines are built in, so you can verify the embedding actually adds
+  value on your data.
+
+## Setup
+
+Requires Python 3.10+.
+
+```bash
+pip install stock-embeddings
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/tomaszrymaszewski/stock_embeddings.git
+cd stock_embeddings
+pip install .
+```
+
+## Quick start
+
+```python
+import pandas as pd
+from stock_embeddings import train_embeddings
+
+# Any dict of ticker -> prices works: pandas Series (optionally with a
+# DatetimeIndex), lists, or numpy arrays.
+prices = pd.read_csv("prices.csv", index_col=0, parse_dates=True)
+data = {ticker: prices[ticker].dropna() for ticker in prices.columns}
+
+embeddings = train_embeddings(data)
+
+# Nearest neighbours of a stock:
+from stock_embeddings import fit
+result = fit(data)
+result.most_similar("AAPL", k=10)     # [("MSFT", 0.98), ("AMZN", 0.97), ...]
+result.to_dataframe()                 # embeddings as a DataFrame
+```
+
+## Usage
+
+Every parameter has a default; pass only what you want to change:
+
+```python
+embeddings = train_embeddings(
+    data,
+    dimensions=32,               # embedding size (default 64)
+    embedder="spectral",         # node2vec | spectral | netmf | raw_corr | raw_returns
+    graph_filtering="knn",       # threshold | mst | knn | signed_knn
+    knn_k=10,
+    market_neutral=True,         # regress out the market factor before building the graph
+    spectral_clean="market",     # remove the market eigenmode from the correlation matrix
+    seed=42,
+)
+```
+
+Use `fit()` instead of `train_embeddings()` to get the full `TrainResult` — embeddings,
+the returns matrix actually used, the similarity graph, and the resolved config — plus
+helpers like `to_dataframe()` and `most_similar()`.
+
+See the [documentation](https://docs.stockscore.live/) for the complete parameter
+reference and guides.
+
+## Research
+
+This library implements the method developed in our paper
+[*Stock Embeddings from Return-Correlation Graphs*](https://dx.doi.org/10.2139/ssrn.7591058),
+which benchmarks how well correlation-graph embeddings recover the GICS classification of
+stocks against honest baselines (raw correlation, MST, kNN, PMFG), with seed-averaged,
+significance-tested results. Read the paper for how we got here — the method choices,
+the defaults shipped in this library, and what the embeddings can and cannot do.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

stock_embeddings-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stock-embeddings"
+version = "0.1.0"
+description = "Train stock embeddings (Node2Vec, spectral, NetMF, raw baselines) from price data"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Tomasz Rymaszeski" }]
+keywords = [
+    "stocks", "embeddings", "node2vec", "graph", "finance",
+    "correlation", "quantitative-finance", "representation-learning",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.26",
+    "pandas>=2.0",
+    "networkx>=3.1",
+    "scikit-learn>=1.3",
+    "scipy>=1.11",
+    "gensim>=4.3",
+    "node2vec>=0.5.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "build", "twine"]
+docs = ["mkdocs-material>=9"]
+
+[project.urls]
+Homepage = "https://github.com/tomaszrymaszewski/stock_embeddings"
+Documentation = "https://docs.stockscore.live/"
+Repository = "https://github.com/tomaszrymaszewski/stock_embeddings"
+Changelog = "https://github.com/tomaszrymaszewski/stock_embeddings/blob/main/CHANGELOG.md"
+Paper = "https://dx.doi.org/10.2139/ssrn.7591058"
+
+[tool.setuptools.packages.find]
+include = ["stock_embeddings*"]

stock_embeddings-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stock_embeddings-0.1.0/stock_embeddings/__init__.py

@@ -0,0 +1,21 @@
+"""stock_embeddings -- train stock embeddings from price data.
+
+Basic usage:
+    from stock_embeddings import train_embeddings
+
+    data = {"AAPL": aapl_price_series, "MSFT": msft_price_series, ...}
+    embeddings = train_embeddings(data)                          # all defaults
+    embeddings = train_embeddings(data, dimensions=32,           # any Config field
+                                  graph_filtering="knn",
+                                  embedder="spectral")
+
+Use `fit()` instead of `train_embeddings()` to also get the returns matrix,
+the similarity graph, and helper methods (to_dataframe, most_similar).
+"""
+
+from .api import TrainResult, fit, train_embeddings
+from .config import Config
+
+__version__ = "0.1.0"
+
+__all__ = ["train_embeddings", "fit", "Config", "TrainResult", "__version__"]

stock_embeddings-0.1.0/stock_embeddings/api.py

@@ -0,0 +1,132 @@
+"""Public API: train stock embeddings from a dict of price series."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, fields
+from typing import Mapping, Sequence, Union
+
+import networkx as nx
+import numpy as np
+import pandas as pd
+
+from .config import Config
+from .data import PriceSeries, prices_to_returns
+from .embedders import RAW_EMBEDDERS, build_embeddings
+from .graph import GraphBuilder
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TrainResult:
+    """Outcome of a training run.
+
+    Attributes:
+        embeddings: {ticker: vector} -- the primary output.
+        returns:    the aligned returns DataFrame actually used.
+        graph:      the stock similarity graph (None for raw_* embedders).
+        config:     the resolved Config used for this run.
+    """
+
+    embeddings: dict[str, list[float]]
+    returns: pd.DataFrame
+    graph: nx.Graph | None
+    config: Config
+
+    def to_dataframe(self) -> pd.DataFrame:
+        """Embeddings as a DataFrame indexed by ticker (one column per dimension)."""
+        return pd.DataFrame.from_dict(self.embeddings, orient="index")
+
+    def most_similar(self, ticker: str, k: int = 10) -> list[tuple[str, float]]:
+        """Top-k most cosine-similar tickers to `ticker` (excluding itself)."""
+        tickers = list(self.embeddings.keys())
+        if ticker not in tickers:
+            raise KeyError(f"{ticker!r} not in trained embeddings")
+        M = np.array([self.embeddings[t] for t in tickers], dtype=float)
+        norms = np.linalg.norm(M, axis=1, keepdims=True)
+        norms[norms == 0] = 1e-10
+        M = M / norms
+        sims = M @ M[tickers.index(ticker)]
+        order = np.argsort(sims)[::-1]
+        out = []
+        for i in order:
+            if tickers[i] == ticker:
+                continue
+            out.append((tickers[i], float(sims[i])))
+            if len(out) >= k:
+                break
+        return out
+
+
+def train_embeddings(
+    data: Mapping[str, PriceSeries],
+    config: Config | None = None,
+    **params,
+) -> dict[str, list[float]]:
+    """Train stock embeddings from a dict of {ticker: price series}.
+
+    Args:
+        data:   mapping of ticker -> prices (pandas Series, list, or numpy
+                array). A DatetimeIndex is used for alignment if present.
+        config: optional pre-built Config; keyword arguments override it.
+        **params: any Config field, e.g. ``dimensions=32``,
+            ``graph_filtering="knn"``, ``embedder="spectral"``.
+
+    Returns:
+        {ticker: embedding vector} dict.
+
+    Example:
+        >>> embeddings = train_embeddings({"AAPL": aapl_prices, "MSFT": msft_prices})
+        >>> embeddings = train_embeddings(data, dimensions=32, embedder="spectral")
+    """
+    return fit(data, config=config, **params).embeddings
+
+
+def fit(
+    data: Mapping[str, PriceSeries],
+    config: Config | None = None,
+    **params,
+) -> TrainResult:
+    """Like :func:`train_embeddings` but returns the full :class:`TrainResult`
+    (embeddings + returns + graph + resolved config)."""
+    config = _resolve_config(config, params)
+    _setup_logging(config.verbose)
+
+    returns = prices_to_returns(data, config)
+
+    graph = None
+    if config.embedder not in RAW_EMBEDDERS:
+        graph = GraphBuilder(config).build(returns)
+
+    embeddings = build_embeddings(config, returns, graph=graph)
+    logger.info("Trained %d embeddings (embedder=%s)", len(embeddings),
+                config.embedder)
+    return TrainResult(embeddings=embeddings, returns=returns, graph=graph,
+                       config=config)
+
+
+def _resolve_config(config: Config | None, params: dict) -> Config:
+    if config is None:
+        return Config(**params)
+    if not params:
+        return config
+    known = {f.name for f in fields(Config)}
+    unknown = set(params) - known
+    if unknown:
+        raise TypeError(f"Unknown Config parameter(s): {sorted(unknown)}")
+    overrides = {f.name: getattr(config, f.name) for f in fields(Config)}
+    overrides.update(params)
+    return Config(**overrides)
+
+
+def _setup_logging(verbose: bool) -> None:
+    level = logging.INFO if verbose else logging.WARNING
+    logger.setLevel(level)
+    pkg_logger = logging.getLogger("stock_embeddings")
+    pkg_logger.setLevel(level)
+    if verbose and not pkg_logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        pkg_logger.addHandler(handler)
+        pkg_logger.propagate = False

stock_embeddings-0.1.0/stock_embeddings/config.py

@@ -0,0 +1,97 @@
+"""Configuration for stock embedding training. All parameters have sane defaults."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Config:
+    """Central control panel for embedding training.
+
+    Every field can be passed as a keyword argument to
+    :func:`stock_embeddings.train_embeddings`.
+    """
+
+    # -------------------------------------------------------------------------
+    # Embedding family
+    # -------------------------------------------------------------------------
+    # "node2vec"     -> local random walks + skip-gram (default)
+    # "spectral"     -> Laplacian Eigenmaps (global spectral geometry)
+    # "netmf"        -> DeepWalk-as-matrix-factorization (closed-form skip-gram)
+    # "raw_corr"     -> no embedding: a stock IS its correlation row
+    # "raw_returns"  -> no embedding: a stock IS its standardized return series
+    embedder: str = "node2vec"
+
+    # Embedding dimensionality (ignored by raw_* embedders, which are data-shaped).
+    dimensions: int = 64
+
+    # Random seed for walks / Word2Vec init / eigensolvers.
+    seed: int = 42
+
+    # -------------------------------------------------------------------------
+    # Graph construction
+    # -------------------------------------------------------------------------
+    # 'threshold'   = connect stocks if |correlation| > correlation_threshold
+    # 'mst'         = maximum spanning tree backbone (+ optional extra edges)
+    # 'knn'         = connect each stock to its K strongest-correlated peers (|corr|)
+    # 'signed_knn'  = kNN ranked by SIGNED correlation (anti-correlated peers excluded)
+    graph_filtering: str = "threshold"
+
+    # Only used if graph_filtering == 'threshold'
+    correlation_threshold: float = 0.65
+
+    # Forced Connectivity: repair under-connected nodes to a minimum degree.
+    repair_islands: bool = True
+    min_degree: int = 3
+
+    # Only used if graph_filtering in ('knn', 'signed_knn')
+    knn_k: int = 10
+
+    # Only used if graph_filtering == 'mst'
+    mst_extra_edges_pct: float = 0.05   # 0.0 = pure MST; 0.05 = add top 5% unused edges
+    mst_squared_corr: bool = True       # use corr^2 as edge weight
+    # Mantegna (1999) distance-transform MST on SIGNED correlation; overrides the
+    # mst_squared_corr / abs weighting above.
+    mst_distance_transform: bool = False
+
+    # -------------------------------------------------------------------------
+    # Node2Vec walk parameters
+    # -------------------------------------------------------------------------
+    walk_p: float = 0.8                 # return parameter
+    walk_q: float = 7.2                 # in-out parameter
+    walk_length: int = 20
+    num_walks: int = 100
+    window: int = 10                    # skip-gram window (also NetMF window)
+
+    # -------------------------------------------------------------------------
+    # Similarity matrix estimation
+    # -------------------------------------------------------------------------
+    # True = Graphical Lasso (partial correlation); False = Pearson correlation.
+    use_precision_matrix: bool = False
+    # lasso_alpha = 0.0 -> GraphicalLassoCV (slow CV); > 0.0 -> fixed-alpha (fast).
+    # With lasso, use a SMALL correlation_threshold (~0.02-0.1).
+    lasso_alpha: float = 0.0
+
+    # Market-neutral residualization: regress out a market factor and keep residuals.
+    # Factor = `market_ticker` column if present, else equal-weighted average.
+    market_neutral: bool = False
+    market_ticker: str = "SPY"
+
+    # Cross-sectional demeaning: subtract each day's equal-weighted mean return.
+    cross_sectional_demean: bool = False
+
+    # Spectral (RMT) cleaning of the correlation matrix:
+    #   "none" | "market" (drop top eigenmode) | "topk" (drop top spectral_k)
+    #   | "rmt" (keep only modes above the Marchenko-Pastur edge)
+    spectral_clean: str = "none"
+    spectral_k: int = 1
+
+    # -------------------------------------------------------------------------
+    # Data preparation
+    # -------------------------------------------------------------------------
+    # Drop tickers with less than this fraction of non-NaN observations.
+    min_history_frac: float = 0.8
+    # Minimum number of return observations required to train.
+    min_rows: int = 30
+
+    # Print progress logs.
+    verbose: bool = True