ml4t-engineer 0.1.0__py3-none-any.whl

ml4t/engineer/AGENTS.md

@@ -0,0 +1,83 @@
+# 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/__init__.py

@@ -0,0 +1,151 @@
+"""ml4t-engineer - A Financial Machine Learning Feature Engineering Library.
+
+ml4t-engineer is a comprehensive FML stack designed for correctness, reproducibility,
+and performance. It provides tools for feature engineering, labeling, and preprocessing
+for financial machine learning models.
+
+Agent Navigation:
+    This package includes AGENTS.md files for AI agent navigation.
+    Call `get_agent_docs()` to get paths to all documentation files.
+    Start with the root AGENTS.md for package overview and navigation.
+"""
+
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _dist_version
+from pathlib import Path as _Path
+
+from . import _polars_compat as _polars_compat
+from . import (
+    core,
+    dataset,
+    discovery,
+    features,
+    labeling,
+    preprocessing,
+    relationships,
+    store,
+)
+from .api import compute_features
+from .dataset import (
+    DatasetInfo,
+    FoldResult,
+    MLDatasetBuilder,
+    create_dataset_builder,
+)
+from .discovery import FeatureCatalog
+from .discovery.catalog import features as feature_catalog
+from .preprocessing import (
+    BaseScaler,
+    MinMaxScaler,
+    NotFittedError,
+    PreprocessingPipeline,
+    Preprocessor,
+    RobustScaler,
+    StandardScaler,
+    TransformType,
+)
+
+try:
+    from ._version import version as __version__
+except Exception:
+    try:
+        __version__ = _dist_version("ml4t-engineer")
+    except _PackageNotFoundError:
+        __version__ = "0+unknown"
+
+
+def get_agent_docs() -> dict[str, _Path]:
+    """Get paths to AGENTS.md documentation files for AI agent navigation.
+
+    Returns a dict mapping logical names to file paths. Start with 'root'
+    for package overview, then drill into specific areas as needed.
+
+    Returns
+    -------
+    dict[str, Path]
+        Mapping of doc names to paths. Keys include:
+        - 'root': Package overview and directory map
+        - 'features': Feature category index (120 indicators)
+        - 'features/{category}': Category-specific signatures
+        - 'labeling': ML label generation methods
+        - 'bars': Alternative bar sampling
+        - 'core', 'core/calendars': Registry and validation internals
+        - 'config': Reusable configuration models
+        - 'discovery': Metadata-driven feature search
+        - 'artifacts', 'relationships', 'store', 'logging', 'utils': Secondary
+          package areas with their own navigation guides
+
+    Example
+    -------
+    >>> from ml4t.engineer import get_agent_docs
+    >>> docs = get_agent_docs()
+    >>> print(docs['root'].read_text()[:200])  # Read overview
+    """
+    pkg_dir = _Path(__file__).parent
+    docs: dict[str, _Path] = {}
+
+    # Root and package-level
+    if (p := pkg_dir / "AGENTS.md").exists():
+        docs["root"] = p
+
+    # Features index and categories
+    features_dir = pkg_dir / "features"
+    if (p := features_dir / "AGENTS.md").exists():
+        docs["features"] = p
+    for category_dir in features_dir.iterdir():
+        if category_dir.is_dir() and (p := category_dir / "AGENTS.md").exists():
+            docs[f"features/{category_dir.name}"] = p
+
+    # Other modules
+    for module in [
+        "labeling",
+        "bars",
+        "core",
+        "config",
+        "discovery",
+        "artifacts",
+        "relationships",
+        "store",
+        "logging",
+        "utils",
+    ]:
+        if (p := pkg_dir / module / "AGENTS.md").exists():
+            docs[module] = p
+    if (p := pkg_dir / "core" / "calendars" / "AGENTS.md").exists():
+        docs["core/calendars"] = p
+
+    return docs
+
+
+__all__ = [
+    # Main API
+    "compute_features",
+    # Agent navigation
+    "get_agent_docs",
+    # Feature Discovery (discoverability API)
+    "FeatureCatalog",
+    "feature_catalog",
+    # Dataset builder (leakage-safe train/test preparation)
+    "MLDatasetBuilder",
+    "create_dataset_builder",
+    "FoldResult",
+    "DatasetInfo",
+    # Preprocessing (leakage-safe scalers)
+    "Preprocessor",
+    "PreprocessingPipeline",
+    "TransformType",
+    "StandardScaler",
+    "MinMaxScaler",
+    "RobustScaler",
+    "BaseScaler",
+    "NotFittedError",
+    # Submodules
+    "core",
+    "dataset",
+    "discovery",
+    "features",
+    "labeling",
+    "preprocessing",
+    "relationships",
+    "store",
+]

ml4t/engineer/_numba.py

@@ -0,0 +1,32 @@
+"""Numba decorators with a pure-Python fallback for unsupported runtimes."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib import import_module
+from typing import Any, TypeVar
+
+_Function = TypeVar("_Function", bound=Callable[..., Any])
+
+
+def _identity_jit(*args: Any, **kwargs: Any) -> Any:
+    """Return the undecorated function when Numba is unavailable."""
+    del kwargs
+    if len(args) == 1 and callable(args[0]):
+        return args[0]
+
+    def decorate(function: _Function) -> _Function:
+        return function
+
+    return decorate
+
+
+def _load_numba_decorators() -> tuple[Any, Any, bool]:
+    try:
+        numba = import_module("numba")
+    except ImportError:
+        return _identity_jit, _identity_jit, False
+    return numba.jit, numba.njit, True
+
+
+jit, njit, NUMBA_AVAILABLE = _load_numba_decorators()

ml4t/engineer/_polars_compat.py

@@ -0,0 +1,71 @@
+"""Compatibility repair for Polars Series dispatch on CPython 3.15."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Container
+from datetime import datetime
+from importlib import import_module
+from types import FunctionType
+
+_SERIES_CLASSES = (
+    ("polars.series.series", "Series"),
+    ("polars.series.array", "ArrayNameSpace"),
+    ("polars.series.binary", "BinaryNameSpace"),
+    ("polars.series.categorical", "CatNameSpace"),
+    ("polars.series.datetime", "DateTimeNameSpace"),
+    ("polars.series.ext", "ExtensionNameSpace"),
+    ("polars.series.list", "ListNameSpace"),
+    ("polars.series.string", "StringNameSpace"),
+    ("polars.series.struct", "StructNameSpace"),
+)
+_BROKEN_SERIES_ERROR = "'NoneType' object has no attribute '_s'"
+
+
+def _has_py315_docstring_layout(function: FunctionType, empty_bytecode: Container[bytes]) -> bool:
+    code = function.__code__
+    return (
+        code.co_code in empty_bytecode
+        and isinstance(function.__doc__, str)
+        and code.co_consts == (function.__doc__,)
+    )
+
+
+def ensure_polars_series_dispatch() -> None:
+    """Repair pola-rs/polars#28347 only when its Python 3.15 failure is present."""
+    if sys.version_info < (3, 15):
+        return
+
+    import polars as pl
+
+    expected = datetime(2000, 1, 1)
+    try:
+        pl.Series("_ml4t_polars_probe", [expected])
+        return
+    except AttributeError as error:
+        if _BROKEN_SERIES_ERROR not in str(error):
+            raise
+
+    utils = import_module("polars.series.utils")
+    predicate_name = "_is_empty_method"
+    original_is_empty = getattr(utils, predicate_name)
+    empty_bytecode = utils._EMPTY_BYTECODE
+
+    def is_empty_method(function: FunctionType) -> bool:
+        return original_is_empty(function) or _has_py315_docstring_layout(function, empty_bytecode)
+
+    setattr(utils, predicate_name, is_empty_method)
+    try:
+        for module_name, class_name in _SERIES_CLASSES:
+            utils.expr_dispatch(getattr(import_module(module_name), class_name))
+
+        probe = pl.Series("_ml4t_polars_probe", [expected])
+        if probe.to_list() != [expected]:
+            raise RuntimeError("Polars Series dispatch probe returned an invalid result")
+    except Exception as error:
+        raise RuntimeError("Unable to repair Polars Series dispatch on Python 3.15") from error
+    finally:
+        setattr(utils, predicate_name, original_is_empty)
+
+
+ensure_polars_series_dispatch()

ml4t/engineer/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None