docs: add PreTab ref, reorder sections, add v1 vs v2 migration guidance

mkumar73 · mkumar73 · commit 8c46f3d33844 · 2026-06-22T12:32:27.000+02:00
diff --git a/README.md b/README.md
@@ -24,7 +24,7 @@
 ## Why DeepTab?
 
 - **Familiar interface.** A scikit-learn `fit`/`predict`/`evaluate` API that drops into existing pipelines, including `GridSearchCV`.
-- **Automatic preprocessing.** Feature-type detection, encoding, scaling, and missing-value handling are built in.
+- **Automatic preprocessing.** Feature-type detection, encoding, scaling, and missing-value handling are powered by [PreTab](https://github.com/OpenTabular/PreTab) and applied for you.
 - **One model, three tasks.** Every architecture ships as a classifier, a regressor, and a distributional (`LSS`) variant for uncertainty quantification.
 - **A broad model zoo.** 15 stable architectures plus experimental models, all behind the same interface, with [selection guidance](https://deeptab.readthedocs.io/en/latest/model_zoo/index.html).
 - **Built for real data.** Mixed feature types, class imbalance, GPU acceleration, and early stopping work out of the box.
diff --git a/docs/core_concepts/config_system.md b/docs/core_concepts/config_system.md
@@ -3,7 +3,7 @@
 DeepTab uses a split-config API. Architecture, preprocessing, and training settings are kept in separate dataclasses so experiments can change one layer without mixing concerns.
 
 ```{important}
-The model constructor accepts `model_config`, `preprocessing_config`, and `trainer_config`. Flat constructor arguments are legacy compatibility only; new documentation and experiments should use split configs.
+The model constructor accepts `model_config`, `preprocessing_config`, and `trainer_config`. All settings must go through these config objects; the flat constructor arguments from v1 are no longer accepted and raise a `TypeError`.
 ```
 
 ## The Three Config Layers
@@ -16,6 +16,38 @@ The model constructor accepts `model_config`, `preprocessing_config`, and `train
 
 All three are optional. If omitted, DeepTab creates default config objects internally.
 
+### Moving from v1
+
+In v1, architecture, preprocessing, and training options were all passed as flat keyword arguments on the estimator. In v2 those same options live in three dedicated config objects. The estimator call is the only thing that changes; `fit`, `predict`, and `evaluate` behave exactly as before.
+
+```python
+# v1: every option flat on the estimator
+from deeptab.models import MambularClassifier
+
+model = MambularClassifier(
+    d_model=128,
+    n_layers=4,
+    numerical_preprocessing="ple",
+    lr=1e-3,
+)
+```
+
+```python
+# v2: options grouped by concern
+from deeptab.models import MambularClassifier
+from deeptab.configs import MambularConfig, PreprocessingConfig, TrainerConfig
+
+model = MambularClassifier(
+    model_config=MambularConfig(d_model=128, n_layers=4),
+    preprocessing_config=PreprocessingConfig(numerical_preprocessing="ple"),
+    trainer_config=TrainerConfig(lr=1e-3),
+)
+```
+
+```{tip}
+Each option moves to the config that owns its concern: architecture fields go to the model config, anything passed to `pretab.Preprocessor` goes to `PreprocessingConfig`, and training or optimizer fields go to `TrainerConfig`. The tables further down list which fields belong where.
+```
+
 ### Where to find every field
 
 Each config has a complete, authoritative field reference. Use the table below as the index.
diff --git a/docs/homepage.md b/docs/homepage.md
@@ -15,7 +15,7 @@ probabilities = model.predict_proba(X_test)
 ## Why DeepTab
 
 - **Familiar interface.** A scikit-learn `fit`/`predict`/`evaluate` API that drops into existing pipelines, including `GridSearchCV`.
-- **Automatic preprocessing.** Feature-type detection, encoding, scaling, and missing-value handling are built in.
+- **Automatic preprocessing.** Feature-type detection, encoding, scaling, and missing-value handling are powered by [PreTab](https://github.com/OpenTabular/PreTab) and applied for you.
 - **One model, three tasks.** Every architecture ships as a classifier, a regressor, and a distributional (`LSS`) variant for uncertainty quantification.
 - **A broad model zoo.** 15 stable architectures plus experimental models, all behind the same interface, with [selection guidance](model_zoo/comparison_tables).
 - **Built for real data.** Mixed feature types, class imbalance, GPU acceleration, and early stopping work out of the box.
@@ -30,7 +30,7 @@ DeepTab requires Python 3.10+ and installs PyTorch automatically. See [Installat
 
 ## What's New in v2.0
 
-v2.0 is a ground-up restructuring of DeepTab. The high-level estimator API stays familiar, while the package layout, configuration objects, and import paths have moved.
+v2.0 is a ground-up restructuring of DeepTab. The high-level estimator API stays familiar, while the package layout, configuration objects, and import paths have been updated.
 
 - **Split-config API**: separate model, preprocessing, and training configuration objects, so each concern can be tuned on its own. This is the first thing you reach for in v2.
 - **New models**: AutoInt, ENODE, and TabR (stable); Tangos, Trompt, and ModernNCA (experimental).
@@ -44,7 +44,49 @@ v2.0 is a ground-up restructuring of DeepTab. The high-level estimator API stays
 - **Rebuilt docs and tutorials**: refreshed guides plus end-to-end, Colab-ready tutorials for [classification](tutorials/imbalance_classification), [regression](tutorials/skewed_regression), and [uncertainty quantification](tutorials/uncertainty_quantification).
 
 ```{warning}
-Upgrading from v1 requires changes. Packages were reorganised, the `Default<Arch>Config` classes were renamed to `<Arch>Config`, and the data modules became `TabularDataModule` / `TabularDataset`. See the [FAQ](getting_started/faq) for v1 support and upgrade notes.
+**v2.0 is not backward compatible with v1, and v1 is no longer maintained.** Three
+things changed that affect existing code:
+
+1. **Import paths** were reorganised under the `deeptab` namespace.
+2. **Config classes** lost their `Default` prefix, so `DefaultMambularConfig` is now
+   `MambularConfig`. Settings are also split across `MambularConfig` (architecture),
+   `PreprocessingConfig` (feature handling), and `TrainerConfig` (optimisation).
+3. **Data modules** were renamed to `TabularDataModule` and `TabularDataset`; the old
+   `Mambular*` aliases are deprecated.
+
+If you need to stay on v1 for now, pin `deeptab<2.0`. Note that the v1 branch receives
+no bug fixes or security updates. See the [FAQ](getting_started/faq) for the full
+support policy and migration notes.
+```
+
+The high-level `fit`/`predict`/`evaluate` workflow is unchanged. In most cases only
+the imports and config construction need updating:
+
+```python
+# v1: settings passed as flat keyword arguments on the estimator
+from deeptab.models import MambularClassifier
+
+model = MambularClassifier(d_model=128, n_layers=4, numerical_preprocessing="ple")
+model.fit(X_train, y_train, max_epochs=50)
+```
+
+```python
+# v2: settings grouped into focused config objects
+from deeptab.models import MambularClassifier
+from deeptab.configs import MambularConfig, PreprocessingConfig
+
+model = MambularClassifier(
+    model_config=MambularConfig(d_model=128, n_layers=4),          # architecture
+    preprocessing_config=PreprocessingConfig(numerical_preprocessing="ple"),  # features
+)
+model.fit(X_train, y_train, max_epochs=50)
+```
+
+```{note}
+You only pass the configs you want to customise. `MambularClassifier()` with no
+arguments uses sensible defaults for the architecture, preprocessing, and training.
+The flat keyword-argument style from v1 is no longer accepted, so settings must go
+through the relevant config object.
 ```
 
 See the [Overview](getting_started/overview) for the full picture.
@@ -59,61 +101,18 @@ Each architecture comes in three variants, `*Classifier`, `*Regressor`, and `*LS
 
 ## Documentation
 
-### Getting Started
-
-- [Overview](getting_started/overview): What DeepTab is and when to use it
-- [Installation](getting_started/installation): Setup, GPU support, and optional kernels
-- [Quickstart](getting_started/quickstart): Train your first models in a few minutes
-- [FAQ](getting_started/faq): Common questions and troubleshooting
-
-### Core Concepts
-
-- [sklearn API](core_concepts/sklearn_api): The fit/predict/evaluate interface
-- [Model Tiers](core_concepts/model_tiers): Stable versus experimental models
-- [Config System](core_concepts/config_system): Split configuration for model, preprocessing, and training
-- [Training and Evaluation](core_concepts/training_and_evaluation): The fit pipeline, metrics, and reproducibility
-- [Observability](core_concepts/observability): Lifecycle events, structured logging, and experiment tracking
-- [Model Operations](core_concepts/model_operations): Serialisation and inspection
-- [Inference](core_concepts/inference): Deployment-safe prediction with `InferenceModel`
-
-### Tutorials
-
-- [Imbalanced Classification](tutorials/imbalance_classification): An end-to-end classification workflow
-- [Skewed-Target Regression](tutorials/skewed_regression): Regression on a right-skewed target
-- [Uncertainty Quantification](tutorials/uncertainty_quantification): Prediction intervals with LSS models
-- [Hyperparameter Optimisation](tutorials/hpo): Tuning models efficiently
-- [Advanced Training and Inference](tutorials/advanced_training): Optimizers, schedulers, and production inference
-- [Observability and Logging](tutorials/observability): Run directories and experiment trackers
-- [Model Efficiency](tutorials/model_efficiency): Runtime and memory benchmarking
-- [Experimental Models](tutorials/experimental): Working with cutting-edge architectures
-
-### Model Zoo
-
-- [Comparison Tables](model_zoo/comparison_tables): Selection guidance and performance across dimensions
-- [Stable Models](model_zoo/stable/index): Production-ready architectures
-- [Experimental Models](model_zoo/experimental/index): Models under evaluation
-- [Efficiency and Benchmarking](model_zoo/efficiency): Runtime and memory guidance
-- [Recommended Configs](model_zoo/recommended_configs): Hyperparameter recipes
-
-### API Reference
-
-- [Models](api/models/index): Classifier, Regressor, and LSS classes
-- [Configs](api/configs/index): Configuration dataclasses
-- [Data](api/data/index): Datasets, data modules, and schemas
-- [Distributions](api/distributions/index): LSS distribution families
-- [Metrics](api/metrics/index): Task-aware metric classes
-- [Training](api/training/index): Lightning modules for advanced use
-
-### Developer Guide
-
-- [Contributing](developer_guide/contributing): How to contribute
-- [Testing](developer_guide/testing): Test suite and coverage
-- [Documentation](developer_guide/documentation): Building the docs locally
-- [Versioning](developer_guide/versioning): Semantic versioning policy
-- [CI/CD](developer_guide/ci_cd): Continuous integration
-- [Release Process](developer_guide/release): Release workflow
-- [Model Promotion Policy](developer_guide/model_promotion_policy): From experimental to stable
-- [Support Matrix](developer_guide/support_matrix): Supported Python and PyTorch versions
+```{note}
+These are starting points for each area. The sidebar navigation is the source of
+truth, so please review the individual documentation sections for the latest
+updates and further documentation.
+```
+
+- **Getting Started**: Begin with the [Overview](getting_started/overview) and [Quickstart](getting_started/quickstart), then see [Installation](getting_started/installation) for GPU setup.
+- **Core Concepts**: How DeepTab works, including the [sklearn API](core_concepts/sklearn_api), the [Config System](core_concepts/config_system), and [Training and Evaluation](core_concepts/training_and_evaluation).
+- **Tutorials**: End-to-end, Colab-ready walkthroughs for [regression](tutorials/skewed_regression), [classification](tutorials/imbalance_classification), and [uncertainty quantification](tutorials/uncertainty_quantification).
+- **Model Zoo**: Browse the [Stable Models](model_zoo/stable/index) and [Experimental Models](model_zoo/experimental/index), or use the [Comparison Tables](model_zoo/comparison_tables) for selection guidance.
+- **API Reference**: Full reference for [Models](api/models/index), [Configs](api/configs/index), and the rest of the public API.
+- **Developer Guide**: [Contributing](developer_guide/contributing), [Testing](developer_guide/testing), and the [Release Process](developer_guide/release) for maintainers.
 
 ---
 
