From d8759b238bf92df81995f0c6b1dc8c107dc2bfc0 Mon Sep 17 00:00:00 2001 From: Stefan Jansen Date: Wed, 9 Sep 2026 15:26:00 -0400 Subject: [PATCH 1/2] docs: remove private calendar reference --- src/ml4t/engineer/labeling/calendar.py | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/ml4t/engineer/labeling/calendar.py b/src/ml4t/engineer/labeling/calendar.py index 3bf128f..1ac9302 100644 --- a/src/ml4t/engineer/labeling/calendar.py +++ b/src/ml4t/engineer/labeling/calendar.py @@ -326,14 +326,6 @@ def _calendar_session_ids( return sorted_data, session_ids -# ExchangeCalendar adapter removed - use pandas_market_calendars directly -# See .claude/reference/calendar_libraries.md for rationale: -# - pandas_market_calendars includes ALL exchange_calendars features as dependency -# - Adds critical product-specific calendars (CME_Equity, CME_Agriculture, etc.) -# - Correctly handles CME futures maintenance breaks (4-5 PM CT) -# - Better maintenance, more features, zero downside - - def calendar_aware_labels( data: pl.DataFrame, config: LabelingConfig, From a1a3529e6e2e96460f59cf313790ffe3c4e84e2c Mon Sep 17 00:00:00 2001 From: Stefan Jansen Date: Thu, 10 Sep 2026 14:20:14 -0400 Subject: [PATCH 2/2] docs: align agent orientation with ecosystem policy --- AGENTS.md | 141 +++++++++++++++--------------------- src/ml4t/engineer/AGENTS.md | 113 ++++++++--------------------- 2 files changed, 90 insertions(+), 164 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 19fbf2a..cf2b874 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,84 +1,63 @@ # ml4t-engineer -Feature engineering for financial ML: compute indicators, create labels, sample -alternative bars, and prepare leakage-safe datasets for model training. - -## Quick Start - -```python -from ml4t.engineer import compute_features, create_dataset_builder -from ml4t.engineer.config import LabelingConfig -from ml4t.engineer.labeling import triple_barrier_labels - -features = compute_features(df, ["rsi", "macd", "atr"]) -labels = triple_barrier_labels( - features, - config=LabelingConfig.triple_barrier( - upper_barrier=0.02, lower_barrier=0.01, max_holding_period=20, - ), -) -builder = create_dataset_builder( - features=labels.select(["rsi", "macd", "atr"]), - labels=labels["label"], - dates=labels["timestamp"], - scaler="robust", -) -``` - -## Directory Map - -| Path | Purpose | Key Surfaces | -|------|---------|--------------| -| `src/ml4t/engineer/features/` | Feature computation and discovery metadata | `compute_features()`, `feature_catalog`, `FeatureCatalog` | -| `src/ml4t/engineer/labeling/` | Supervised label generation and sample weighting | `triple_barrier_labels()`, `atr_triple_barrier_labels()`, `rolling_percentile_binary_labels()` | -| `src/ml4t/engineer/bars/` | Tick, volume, dollar, imbalance, and run bars | `TickBarSampler`, `VolumeBarSampler`, `DollarBarSampler` | -| `src/ml4t/engineer/dataset.py` | Leakage-safe dataset preparation | `MLDatasetBuilder`, `create_dataset_builder()` | -| `src/ml4t/engineer/preprocessing.py` | Train-only scalers and pipelines | `StandardScaler`, `RobustScaler`, `PreprocessingPipeline` | -| `src/ml4t/engineer/config/` | Reusable config objects | `LabelingConfig`, `PreprocessingConfig`, `DataContractConfig` | - -## Public Entry Points - -```python -from ml4t.engineer import ( - compute_features, - create_dataset_builder, - feature_catalog, - FeatureCatalog, - StandardScaler, - RobustScaler, -) -from ml4t.engineer.config import LabelingConfig -from ml4t.engineer.labeling import ( - triple_barrier_labels, - atr_triple_barrier_labels, - rolling_percentile_binary_labels, - fixed_time_horizon_labels, - trend_scanning_labels, -) -from ml4t.engineer.bars import ( - TickBarSampler, - VolumeBarSampler, - DollarBarSampler, - FixedTickImbalanceBarSampler, - FixedVolumeImbalanceBarSampler, -) +`ml4t-engineer` provides Polars-first feature engineering, labeling, alternative +bars, and leakage-safe dataset preparation for financial machine learning. + +## Source orientation + +Runtime code lives under `src/ml4t/engineer/`. + +- `api.py`, `features/`, and `discovery/` implement registry-backed feature + computation and discovery. +- `labeling/` implements path-dependent, fixed-horizon, percentile, meta-label, + and sample-weighting workflows. +- `bars/` converts trade data into tick, volume, dollar, imbalance, and run bars. +- `dataset.py` and `preprocessing.py` implement train/test preparation and + train-only transformations. +- `core/` and `config/` contain registry metadata, validation, schemas, and + reusable configuration models. +- `artifacts/`, `relationships/`, `store/`, `logging/`, and `utils/` provide + supporting services. + +Tests are under `tests/`. Executable examples and repository checks are under +`examples/` and `scripts/`. + +## Public workflows + +Stable entry points include: + +- `ml4t.engineer.compute_features` +- `ml4t.engineer.feature_catalog` +- `ml4t.engineer.create_dataset_builder` +- labeling functions under `ml4t.engineer.labeling` +- bar samplers under `ml4t.engineer.bars` + +Start with `README.md` and `docs/getting-started/`. Detailed workflow guidance +is under `docs/user-guide/`, and the generated API reference is under +`docs/api/`. + +## Engineering constraints + +- Python 3.12, 3.13, and 3.14 are supported. +- Feature computation must preserve the documented DataFrame or LazyFrame + return behavior. +- Changes to registered features must keep implementation, registry metadata, + dependencies, normalization metadata, and lookback behavior consistent. +- Fit preprocessing state only on training data. +- Keep optional dependencies isolated from the base import. +- Shared data-contract changes originate in `ml4t-specs`. + +## Quality commands + +Run from the repository root: + +```bash +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 ``` - -## Core Workflows - -- `compute_features()` appends indicator columns to an OHLCV DataFrame or LazyFrame -- `LabelingConfig` plus labeling functions create reusable supervised targets -- `MLDatasetBuilder` handles train/test splitting and train-only scaling -- sampler classes in `bars/` turn trade data into non-time bars for downstream use - -## Trust Signals - -- 120 features across 11 categories -- 60 TA-Lib validated indicators at `1e-6` tolerance -- ~50,000 labels/second for triple-barrier workflows -- shared book integration via `docs/book-guide/index.md` - -## Navigation - -See [src/ml4t/engineer/AGENTS.md](src/ml4t/engineer/AGENTS.md) for package-level -module orientation and subdirectory entry points. diff --git a/src/ml4t/engineer/AGENTS.md b/src/ml4t/engineer/AGENTS.md index 061071e..332686e 100644 --- a/src/ml4t/engineer/AGENTS.md +++ b/src/ml4t/engineer/AGENTS.md @@ -1,83 +1,30 @@ -# ml4t.engineer Package - -Package-level navigation for the public `ml4t-engineer` surface. - -## Main Modules - -| Module | Purpose | Key Exports | -|--------|---------|-------------| -| `api.py` | Feature-computation entry point | `compute_features()` | -| `dataset.py` | Leakage-safe dataset preparation | `MLDatasetBuilder`, `create_dataset_builder()` | -| `preprocessing.py` | Train-only scalers and transform pipelines | `StandardScaler`, `MinMaxScaler`, `RobustScaler`, `PreprocessingPipeline` | -| `discovery/catalog.py` | Metadata-driven feature exploration | `FeatureCatalog`, `feature_catalog` | -| `config/` | Reusable config models | `LabelingConfig`, `PreprocessingConfig`, `DataContractConfig` | -| `__init__.py` | Public re-exports and AGENTS discovery helper | `get_agent_docs()` | - -## Subdirectories - -| Directory | Purpose | AGENTS | -|-----------|---------|--------| -| `features/` | Registry-backed indicator implementations and standalone feature helpers | [features/AGENTS.md](features/AGENTS.md) | -| `labeling/` | Barrier labels, percentile labels, meta-labeling, uniqueness | [labeling/AGENTS.md](labeling/AGENTS.md) | -| `bars/` | Tick, volume, dollar, imbalance, and run bars | [bars/AGENTS.md](bars/AGENTS.md) | -| `core/` | Registry, metadata, schemas, decorators, validation | [core/AGENTS.md](core/AGENTS.md) | -| `config/` | Pydantic configuration models and schema bridges | [config/AGENTS.md](config/AGENTS.md) | -| `discovery/` | Metadata-driven feature search and filtering | [discovery/AGENTS.md](discovery/AGENTS.md) | -| `relationships/` | Correlation helpers and plotting utilities | [relationships/AGENTS.md](relationships/AGENTS.md) | -| `store/` | Offline DuckDB storage helpers | [store/AGENTS.md](store/AGENTS.md) | -| `artifacts/` | Lightweight artifact records for features, labels, predictions | [artifacts/AGENTS.md](artifacts/AGENTS.md) | -| `logging/` | Structured logging configuration | [logging/AGENTS.md](logging/AGENTS.md) | -| `utils/` | optional dependency helpers and low-level utilities | [utils/AGENTS.md](utils/AGENTS.md) | - -## Current Public API Shape - -```python -from ml4t.engineer import ( - compute_features, - create_dataset_builder, - feature_catalog, - MLDatasetBuilder, - StandardScaler, - RobustScaler, -) -from ml4t.engineer.config import LabelingConfig, PreprocessingConfig -from ml4t.engineer.labeling import triple_barrier_labels, atr_triple_barrier_labels -from ml4t.engineer.bars import TickBarSampler, VolumeBarSampler, DollarBarSampler -``` - -## Core Patterns - -### Compute features through the registry - -```python -from ml4t.engineer import compute_features - -result = compute_features(df, ["rsi", "macd", "atr"]) -``` - -### Discover features through metadata - -```python -from ml4t.engineer import feature_catalog - -feature_catalog.list(category="momentum") -feature_catalog.search("volatility estimator") -feature_catalog.describe("rsi") -``` - -### Build train/test data without leakage - -```python -from ml4t.engineer import create_dataset_builder - -builder = create_dataset_builder(features, labels, scaler="robust") -X_train, X_test, y_train, y_test = builder.train_test_split(train_size=0.8) -``` - -## Notes - -- `FeatureSelector` has moved out of this library and belongs in `ml4t-diagnostic` -- `store/` exists but is lower-priority than the core feature, labeling, bar, and - dataset workflows -- AGENTS files are the current navigation surface; older singular filename references - should be treated as stale +# ml4t.engineer package + +These instructions apply within `src/ml4t/engineer/`. Use the repository-root +`AGENTS.md` for setup and quality commands. + +## Internal structure + +- `core/registry.py` and `core/decorators.py` own feature registration and + metadata. +- `api.py` resolves registered features, their dependencies, and execution + order. +- `features/` contains registered indicators and standalone transforms. +- `labeling/`, `bars/`, `dataset.py`, and `preprocessing.py` implement the + primary downstream workflows. +- `config/` bridges reusable configuration and shared `ml4t-specs` contracts. + +## Local rules + +- A registered feature change must keep its decorator metadata and first usable + row consistent with its implementation. +- Preserve DataFrame and LazyFrame behavior where the public workflow supports + both. +- Label calculations must not introduce future information before the declared + horizon. +- Preprocessing state is fitted on training observations only. +- Guard optional integrations through the existing dependency helpers so + `import ml4t.engineer` works with base dependencies. + +Use the scoped guides in `features/AGENTS.md`, `labeling/AGENTS.md`, and +`bars/AGENTS.md` when working in those subsystems.