docs: mkdocs GitHub Pages deploy

.github/workflows/ci.yml

@@ -7,7 +7,7 @@ on:
     branches: [main]
 
 env:
-  PYTHON_VERSION: "3.11"
+  PYTHON_VERSION: "3.12"
 
 jobs:
   lint:
@@ -59,7 +59,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4

.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: "docs"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build & Deploy Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --dev --extra docs
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+      - name: Deploy to website repo
+        uses: cpina/github-action-push-to-another-repository@v1.7.2
+        env:
+          SSH_DEPLOY_KEY: ${{ secrets.DOCS_DEPLOY_KEY }}
+        with:
+          source-directory: site/
+          destination-github-username: ml4t
+          destination-repository-name: website
+          target-directory: static/docs/engineer/
+          target-branch: main
+          commit-message: "docs(engineer): update from ml4t/engineer@${{ github.sha }}"
+          user-name: ml4t-bot
+          user-email: bot@ml4trading.io

.github/workflows/release.yml

@@ -5,7 +5,7 @@ on:
     tags: ["v*"]
 
 env:
-  PYTHON_VERSION: "3.11"
+  PYTHON_VERSION: "3.12"
 
 jobs:
   build:

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 .hypothesis/
 htmlcov/
 
+# MkDocs build output
+site/
+
 # Claude Code (local development only)
 CLAUDE.md
 .claude/

AGENTS.md

@@ -0,0 +1,84 @@
+# 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_14", "macd", "atr_14"]),
+    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,
+)
+```
+
+## 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.

CHANGELOG.md

@@ -7,6 +7,34 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.0b3] - 2026-04-01
+
+### Added
+- Public documentation overhaul with a workflow-first landing page, Book Guide,
+  and tighter API/user-guide routing
+- Expanded `AGENTS.md` coverage across the package, including secondary modules
+  and wheel artifacts
+
+### Changed
+- Shared feed and artifact schema definitions now come from `ml4t-specs`
+- `data_contract_from_market_data_spec()` now normalizes inputs through
+  `ml4t.specs.FeedSpec`
+- Artifact schema defaults align with shared spec naming:
+  `asset`, `label_value`, and `prediction_value`
+
+### Removed
+- `DataContractConfig.from_ml4t_data()` in favor of shared spec-driven contracts
+
+## [0.1.0b2] - 2026-03-23
+
+### Added
+- Engineered artifact spec dataclasses for feature, label, and prediction outputs
+
+### Changed
+- Shared market data specs can now be bridged directly into engineer config
+
+## [0.1.0b1] - 2026-03-03
+
 ### Removed
 - Dead modules: `selection/`, `validation/`, `visualization/`, `pipeline/`
 - Diagnostic config classes (`feature_config.py`) — moved to ml4t-diagnostic
@@ -88,8 +116,8 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 - `get_agent_docs()` for AI agent discoverability
-- Hierarchical AGENT.md navigation files
-- AGENT.md files included in wheel builds
+- Hierarchical AGENTS.md navigation files
+- AGENTS.md files included in wheel builds
 
 ### Fixed
 - `variance_ratio` Int64 bug
@@ -118,7 +146,10 @@ Initial public alpha release.
 - `MLDatasetBuilder` for dataset construction
 - `PreprocessingPipeline` for feature transformation
 
-[Unreleased]: https://github.com/stefan-jansen/ml4t-engineer/compare/v0.1.0a11...HEAD
+[Unreleased]: https://github.com/stefan-jansen/ml4t-engineer/compare/v0.1.0b3...HEAD
+[0.1.0b3]: https://github.com/stefan-jansen/ml4t-engineer/compare/v0.1.0b2...v0.1.0b3
+[0.1.0b2]: https://github.com/stefan-jansen/ml4t-engineer/compare/v0.1.0b1...v0.1.0b2
+[0.1.0b1]: https://github.com/stefan-jansen/ml4t-engineer/compare/v0.1.0a11...v0.1.0b1
 [0.1.0a11]: https://github.com/stefan-jansen/ml4t-engineer/compare/v0.1.0a10...v0.1.0a11
 [0.1.0a10]: https://github.com/stefan-jansen/ml4t-engineer/compare/v0.1.0a9...v0.1.0a10
 [0.1.0a9]: https://github.com/stefan-jansen/ml4t-engineer/compare/v0.1.0a8...v0.1.0a9

README.md

@@ -1,6 +1,6 @@
 # ml4t-engineer
 
-[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-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://opensource.org/licenses/MIT)
 
@@ -164,6 +164,7 @@ ibars = TickImbalanceBarSampler(expected_imbalance=100).sample(tick_data)
 
 ## Related Libraries
 
+- **ml4t-specs**: Shared feed and artifact schema definitions across the ML4T stack
 - **ml4t-data**: Market data acquisition and storage
 - **ml4t-diagnostic**: Signal evaluation and statistical validation
 - **ml4t-backtest**: Event-driven backtesting

api.yaml

@@ -1,6 +1,6 @@
 name: ml4t-engineer
 version: 1.0.0
-python_requires: ">=3.11"
+python_requires: ">=3.12"
 description: High-performance feature engineering for financial machine learning
 
 modules: