Metadata-Version: 2.5
Name: ml4t-engineer
Version: 0.2.1
Summary: Feature engineering, labeling, alternative bars, and leakage-safe datasets for financial ML.
Project-URL: Homepage, https://www.ml4trading.io/
Project-URL: Documentation, https://www.ml4trading.io/docs/engineer/
Project-URL: Repository, https://github.com/ml4t/engineer
Project-URL: Issues, https://github.com/ml4t/engineer/issues
Project-URL: Changelog, https://github.com/ml4t/engineer/releases
Author-email: Stefan Jansen <stefan@applied-ai.com>
Maintainer-email: Stefan Jansen <pm@ml4trading.io>
License: MIT
License-File: LICENSE
Keywords: algorithmic-trading,backtesting,feature-engineering,features,finance,labeling,machine-learning,microstructure,polars,quantitative-finance,technical-analysis,trading
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: ml4t-specs<0.3.0,>=0.2.0
Requires-Dist: numba>=0.57.0
Requires-Dist: numpy<2.6,>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: polars>=2.0.0
Requires-Dist: pydantic<3,>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: structlog>=23.0.0
Provides-Extra: all
Requires-Dist: arch>=6.0.0; extra == 'all'
Requires-Dist: duckdb>=0.9.0; extra == 'all'
Requires-Dist: hypothesis>=6.80.0; extra == 'all'
Requires-Dist: ipdb>=0.13.0; extra == 'all'
Requires-Dist: ipython>=8.14.0; extra == 'all'
Requires-Dist: lightgbm>=4.0.0; extra == 'all'
Requires-Dist: matplotlib>=3.7.0; extra == 'all'
Requires-Dist: mkdocs-material>=9.5.0; extra == 'all'
Requires-Dist: mkdocs<2,>=1.6; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'all'
Requires-Dist: pandas-market-calendars>=5.5.0; extra == 'all'
Requires-Dist: plotly>=5.15.0; extra == 'all'
Requires-Dist: pre-commit>=3.3.0; extra == 'all'
Requires-Dist: pyarrow>=14.0.0; extra == 'all'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest-timeout>=2.1.0; extra == 'all'
Requires-Dist: pytest-xdist>=3.3.0; extra == 'all'
Requires-Dist: pytest>=7.4.0; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: seaborn>=0.12.0; extra == 'all'
Requires-Dist: shap>=0.44.0; extra == 'all'
Requires-Dist: statsmodels>=0.14.0; extra == 'all'
Requires-Dist: ta-lib<0.9,>=0.8.2; extra == 'all'
Provides-Extra: calendars
Requires-Dist: pandas-market-calendars>=5.5.0; extra == 'calendars'
Provides-Extra: dev
Requires-Dist: arch>=6.0.0; extra == 'dev'
Requires-Dist: duckdb>=0.9.0; extra == 'dev'
Requires-Dist: hypothesis>=6.80.0; extra == 'dev'
Requires-Dist: ipdb>=0.13.0; extra == 'dev'
Requires-Dist: ipython>=8.14.0; extra == 'dev'
Requires-Dist: lightgbm>=4.0.0; extra == 'dev'
Requires-Dist: pandas-market-calendars>=5.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.3.0; extra == 'dev'
Requires-Dist: pyarrow>=14.0.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.3.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: shap>=0.44.0; extra == 'dev'
Requires-Dist: statsmodels>=0.14.0; extra == 'dev'
Requires-Dist: ta-lib<0.9,>=0.8.2; extra == 'dev'
Requires-Dist: yfinance>=0.2.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: ml
Requires-Dist: lightgbm>=4.0.0; extra == 'ml'
Requires-Dist: shap>=0.44.0; extra == 'ml'
Provides-Extra: stats
Requires-Dist: scipy>=1.14.0; extra == 'stats'
Requires-Dist: statsmodels>=0.14.0; extra == 'stats'
Provides-Extra: store
Requires-Dist: duckdb>=0.9.0; extra == 'store'
Requires-Dist: pyarrow>=14.0.0; extra == 'store'
Provides-Extra: ta
Requires-Dist: ta-lib<0.9,>=0.8.2; extra == 'ta'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7.0; extra == 'viz'
Requires-Dist: plotly>=5.15.0; extra == 'viz'
Requires-Dist: pyarrow>=14.0.0; extra == 'viz'
Requires-Dist: seaborn>=0.12.0; extra == 'viz'
Description-Content-Type: text/markdown

# ml4t-engineer

[![Python 3.12-3.15](https://img.shields.io/badge/python-3.12--3.15-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/ml4t-engineer)](https://pypi.org/project/ml4t-engineer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ml4t/engineer/blob/main/LICENSE)

Feature engineering, labeling, alternative bars, and leakage-safe datasets for
financial ML.

`ml4t-engineer` provides 120 registry features across 11 categories, path-dependent
and fixed-horizon labeling, activity-based bar sampling, and train-only preprocessing.
The core interface uses Polars DataFrames.

## Installation

Development source supports Python 3.12, 3.13, 3.14, and 3.15 on Linux, macOS, and Windows.
Python 3.15 support and the calendar API used below are intended for the 0.2 release.
Release 0.1.6 supports Python 3.12-3.14; use its
[version-matched quick start](https://github.com/ml4t/engineer/tree/v0.1.6#quick-start)
instead of passing the new `calendar` argument to that release.

```bash
pip install ml4t-engineer
```

Until 0.2 is available from PyPI, run the examples below from a
[source checkout](#development) with `uv sync --no-dev`, using that environment's Python.

The quick start uses only core dependencies. Optional extras provide TA-Lib validation,
DuckDB and PyArrow storage, market calendars, visualization, statistics, and ML tools:

```bash
pip install "ml4t-engineer[ta]"
pip install "ml4t-engineer[store]"
pip install "ml4t-engineer[calendars]"
pip install "ml4t-engineer[viz]"
pip install "ml4t-engineer[stats]"
pip install "ml4t-engineer[ml]"
```

The development `ta` extra uses TA-Lib 0.8.2 or later in the 0.8 series; its wheels
include the native library. For source builds, follow the
[upstream installation guide](https://github.com/TA-Lib/ta-lib-python#installation).
The core package does not require an external service, credentials, or special hardware.

## Quick Start

<!-- ml4t-exec -->
```python
from datetime import date, timedelta

import polars as pl
from ml4t.engineer import compute_features

close = [100.0 + i * 0.1 + (i % 7) * 0.2 for i in range(100)]
ohlcv = pl.DataFrame(
    {
        "timestamp": [date(2024, 1, 1) + timedelta(days=i) for i in range(100)],
        "open": close,
        "high": [price + 1.0 for price in close],
        "low": [price - 1.0 for price in close],
        "close": close,
        "volume": [100_000 + i * 100 for i in range(100)],
    }
)

features = compute_features(ohlcv, ["rsi", "macd", "atr"], calendar=None)

assert {"rsi", "macd", "atr"} <= set(features.columns)
assert features.height == ohlcv.height
```

`compute_features()` returns the input columns with the requested feature columns
appended. This example explicitly uses observation-row mode with `calendar=None`;
periods count rows, not scheduled sessions or elapsed days. Use the feature registry
to inspect categories and parameters before building larger pipelines.

## Supported Workflows

- Technical, volatility, risk, microstructure, statistical, and ML-oriented features
- Triple-barrier, ATR-barrier, percentile, fixed-horizon, trend-scanning, and meta-labels
- Tick, volume, dollar, imbalance, and run bars
- Train/test splitting with train-only scaling
- Feature metadata search and discovery

See the [documentation](https://www.ml4trading.io/docs/engineer/) for tutorials,
task-oriented guides, explanations, and the API reference. Report defects and request
changes through [GitHub Issues](https://github.com/ml4t/engineer/issues).

## Related Libraries

- [`ml4t-specs`](https://github.com/ml4t/specs) defines the shared market-data and
  artifact contracts used by this package.
- [`ml4t-data`](https://github.com/ml4t/data) supplies validated market data for feature
  computation.
- [`ml4t-diagnostic`](https://github.com/ml4t/diagnostic) evaluates features, labels, and
  model signals produced from engineered datasets.

## Development

Read [CONTRIBUTING.md](https://github.com/ml4t/engineer/blob/main/CONTRIBUTING.md) before opening
an issue or pull request.

```bash
git clone https://github.com/ml4t/engineer.git
cd engineer
uv sync --dev --extra docs --extra ta --extra store --extra viz
uv run ruff check src/ tests/ examples/ scripts/
uv run ruff format --check src/ tests/ examples/ scripts/
uv run ty check
uv run pytest tests/ -q
uv build
uv run python -c "import ml4t.engineer"
uv run mkdocs build --strict
```

Pull requests must also pass the supported Python and operating-system matrix,
dependency and vulnerability review, clean-wheel installation, documented workflow
tests, and ecosystem qualification.

## Project Information

- [Documentation](https://www.ml4trading.io/docs/engineer/)
- [Contributing](https://github.com/ml4t/engineer/blob/main/CONTRIBUTING.md)
- [Issue tracker](https://github.com/ml4t/engineer/issues)
- [Releases and changelog](https://github.com/ml4t/engineer/releases)
- [License](https://github.com/ml4t/engineer/blob/main/LICENSE)
