SonanceAI · luandalmazo · Jul 6, 2026 · Jul 6, 2026
diff --git a/README.md b/README.md
@@ -97,15 +97,21 @@ results = trainer.fit()
 
 ## 📚 Documentation
 
-| Resource | Description |
-|----------|-------------|
-| [🚀 Getting Started](https://sonanceai.github.io/datamint-python-api/getting_started.html) | Step-by-step setup and basic usage |
-| [📖 API Reference](https://sonanceai.github.io/datamint-python-api/client_api.html) | Complete API documentation |
-| [🔥 PyTorch Integration](https://sonanceai.github.io/datamint-python-api/pytorch_integration.html) | ML workflow integration |
-| [🧠 Trainer Guide](https://sonanceai.github.io/datamint-python-api/trainer_api.html) | Built-in trainers, trainer lifecycle, and custom model integration |
-| [🛠️ Command Line Tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html) | Full reference for `datamint upload`, `datamint init`, and `datamint config` |
-| [🔒 SSL Troubleshooting](https://sonanceai.github.io/datamint-python-api/ssl_troubleshooting.html) | Fixing `SSLCertVerificationError` |
-| [📓 Notebooks](notebooks/) | Numbered, runnable tutorials. Start at `01_getting_started` and work through annotations, datasets, experiment tracking, deployment, and a full end-to-end example |
+**Difficulty levels:**
+
+- ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) no ML knowledge needed 
+- ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow)assumes SDK familiarity, introduces ML/dataset concepts
+- ![Advanced](https://img.shields.io/badge/level-advanced-red) full training pipelines, custom models, 3D data, multi-step workflows.
+
+| Resource | Level | Description |
+|----------|-------|-------------|
+| [🚀 Getting Started](https://sonanceai.github.io/datamint-python-api/getting_started.html) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Step-by-step setup and basic usage |
+| [📖 API Reference](https://sonanceai.github.io/datamint-python-api/client_api.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Complete API documentation |
+| [🔥 PyTorch Integration](https://sonanceai.github.io/datamint-python-api/pytorch_integration.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | ML workflow integration |
+| [🧠 Trainer Guide](https://sonanceai.github.io/datamint-python-api/trainer_api.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Built-in trainers, trainer lifecycle, and custom model integration |
+| [🛠️ Command Line Tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Full reference for `datamint upload`, `datamint init`, and `datamint config` |
+| [🔒 SSL Troubleshooting](https://sonanceai.github.io/datamint-python-api/ssl_troubleshooting.html) | — | Fixing `SSLCertVerificationError` |
+| [📓 Notebooks](notebooks/) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) ![Advanced](https://img.shields.io/badge/level-advanced-red) | Numbered, runnable tutorials. Start at `01_getting_started` and work through annotations, datasets, experiment tracking, deployment, and a full end-to-end example |
 
 ## 🆘 Support
 

diff --git a/docs/source/client_api.rst b/docs/source/client_api.rst
@@ -2,6 +2,9 @@
 
 Client Python API
 =================
+
+:bdg-warning:`Intermediate`
+
 This chapter describes how to use the |ApiClass| class in Python,
 to interact with the Datamint API.
 Before continuing, you may want to check the :ref:`setup-api-key` section to easily set up your API key, if you haven't done so yet.

diff --git a/docs/source/command_line_tools.rst b/docs/source/command_line_tools.rst
@@ -3,6 +3,8 @@
 Command-line tools
 ==================
 
+:bdg-success:`Beginner`
+
 All Datamint command-line tools are invoked through a single ``datamint`` command, followed
 by a subcommand and its arguments — the same ``tool <command> ARGS`` pattern used by tools
 like ``docker``, ``git``, and ``pip``:

diff --git a/docs/source/datamint_vs_raw_pytorch.rst b/docs/source/datamint_vs_raw_pytorch.rst
@@ -1,6 +1,8 @@
 Datamint vs Raw PyTorch
 =======================
 
+:bdg-danger:`Advanced`
+
 This page shows how Datamint removes boilerplate from common medical-imaging
 training workflows by comparing side-by-side a raw PyTorch / Lightning setup
 with the equivalent Datamint code.  All examples target **2-D semantic

diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -1,6 +1,8 @@
 Quick Start
 =========================================
 
+:bdg-success:`Beginner`
+
 This guide will help you set up and start using the Datamint Python API for your medical imaging projects.
 
 Installation

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -21,9 +21,82 @@ Datamint
 - `Datamint Platform <https://app.datamint.io/>`_
 - `GitHub <https://github.com/SonanceAI/datamint-python-api>`_
 
+**Difficulty levels:**
+
+- :bdg-success:`Beginner` no ML knowledge needed
+- :bdg-warning:`Intermediate` assumes SDK familiarity, introduces ML/dataset concepts
+- :bdg-danger:`Advanced` full training pipelines, custom models, 3D data, multi-step workflows
+
+User Guide
+----------
+
+.. grid:: 1 2 3 3
+   :gutter: 2
+
+   .. grid-item-card:: Quick Start
+      :link: getting_started
+      :link-type: doc
+
+      :bdg-success:`Beginner`
+
+      Install the package, configure your API key, and make your first calls.
+
+   .. grid-item-card:: Command-line tools
+      :link: command_line_tools
+      :link-type: doc
+
+      :bdg-success:`Beginner`
+
+      Run the unified ``datamint <command>`` CLI for uploads, config, training, and inference.
+
+   .. grid-item-card:: Client Python API
+      :link: client_api
+      :link-type: doc
+
+      :bdg-warning:`Intermediate`
+
+      Use the ``Api`` class directly for full control over resources, projects, and annotations.
+
+   .. grid-item-card:: PyTorch & Lightning Integration
+      :link: pytorch_integration
+      :link-type: doc
+
+      :bdg-warning:`Intermediate`
+
+      Plug Datamint datasets into PyTorch and Lightning training loops.
+
+   .. grid-item-card:: Training your Model
+      :link: trainer_api
+      :link-type: doc
+
+      :bdg-warning:`Intermediate`
+
+      Train models with built-in one-line trainers -- no training loop to write.
+
+   .. grid-item-card:: Tutorials
+      :link: tutorials
+      :link-type: doc
+
+      Browse runnable example notebooks, from getting started through full end-to-end pipelines.
+
+   .. grid-item-card:: Datamint vs Raw PyTorch
+      :link: datamint_vs_raw_pytorch
+      :link-type: doc
+
+      :bdg-danger:`Advanced`
+
+      Side-by-side comparison of raw PyTorch/Lightning code vs the Datamint equivalent.
+
+   .. grid-item-card:: SSL Troubleshooting
+      :link: ssl_troubleshooting
+      :link-type: doc
+
+      Fix ``SSLCertVerificationError`` issues when connecting to the API.
+
 .. toctree::
    :maxdepth: 2
    :caption: User Guide
+   :hidden:
 
    getting_started
    command_line_tools
@@ -34,49 +107,23 @@ Datamint
    datamint_vs_raw_pytorch
    ssl_troubleshooting
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Python Modules Reference
-
-   datamint.apihandler
-   datamint.api.base_classes
-   datamint.dataset
-   datamint.entities
-   datamint.lightning_api
-   datamint.mlflow_api
-   datamint.exceptions
-
 Quick Start
 -----------
 
-Install the package:
-
 .. code-block:: bash
 
    pip install datamint
-
-Configure your API access:
-
-.. code-block:: bash
-
    datamint config
 
-Start using the API:
-
 .. code-block:: python
 
    from datamint import Api
 
-   # Initialize API handler
    api = Api()
    all_projects = api.projects.get_all()
 
-   # Upload a resource
-   api.resources.upload_resource("/path/to/image.dcm")
-
-   # Load a dataset for training
-   from datamint.dataset import ImageDataset
-   dataset = ImageDataset(project="my-project")
+See the full :doc:`Quick Start guide <getting_started>` for installing in a virtual
+environment, configuring your API key, and scaffolding a project with ``datamint init``.
 
 Architecture Overview
 ---------------------
@@ -246,6 +293,18 @@ Community & Support
 
 `GitHub Issues <https://github.com/SonanceAI/datamint-python-api/issues>`_
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Python Modules Reference
+
+   datamint.apihandler
+   datamint.api.base_classes
+   datamint.dataset
+   datamint.entities
+   datamint.lightning_api
+   datamint.mlflow_api
+   datamint.exceptions
+
 Indices and Tables
 ------------------
 

diff --git a/docs/source/pytorch_integration.rst b/docs/source/pytorch_integration.rst
@@ -4,6 +4,8 @@
 PyTorch & Lightning Integration
 ===============================
 
+:bdg-warning:`Intermediate`
+
 The Datamint Python API provides seamless integration with PyTorch and PyTorch Lightning, enabling efficient machine learning workflows for medical imaging tasks.
 
 Overview

diff --git a/docs/source/trainer_api.rst b/docs/source/trainer_api.rst
@@ -4,6 +4,8 @@
 Training your Model
 ====================
 
+:bdg-warning:`Intermediate`
+
 The trainer layer in ``datamint.lightning`` packages the usual Lightning workflow into a
 small number of task-focused entry points. A trainer can:
 

diff --git a/notebooks/01_getting_started/README.md b/notebooks/01_getting_started/README.md
@@ -2,7 +2,7 @@
 
 Start here. These notebooks cover the basics of connecting to Datamint and working with your first project.
 
-| Notebook | Description |
-|---|---|
-| [01_upload_data](01_upload_data.ipynb) | Upload images, DICOM series, and NIfTI volumes to a project |
-| [02_explore_data](02_explore_data.ipynb) | List resources, inspect metadata, and browse annotations |
+| Notebook | Level | Description |
+|---|---|---|
+| [01_upload_data](01_upload_data.ipynb) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Upload images, DICOM series, and NIfTI volumes to a project |
+| [02_explore_data](02_explore_data.ipynb) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | List resources, inspect metadata, and browse annotations |
diff --git a/notebooks/02_annotations/README.md b/notebooks/02_annotations/README.md
@@ -2,7 +2,7 @@
 
 How to create, upload, and work with annotations programmatically.
 
-| Notebook | Description |
-|---|---|
-| [01_upload_annotations](01_upload_annotations.ipynb) | Upload segmentation masks and image-level labels via the API |
-| [02_geometry_annotations](02_geometry_annotations.ipynb) | Create and read bounding boxes, points, lines, and polygons |
+| Notebook | Level | Description |
+|---|---|---|
+| [01_upload_annotations](01_upload_annotations.ipynb) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Upload segmentation masks and image-level labels via the API |
+| [02_geometry_annotations](02_geometry_annotations.ipynb) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Create and read bounding boxes, points, lines, and polygons |
diff --git a/notebooks/03_datasets/README.md b/notebooks/03_datasets/README.md
@@ -2,9 +2,9 @@
 
 PyTorch dataset classes, data splits, and volume loading.
 
-| Notebook | Description |
-|---|---|
-| [01_project_scoped_splits](01_project_scoped_splits.ipynb) | Create reproducible train/val/test splits and persist them to the server |
-| [02_patient_wise_splits](02_patient_wise_splits.ipynb) | Patient-level splitting to prevent data leakage in multi-scan datasets |
-| [03_build_dataset](03_build_dataset.ipynb) | Use `build_dataset` to auto-detect project type and get the right dataset class |
-| [04_volume_dataset](04_volume_dataset.ipynb) | Load 3D volumes, slice along anatomical axes, and apply albumentations transforms |
+| Notebook | Level | Description |
+|---|---|---|
+| [01_project_scoped_splits](01_project_scoped_splits.ipynb) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Create reproducible train/val/test splits and persist them to the server |
+| [02_patient_wise_splits](02_patient_wise_splits.ipynb) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Patient-level splitting to prevent data leakage in multi-scan datasets |
+| [03_build_dataset](03_build_dataset.ipynb) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Use `build_dataset` to auto-detect project type and get the right dataset class |
+| [04_volume_dataset](04_volume_dataset.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Load 3D volumes, slice along anatomical axes, and apply albumentations transforms |
diff --git a/notebooks/04_experiment_tracking/README.md b/notebooks/04_experiment_tracking/README.md
@@ -2,6 +2,6 @@
 
 Logging experiments with MLflow through the Datamint backend.
 
-| Notebook | Description |
-|---|---|
-| [01_mlflow_manual_logging](01_mlflow_manual_logging.ipynb) | Log metrics, parameters, and model artifacts manually using `mlflow.set_tracking_uri("datamint://...")` |
+| Notebook | Level | Description |
+|---|---|---|
+| [01_mlflow_manual_logging](01_mlflow_manual_logging.ipynb) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Log metrics, parameters, and model artifacts manually using `mlflow.set_tracking_uri("datamint://...")` |
diff --git a/notebooks/05_deployment/README.md b/notebooks/05_deployment/README.md
@@ -2,9 +2,9 @@
 
 Deploying models as Docker images for remote inference.
 
-| Notebook | Description |
-|---|---|
-| [01_deploy_registered_model](01_deploy_registered_model.ipynb) | Start, monitor, and cancel deployment jobs for a model already registered in Datamint |
-| [02_deploy_external_model](02_deploy_external_model.ipynb) | Wrap a model trained outside Datamint in a `DatamintModel` adapter and deploy it |
-| [03_validate_model](03_validate_model.ipynb) | Validate a model before promoting it to production |
-| [04_predict_images_volumes_and_videos](04_predict_images_volumes_and_videos.ipynb) | Run a 2D model on images, 3D volumes, and video frames using automatic prediction bridges |
+| Notebook | Level | Description |
+|---|---|---|
+| [01_deploy_registered_model](01_deploy_registered_model.ipynb) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Start, monitor, and cancel deployment jobs for a model already registered in Datamint |
+| [02_deploy_external_model](02_deploy_external_model.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Wrap a model trained outside Datamint in a `DatamintModel` adapter and deploy it |
+| [03_validate_model](03_validate_model.ipynb) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Validate a model before promoting it to production |
+| [04_predict_images_volumes_and_videos](04_predict_images_volumes_and_videos.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Run a 2D model on images, 3D volumes, and video frames using automatic prediction bridges |
diff --git a/notebooks/06_end_to_end/README.md b/notebooks/06_end_to_end/README.md
@@ -6,17 +6,17 @@ Complete pipelines from raw data to a deployed model. Each notebook covers data
 
 Models that operate on individual 2D images or 2D slices extracted from volumes.
 
-| Notebook | Task | Dataset | Architecture |
-|---|---|---|---|
-| [01_fracatlas_classification](slice_based/01_fracatlas_classification.ipynb) | Binary classification | FracAtlas (X-rays) | ResNet |
-| [02_busi_segmentation](slice_based/02_busi_segmentation.ipynb) | Semantic segmentation | BUSI (ultrasound) | TransUNet |
-| [03_bccd_detection](slice_based/03_bccd_detection.ipynb) | Object detection | BCCD (blood cells) | YOLOX |
+| Notebook | Level | Task | Dataset | Architecture |
+|---|---|---|---|---|
+| [01_fracatlas_classification](slice_based/01_fracatlas_classification.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Binary classification | FracAtlas (X-rays) | ResNet |
+| [02_busi_segmentation](slice_based/02_busi_segmentation.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Semantic segmentation | BUSI (ultrasound) | TransUNet |
+| [03_bccd_detection](slice_based/03_bccd_detection.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Object detection | BCCD (blood cells) | YOLOX |
 
 ## Full 3D
 
 Models that consume entire volumetric inputs without slicing.
 
-| Notebook | Task | Dataset | Architecture |
-|---|---|---|---|
-| [01_synapse_unetrpp](full_3d/01_synapse_unetrpp.ipynb) | Multi-organ segmentation | Synapse CT | UNETR++ |
-| [02_synapse_nnunet](full_3d/02_synapse_nnunet.ipynb) | Multi-organ segmentation | Synapse CT | nnU-Net |
+| Notebook | Level | Task | Dataset | Architecture |
+|---|---|---|---|---|
+| [01_synapse_unetrpp](full_3d/01_synapse_unetrpp.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Multi-organ segmentation | Synapse CT | UNETR++ |
+| [02_synapse_nnunet](full_3d/02_synapse_nnunet.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Multi-organ segmentation | Synapse CT | nnU-Net |
diff --git a/notebooks/06_end_to_end/full_3d/README.md b/notebooks/06_end_to_end/full_3d/README.md
@@ -2,7 +2,7 @@
 
 End-to-end pipelines for models that process entire volumetric inputs.
 
-| Notebook | Task | Dataset |
-|---|---|---|
-| [01_synapse_unetrpp](01_synapse_unetrpp.ipynb) | Multi-organ segmentation | Synapse CT |
-| [02_synapse_nnunet](02_synapse_nnunet.ipynb) | Multi-organ segmentation | Synapse CT |
+| Notebook | Level | Task | Dataset |
+|---|---|---|---|
+| [01_synapse_unetrpp](01_synapse_unetrpp.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Multi-organ segmentation | Synapse CT |
+| [02_synapse_nnunet](02_synapse_nnunet.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Multi-organ segmentation | Synapse CT |
diff --git a/notebooks/06_end_to_end/slice_based/README.md b/notebooks/06_end_to_end/slice_based/README.md
@@ -2,8 +2,8 @@
 
 End-to-end pipelines for 2D models — classification, segmentation, and detection.
 
-| Notebook | Task | Dataset |
-|---|---|---|
-| [01_fracatlas_classification](01_fracatlas_classification.ipynb) | Fracture classification | FracAtlas |
-| [02_busi_segmentation](02_busi_segmentation.ipynb) | Breast lesion segmentation | BUSI |
-| [03_bccd_detection](03_bccd_detection.ipynb) | Blood cell detection | BCCD |
+| Notebook | Level | Task | Dataset |
+|---|---|---|---|
+| [01_fracatlas_classification](01_fracatlas_classification.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Fracture classification | FracAtlas |
+| [02_busi_segmentation](02_busi_segmentation.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Breast lesion segmentation | BUSI |
+| [03_bccd_detection](03_bccd_detection.ipynb) | ![Advanced](https://img.shields.io/badge/level-advanced-red) | Blood cell detection | BCCD |