feat!: DeepTab v2 API with split-config design (#400)

DeepTab v2 is a ground-up restructuring of the library. The high-level
estimator API (`MambularClassifier().fit(...)`) is largely unchanged, but
the internal package layout, configuration objects, and import paths have
moved.

## Highlights

- **Split-config API:** model behavior is now configured through separate
  `model_config`, `preprocessing_config`, `trainer_config`, and
  `observability_config` objects instead of a single monolithic config.
- **15 stable architectures** across five families: State Space Models
  (Mambular, MambaTab, MambAttention), Transformers (FTTransformer,
  TabTransformer, SAINT, AutoInt), Residual Networks (ResNet, TabR),
  Tree-Inspired (NODE, ENODE, NDTF), and general baselines (MLP, TabM,
  TabulaRNN), each as a Classifier, Regressor, or distributional (LSS) model.
- **3 experimental models** under evaluation: ModernNCA, Tangos, Trompt.
- **Reorganized package layout:** `deeptab.models`, `deeptab.architectures`,
  `deeptab.configs`, `deeptab.core`, `deeptab.training`, `deeptab.data`.

## Fixes

- ModernNCA now supports distributional (LSS) prediction by pooling
  candidate representations through the tabular head.
- Aligned ruff between CI and pre-commit to remove "passes locally, fails
  in CI" drift; declared the previously implicit `sphinxext-opengraph`
  docs dependency; regenerated `poetry.lock`.

## Docs & tests

- Standardized numpydoc docstrings across architectures, core, nn, and
  training modules.
- Added smoke coverage for all stable and experimental models.
- Verified and corrected the model comparison tables against source.

BREAKING CHANGE: internal package layout, configuration objects, and import
paths have changed. See the migration guide for details.

Author: mkumar73

.github/workflows/ci.yml

@@ -146,3 +146,84 @@ jobs:
 
       - name: Run unit tests
         run: poetry run pytest tests/ -v
+
+  smoke:
+    name: Smoke tests (Python 3.12, ubuntu)
+    runs-on: ubuntu-latest
+    needs: lint
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Configure Poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Cache virtualenv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-smoke-${{ runner.os }}-3.12-${{ hashFiles('poetry.lock') }}
+
+      - name: Install dependencies
+        run: poetry install
+
+      - name: Run smoke tests
+        run: poetry run pytest tests/ -v -m smoke --tb=short
+
+  coverage:
+    name: Coverage (stable modules)
+    runs-on: ubuntu-latest
+    needs: tests
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Poetry
+        run: pipx install poetry
+
+      - name: Configure Poetry
+        run: poetry config virtualenvs.in-project true
+
+      - name: Cache virtualenv
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-coverage-${{ runner.os }}-3.12-${{ hashFiles('poetry.lock') }}
+
+      - name: Install dependencies
+        run: poetry install
+
+      - name: Run tests with coverage
+        run: |
+          poetry run pytest tests/ \
+            --cov=deeptab \
+            --cov-branch \
+            --cov-report=term-missing \
+            --cov-report=xml:coverage.xml \
+            -q
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml
+          retention-days: 30
+
+      - name: Upload to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

.gitignore

@@ -168,12 +168,28 @@ dist/
 # logs and checkpoints
 examples/lightning_logs
 *.ckpt
-
+*.deeptab
+lightning_logs
+lightning_logs/*
+checkpoints
+checkpoints/*
+model_checkpoints
+model_checkpoints/*
+outputs
+outputs/*
+experiment_logs
+experiment_logs/*
+mlruns
+mlruns/*
+deeptab_runs
+deeptab_runs/*
+obs_runs
+obs_runs/*
+
+# Sphinx build artifacts
 docs/_build/doctrees/*
 docs/_build/html/*
 
+# dev files
 dev
 dev/*
-
-
-lightning_logs/*

README.md

@@ -1,10 +1,30 @@
-from . import base_models, data_utils, models, utils
+from . import configs, data, distributions, metrics, models
 from ._version import __version__
+from .core.exceptions import (
+    ConfigWarning,
+    DataWarning,
+    DeepTabError,
+    DeepTabWarning,
+    NotFittedError,
+    PerformanceWarning,
+)
+from .core.inference import InferenceModel
+from .core.reproducibility import seed_context, set_seed
 
 __all__ = [
+    "ConfigWarning",
+    "DataWarning",
+    "DeepTabError",
+    "DeepTabWarning",
+    "InferenceModel",
+    "NotFittedError",
+    "PerformanceWarning",
     "__version__",
-    "base_models",
-    "data_utils",
+    "configs",
+    "data",
+    "distributions",
+    "metrics",
     "models",
-    "utils",
+    "seed_context",
+    "set_seed",
 ]