Metadata-Version: 2.5
Name: ml4t-engineer
Version: 0.1.5
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: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Requires-Dist: ml4t-specs<0.2.0,>=0.1.0
Requires-Dist: numba>=0.57.0
Requires-Dist: numpy<2.6,>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: polars>=0.20.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>=4.0.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.8,>=0.4.0; extra == 'all'
Provides-Extra: calendars
Requires-Dist: pandas-market-calendars>=4.0.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>=4.0.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.8,>=0.4.0; 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: 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.8,>=0.4.0; 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.14](https://img.shields.io/badge/python-3.12--3.14-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)](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

`ml4t-engineer` supports Python 3.12, 3.13, and 3.14 on Linux, macOS, and Windows.

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

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]"
```

TA-Lib requires its native library. The core package does not require an external
service, credentials, or special hardware. Python 3.15 is not supported while the
active Polars compatibility exception applies.

## 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"])

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

`compute_features()` returns the input columns with the requested feature columns
appended. 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

```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 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/)
- [Issue tracker](https://github.com/ml4t/engineer/issues)
- [Releases and changelog](https://github.com/ml4t/engineer/releases)
- [License](LICENSE)
