Merge pull request #59 from magcil/58-add-architecture-info-on-audioclassifier-and-backbones-and-expose-available-backbones-and-pooling-methods

58 add architecture info on audioclassifier and backbones and expose available backbones and pooling methods

Author: ChrisNick92

CONTRIBUTING.md

@@ -12,6 +12,24 @@ We welcome contributions of all kinds. If you want to improve DeepAudioX, there
   `deepaudiox.modules.pooling`.
 - **Improve the library**: Optimize performance, fix bugs, enhance documentation, or add tests.
 
+## Development Setup
+
+Clone the repository and install all dependencies (including dev tools) using `uv`:
+
+```bash
+git clone https://github.com/magcil/deepaudio-x.git
+cd deepaudio-x
+uv sync
+```
+
+This installs the package in editable mode along with `pytest` and `ruff`.
+
+## Running Tests
+
+```bash
+uv run pytest -v
+```
+
 ## General Guidelines
 
 1. Open an issue to discuss major changes before submitting a pull request.

README.md

@@ -5,6 +5,7 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/deepaudio-x.svg?cacheSeconds=300)](https://pypi.org/project/deepaudio-x/)
 [![License](https://img.shields.io/github/license/magcil/deepaudio-x.svg)](https://github.com/magcil/deepaudio-x/blob/main/LICENSE)
 [![Run Tests](https://github.com/magcil/deepaudio-x/actions/workflows/tests.yml/badge.svg)](https://github.com/magcil/deepaudio-x/actions/workflows/tests.yml)
+[![Publish to PyPI](https://github.com/magcil/deepaudio-x/actions/workflows/publish.yml/badge.svg)](https://github.com/magcil/deepaudio-x/actions/workflows/publish.yml)
 
 
 <p align="left">
@@ -93,7 +94,7 @@ You can load the dataset as follows:
 
 ```python
 from deepaudiox import audio_classification_dataset_from_dir
-from deepaudiox.utils.training_utils import get_class_mapping_from_dir
+from deepaudiox import get_class_mapping_from_dir
 
 # Define a class mapping
 class_mapping = get_class_mapping_from_dir(root_dir="path/to/data")
@@ -334,6 +335,13 @@ trainer = Trainer(
 trainer.train()
 ```
 
+> **Note:** The checkpoint saved at `path_to_checkpoint` contains both the model weights and the architecture config (backbone, pooling, num_classes, etc.). You can restore the full model in one line:
+> ```python
+> from deepaudiox import AudioClassifier
+> model = AudioClassifier.from_checkpoint("checkpoint.pt")
+> print(model.config)  # {"backbone": "beats", "pooling": "gap", ...}
+> ```
+
 ### Trainer Parameters
 
 - `train_dset`: Training dataset (AudioClassificationDataset)
@@ -359,9 +367,10 @@ trainer.train()
 Evaluate your trained classifier on a test dataset using the `Evaluator` class:
 
 ```python
-import torch
+from deepaudiox import AudioClassifier, Evaluator
 
-from deepaudiox import Evaluator
+# Load model with architecture and weights restored from checkpoint
+classifier = AudioClassifier.from_checkpoint("checkpoint.pt")
 
 # Initialize evaluator
 evaluator = Evaluator(
@@ -372,8 +381,6 @@ evaluator = Evaluator(
     num_workers=4
 )
 
-# Load model
-classifier.load_state_dict(torch.load("checkpoint.pt"))
 
 # Run evaluation
 evaluator.evaluate()
@@ -494,13 +501,6 @@ The library is designed to scale from quick experiments to research and producti
 
 ---
 
-## Project Status
-
-🚧 This project is under active development.
-
-APIs may evolve, but backward compatibility will be considered once a stable release is reached.
-
----
 
 ## Attribution
 
@@ -529,8 +529,6 @@ If you use this library in academic work, please cite:
 
 ## Contributing
 
-Contributions are welcome!
-
-Please open an issue to discuss major changes before submitting a pull request.
+Contributions are welcome! Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to set up the development environment, run tests, and submit changes.
 
 ---

docs/source/about.rst

@@ -40,11 +40,9 @@ audio classifier:
 
 .. code-block:: python
 
-   import torch
-
    from deepaudiox import AudioClassifier, Evaluator, Trainer
    from deepaudiox import audio_classification_dataset_from_dir
-   from deepaudiox.utils.training_utils import get_class_mapping_from_dir
+   from deepaudiox import get_class_mapping_from_dir
 
    # 1) Build a dataset from a folder structure of class subdirectories
    class_mapping = get_class_mapping_from_dir(root_dir="path/to/data")
@@ -74,7 +72,7 @@ audio classifier:
 
    trainer.train()
 
-   classifier.load_state_dict(torch.load("checkpoint.pt"))  # Load model
+   classifier = AudioClassifier.from_checkpoint("checkpoint.pt")  # Load model with config restored
 
    # 4) Evaluate on a test set
    evaluator = Evaluator(
@@ -85,52 +83,3 @@ audio classifier:
 
    evaluator.evaluate()
 
-Supported backbones & pooling
------------------------------
-
-DeepAudio-X supports the following backbones and pooling methods:
-
-Backbones
-~~~~~~~~~
-
-.. list-table::
-   :header-rows: 1
-   :widths: 15 35 50
-
-   * - Name
-     - Description
-     - Notes
-   * - beats
-     - BEATs backbone
-     - Transformer pretrained on AudioSet
-   * - passt
-     - PaSST backbone
-     - Transformer pretrained on AudioSet
-
-Pooling
-~~~~~~~
-
-.. list-table::
-   :header-rows: 1
-   :widths: 15 35 50
-
-   * - Name
-     - Description
-     - Notes
-   * - gap
-     - Global Average Pooling
-     - Fast baseline
-   * - simpool
-     - Simple Pooling
-     - Strong attentive pooling
-   * - ep
-     - Efficient Probing
-     - Efficient attention pooling
-
-References
-----------
-
-- BEATs: `Audio Pre-Training with Acoustic Tokenizers <https://arxiv.org/abs/2212.09058>`_
-- PaSST: `Efficient Training of Audio Transformers with Patchout <https://arxiv.org/abs/2110.05069>`_
-- SimPool: `Keep It SimPool: Who Said Supervised Transformers Suffer from Attention Deficit? <https://arxiv.org/abs/2309.06891>`_
-- EP: `Attention, Please! Revisiting Attentive Probing Through the Lens of Efficiency <https://arxiv.org/abs/2506.10178>`_

docs/source/api-reference.rst

@@ -24,29 +24,46 @@ Methods for building datasets and class mappings from directories or label lists
 Models & Backbones
 ------------------
 
-Constructors and registries for initializing classifiers, backbones, and pooling.
+Constructors for initializing classifiers and backbones.
 
-.. autoclass:: AudioClassifierConstructor
+.. autoclass:: deepaudiox.modules.constructors.AudioClassifierConstructor
    :members:
-   :exclude-members: __init__
+   :special-members: __init__
    :undoc-members:
 
-.. autoclass:: BackboneConstructor
+   .. note:: Available as ``deepaudiox.AudioClassifier``.
+
+.. autoclass:: deepaudiox.modules.constructors.BackboneConstructor
    :members:
-   :exclude-members: __init__
+   :special-members: __init__
    :undoc-members:
 
-.. data:: BACKBONES
-   :annotation: = dict
+   .. note:: Available as ``deepaudiox.Backbone``.
+
+Supported Backbones & Pooling
+-----------------------------
+
+Type aliases and runtime constants for valid backbone and pooling names.
+
+.. data:: AVAILABLE_BACKBONES
+   :annotation: = ("beats", "passt", "mobilenet_05_as", "mobilenet_10_as", "mobilenet_40_as")
 
-.. data:: POOLING
-   :annotation: = dict
+   Supported pretrained backbone names available at runtime.
 
-.. autoclass:: AudioClassifier
-   :noindex:
+.. data:: AVAILABLE_POOLING
+   :annotation: = ("gap", "simpool", "ep")
 
-.. autoclass:: Backbone
-   :noindex:
+   Supported pooling layer names available at runtime.
+
+.. data:: BackboneName
+
+   Type alias: ``Literal["beats", "passt", "mobilenet_05_as", "mobilenet_10_as", "mobilenet_40_as"]``.
+   Use for type-annotated code.
+
+.. data:: PoolingName
+
+   Type alias: ``Literal["gap", "simpool", "ep"]``.
+   Use for type-annotated code.
 
 Training & Evaluation
 ---------------------
@@ -55,12 +72,12 @@ Interfaces for training models and evaluating performance on held-out data.
 
 .. autoclass:: Trainer
    :members:
-   :exclude-members: __init__
+   :special-members: __init__
    :undoc-members:
 
 .. autoclass:: Evaluator
    :members:
-   :exclude-members: __init__
+   :special-members: __init__
    :undoc-members:
 
 Base Classes & Inference
@@ -78,15 +95,15 @@ Full Paths
 The API re-exports the following symbols. If you prefer importing from the original modules, use these paths:
 
 - ``AudioClassifier`` -> ``deepaudiox.modules.constructors.AudioClassifierConstructor``
-- ``AudioClassifierConstructor`` -> ``deepaudiox.modules.constructors.AudioClassifierConstructor``
 - ``Backbone`` -> ``deepaudiox.modules.constructors.BackboneConstructor``
-- ``BackboneConstructor`` -> ``deepaudiox.modules.constructors.BackboneConstructor``
 - ``AudioClassificationDataset`` -> ``deepaudiox.datasets.audio_classification_dataset.AudioClassificationDataset``
 - ``audio_classification_dataset_from_dir`` -> ``deepaudiox.datasets.audio_classification_dataset.audio_classification_dataset_from_dir``
 - ``audio_classification_dataset_from_dictionary`` -> ``deepaudiox.datasets.audio_classification_dataset.audio_classification_dataset_from_dictionary``
 - ``get_class_mapping_from_dir`` -> ``deepaudiox.utils.training_utils.get_class_mapping_from_dir``
 - ``get_class_mapping_from_list`` -> ``deepaudiox.utils.training_utils.get_class_mapping_from_list``
 - ``Trainer`` -> ``deepaudiox.loops.trainer.Trainer``
 - ``Evaluator`` -> ``deepaudiox.loops.evaluator.Evaluator``
-- ``BACKBONES`` -> ``deepaudiox.modules.backbones.BACKBONES``
-- ``POOLING`` -> ``deepaudiox.modules.pooling.POOLING``
+- ``BackboneName`` -> ``deepaudiox.schemas.types.BackboneName``
+- ``PoolingName`` -> ``deepaudiox.schemas.types.PoolingName``
+- ``AVAILABLE_BACKBONES`` -> ``deepaudiox.__init__.AVAILABLE_BACKBONES``
+- ``AVAILABLE_POOLING`` -> ``deepaudiox.__init__.AVAILABLE_POOLING``

docs/source/contributing.rst

@@ -14,6 +14,26 @@ How You Can Contribute
   ``deepaudiox.modules.pooling``.
 - **Improve the library**: Optimize performance, fix bugs, enhance documentation, or add tests.
 
+Development Setup
+-----------------
+
+Clone the repository and install all dependencies (including dev tools) using `uv`:
+
+.. code-block:: bash
+
+   git clone https://github.com/magcil/deepaudio-x.git
+   cd deepaudio-x
+   uv sync
+
+This installs the package in editable mode along with ``pytest`` and ``ruff``.
+
+Running Tests
+-------------
+
+.. code-block:: bash
+
+   uv run pytest -v
+
 General Guidelines
 ------------------
 

docs/source/index.rst

@@ -17,6 +17,10 @@ DeepAudio-X
    :target: https://github.com/magcil/deepaudio-x/actions/workflows/tests.yml
    :alt: Tests
 
+.. image:: https://github.com/magcil/deepaudio-x/actions/workflows/publish.yml/badge.svg
+   :target: https://github.com/magcil/deepaudio-x/actions/workflows/publish.yml
+   :alt: Publish
+
 DeepAudio-X is a self-supervised audio toolkit for audio classification and related
 tasks.
 

docs/source/installation.rst

@@ -6,33 +6,62 @@ This section provides instructions on how to install DeepAudio-X.
 Requirements
 ------------
 
-DeepAudio-X requires Python 3.11, 3.12 or 3.13. It is recommended to use a virtual environment. For example, you can use miniconda or venv.
+DeepAudio-X requires Python 3.11, 3.12 or 3.13. It is recommended to use a virtual environment.
 
-Example with venv:
+With venv:
 
 .. code-block:: bash
 
    python3 -m venv deepaudiox-env
    source deepaudiox-env/bin/activate  # On Windows use `deepaudiox-env\Scripts\activate`
 
-Or with miniconda:
+With miniconda:
 
 .. code-block:: bash
 
    conda create -n deepaudiox-env python=3.13
    conda activate deepaudiox-env
 
+With `uv <https://docs.astral.sh/uv/getting-started/installation/>`_ (recommended):
+
+.. code-block:: bash
+
+   uv venv --python 3.13
+   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+
 PyPI
 ----
 
-DeepAudio-X is available on PyPI and can be installed with pip:
+DeepAudio-X is available on PyPI. Install with pip:
 
 .. code-block:: bash
 
    pip install deepaudio-x
 
+Or with uv:
+
+.. code-block:: bash
+
+   uv pip install deepaudio-x
+
+.. note::
+
+   The PyTorch version pulled from PyPI may require a newer NVIDIA driver than
+   what is installed on your system. After installation, verify that CUDA is available:
+
+   .. code-block:: python
+
+      import torch
+      print(torch.cuda.is_available())   # True if GPU is available
+      print(torch.version.cuda)          # CUDA version PyTorch was built for
+
+   If ``False`` is returned, either update your driver from
+   `nvidia.com <https://www.nvidia.com/Download/index.aspx>`_ or downgrade PyTorch
+   to a version compatible with your driver. See
+   `pytorch.org <https://pytorch.org/get-started/locally/>`_ to find the right build.
+
 Source
------------------------------------------
+------
 
 If you want a pre-release version, clone the repo and use `uv sync` to install
 dependencies from `pyproject.toml` and `uv.lock`. For installing uv itself, see
@@ -43,3 +72,9 @@ the `uv installation guide <https://docs.astral.sh/uv/getting-started/installati
    git clone https://github.com/magcil/deepaudio-x.git
    cd deepaudio-x
    uv sync
+
+Verify the installation:
+
+.. code-block:: bash
+
+   python -c "import deepaudiox; print(deepaudiox.__version__)"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepaudio-x"
-version = "0.4.1"
+version = "0.4.2"
 description = "DeepAudio-X: Self-supervised audio toolkit for audio classification and beyond."
 authors = [
   { name = "Christos Nikou", email = "[email protected]" },