Release v1.0.0: torch.export, new features, pyproject.toml, uv in Docker

Breaking changes:
- Minimum Python 3.10, PyTorch 2.0
- All models migrated from TorchScript (.pt) to torch.export (.pt2)
- path_image and tensor params deprecated in favor of image_source

New features:
- Selective predictor execution (include/exclude_predictors)
- Pre-cropped face input (skip_detector)
- Grayscale/RGBA auto-conversion to RGB
- Robust input routing (tensor, numpy, PIL, bytes, path)
- __call__ methods on FaceAnalyzer, BaseProcessor, BaseDownloader, BaseModel

Packaging & tooling:
- Migrated from setup.py to pyproject.toml (PEP 621)
- Docker dev/test images migrated from conda to uv
- Dev dependencies consolidated into pyproject.toml
- Production Docker images use uv as pip drop-in
- CI updated for Python 3.10-3.13, CUDA 12.4
- Google Colab notebook updated for v1.0.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: tomas-gajarsky

.github/workflows/auto-release.yml

@@ -4,7 +4,7 @@ on:
   push:
     branches: [ "main" ]
     paths:
-      - "version"
+      - "pyproject.toml"
 
 jobs:
   create-release:
@@ -23,7 +23,12 @@ jobs:
       - name: Read version
         id: version
         run: |
-          VERSION=$(cat ./version | tr -d '[:space:]')
+          VERSION=$(python3 -c "
+          import re
+          with open('pyproject.toml') as f:
+              match = re.search(r'^version\s*=\s*\"(.+?)\"', f.read(), re.MULTILINE)
+          print(match.group(1))
+          ")
           echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
           echo "TAG=v$VERSION" >> $GITHUB_OUTPUT
           echo "VERSION=$VERSION" >> $GITHUB_ENV
@@ -74,7 +79,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.12"
 
       - name: Install build dependencies
         run: |
@@ -100,7 +105,13 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set VERSION variable
-        run: echo "VERSION=$(cat ./version | tr -d '[:space:]')" >> $GITHUB_ENV
+        run: |
+          echo "VERSION=$(python3 -c "
+          import re
+          with open('pyproject.toml') as f:
+              match = re.search(r'^version\s*=\s*\"(.+?)\"', f.read(), re.MULTILINE)
+          print(match.group(1))
+          ")" >> $GITHUB_ENV
 
       - name: Login to Docker Hub
         env:

.github/workflows/lint.yml

@@ -12,20 +12,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9"]
+        python-version: ["3.12"]
 
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
     - name: Install development dependencies
       run: |
-          python -m pip install -r requirements.dev.txt
+        python -m pip install --upgrade pip
+        python -m pip install .[dev]
     - name: Lint with flake8
       run: |
         flake8 --config=.flake8

.github/workflows/python-package.yml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - uses: actions/checkout@v4

.github/workflows/release.yml

@@ -4,7 +4,7 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Release tag (e.g., v0.6.1). Defaults to version file."
+        description: "Release tag (e.g., v1.0.0). Defaults to pyproject.toml version."
         required: false
 
 jobs:
@@ -22,7 +22,12 @@ jobs:
           if [ -n "${{ github.event.inputs.tag }}" ]; then
             TAG="${{ github.event.inputs.tag }}"
           else
-            FILE_VERSION=$(cat ./version | tr -d '[:space:]')
+            FILE_VERSION=$(python3 -c "
+          import re
+          with open('pyproject.toml') as f:
+              match = re.search(r'^version\s*=\s*\"(.+?)\"', f.read(), re.MULTILINE)
+          print(match.group(1))
+          ")
             TAG="v$FILE_VERSION"
           fi
           VERSION="${TAG#v}"
@@ -39,7 +44,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.12"
 
       - name: Install build dependencies
         run: |

CHANGELOG.md

@@ -1,5 +1,45 @@
 # Change Log
 
+## 1.0.0
+
+Released on April 18, 2026.
+
+### Breaking Changes
+* Minimum Python version raised from 3.8 to 3.10
+* Minimum PyTorch version raised from 1.9 to 2.0
+* All models migrated from TorchScript (.pt) to torch.export (.pt2) format
+* `path_image` and `tensor` parameters in `FaceAnalyzer.run()` are deprecated in favor of `image_source`
+
+### Added
+* Selective predictor execution via `include_predictors` and `exclude_predictors` parameters in `FaceAnalyzer.run()`
+* Pre-cropped face input support via `skip_detector=True` parameter in `FaceAnalyzer.run()`
+* Grayscale image handling: automatic conversion of single-channel and RGBA inputs to RGB across all input paths
+* `__call__` methods on `FaceAnalyzer`, `BaseProcessor`, `BaseDownloader`, and `BaseModel` (delegates to `run()`)
+* Optional logger configuration: `FaceAnalyzer` falls back to `logging.getLogger("facetorch")` when no logger is configured
+* Robust input routing in `FaceAnalyzer.run()` — tensor, numpy array, PIL Image, bytes, and file path inputs work with any reader type
+* All .pt2 models uploaded to Hugging Face Hub with model cards
+* `uv.lock` for reproducible PyPI-based dependency resolution
+* `[tool.uv]` configuration in `pyproject.toml`
+
+### Changed
+* Migrated from `setup.py` + `version` file to `pyproject.toml` (PEP 621)
+* All model files migrated from TorchScript (.pt) to torch.export (.pt2) portable format with dynamic batch support
+* AU predictor model rewritten with timm Swin Transformer backbone for torch.export compatibility
+* Docker dev/test images migrated from conda/conda-lock to [uv](https://github.com/astral-sh/uv) for faster builds
+* Docker production images now use uv as a pip drop-in
+* Development dependencies consolidated from `requirements.dev.txt` into `pyproject.toml`
+* Docker base images updated to Python 3.12 and CUDA 12.4
+* CI test matrix updated to Python 3.10, 3.11, 3.12, 3.13
+* GPU environment updated from CUDA 11.2 to CUDA 12.1+
+* Development status classifier updated from Alpha to Production/Stable
+* Google Colab notebook updated to v1.0.0 (uses `image_source`, removes pinned torch versions)
+
+### Fixed
+* "File name too long" error when passing tensor/array to `FaceAnalyzer.run()` with `ImageReader`
+* AU predictor YAML indentation error in merged config files
+* Numpy array reader now handles (H, W) and (H, W, 1) grayscale arrays
+
+
 ## 0.6.2
 
 Released on April 17, 2026.
@@ -33,7 +73,7 @@ Released on April 14, 2026.
 ### Added
 * Unit tests for all post-processor tuple input handling
 * Version tag validation in release workflow
-* Auto-release workflow that creates GitHub Releases when version file changes on main
+* Auto-release workflow that creates GitHub Releases when version changes on main
 
 
 ## 0.6.0

MANIFEST.in

@@ -1,8 +1,8 @@
 include LICENSE
-include version
+include pyproject.toml
 include environment.yml
 recursive-include conf *
 recursive-include docs *
 include data/input*/*.jpg
 include data*/*.png
-include tests*/*.py
+include tests*/*.py

README.md

@@ -17,18 +17,25 @@
 [Docker Hub](https://hub.docker.com/repository/docker/tomasgajarsky/facetorch) [(GPU)](https://hub.docker.com/repository/docker/tomasgajarsky/facetorch-gpu)
 
 
-**Facetorch** is a Python library designed for facial detection and analysis, leveraging the power of deep neural networks. Its primary aim is to curate open-source face analysis models from the community, optimize them for high performance using TorchScript, and integrate them into a versatile face analysis toolkit. The library offers the following key features:
+**Facetorch** is a Python library designed for facial detection and analysis, leveraging the power of deep neural networks. Its primary aim is to curate open-source face analysis models from the community, package them as portable [torch.export](https://pytorch.org/docs/stable/export.html) models, and integrate them into a versatile face analysis toolkit. The library offers the following key features:
 
 1. **Customizable Configuration:** Easily configure your setup using [Hydra](https://hydra.cc/docs/intro/) and its powerful [OmegaConf](https://omegaconf.readthedocs.io/) capabilities.
 
-2. **Reproducible Environments:** Ensure reproducibility with tools like [conda-lock](https://github.com/conda-incubator/conda-lock) for dependency management and [Docker](https://docs.docker.com/get-docker/) for containerization.
+2. **Reproducible Environments:** Ensure reproducibility with [uv](https://github.com/astral-sh/uv) for fast Python package management, [conda-lock](https://github.com/conda-incubator/conda-lock) for conda-forge dependency management, and [Docker](https://docs.docker.com/get-docker/) for containerization.
 
-3. **Accelerated Performance:** Enjoy enhanced performance on both CPU and GPU with [TorchScript](https://pytorch.org/docs/stable/jit.html) optimization.
+3. **Portable Models:** Models are serialized with `torch.export` (`.pt2` format) — no model source code needed at inference time, with dynamic batch support and `torch.compile` compatibility.
 
-4. **Simple Extensibility:** Extend the library by uploading your model file to Hugging Face Hub (previously Google Drive) and adding a corresponding configuration YAML file to the repository.
+4. **Simple Extensibility:** Extend the library by uploading your model file to Hugging Face Hub and adding a corresponding configuration YAML file to the repository.
+
+5. **Flexible Input:** Accepts file paths, URLs, tensors, numpy arrays, PIL Images, and bytes. Grayscale and RGBA inputs are automatically converted to RGB.
 
 Facetorch provides an efficient, scalable, and user-friendly solution for facial analysis tasks, catering to developers and researchers looking for flexibility and performance.
 
+### Requirements
+
+* Python >= 3.10
+* PyTorch >= 2.0
+
 Please use this library responsibly and with caution. Adhere to the [European Commission's Ethics Guidelines for Trustworthy AI](https://ec.europa.eu/futurium/en/ai-alliance-consultation.1.html) to ensure ethical and fair usage. Keep in mind that the models may have limitations and potential biases, so it is crucial to evaluate their outputs critically and consider their impact.
 
 
@@ -58,6 +65,28 @@ Check *data/output* for resulting images with bounding boxes and facial 3D landm
 
 (Apple Mac M1) Use Rosetta 2 emulator in Docker Desktop to run the CPU version.
 
+### Python API
+
+```python
+from facetorch import FaceAnalyzer
+from omegaconf import OmegaConf
+
+cfg = OmegaConf.load("conf/config.yaml")
+analyzer = FaceAnalyzer(cfg.analyzer)
+
+# Analyze from file path, URL, tensor, numpy array, PIL Image, or bytes
+response = analyzer.run(image_source="path/to/image.jpg")
+
+# Run only specific predictors
+response = analyzer.run(image_source="image.jpg", include_predictors=["fer", "embed"])
+
+# Skip detector for pre-cropped face inputs
+response = analyzer.run(image_source=face_tensor, skip_detector=True)
+
+# FaceAnalyzer is also callable
+response = analyzer("image.jpg")
+```
+
 ### Configure
 
 The project is configured by files located in *conf* with the main file: *conf/config.yaml*. One can easily add or remove modules from the configuration.
@@ -157,7 +186,7 @@ analyzer
 1. CVI-SZU
     * code: [ME-GraphAU](https://github.com/CVI-SZU/ME-GraphAU)
     * paper: [Luo et al. - Learning Multi-dimensional Edge Feature-based AU Relation Graph for Facial Action Unit Recognition](https://arxiv.org/abs/2205.01782)
-    * ! Does not work with CUDA > 12.0
+    * Note: As of v1.0.0, the AU model uses torch.export format and works with all CUDA versions
 
 #### Facial Valence Arousal (va)
 
@@ -232,13 +261,22 @@ Run the Docker container:
 
 ### Add predictor
 #### Prerequisites
-1. File of the TorchScript model
-2. Repository on Hugging Face Hub for hosting the model (or legacy ID of the Google Drive model file)
+1. Exported `.pt2` model file (see below)
+2. Repository on Hugging Face Hub for hosting the model
 3. facetorch [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
 
-Facetorch works with models that were exported from PyTorch to TorchScript. You can apply [torch.jit.trace](https://pytorch.org/docs/stable/generated/torch.jit.trace.html) function to compile a PyTorch model as a TorchScript module. Please verify that the output of the traced model equals the output of the original model.
+Facetorch uses models exported with [torch.export](https://pytorch.org/docs/stable/export.html) (`.pt2` format). Export your model with dynamic batch support:
+
+```python
+import torch
 
-Models are now hosted on [Hugging Face Hub](https://huggingface.co/tomas-gajarsky) which is the default download source. You can host your model on your own Hugging Face account or use the legacy Google Drive hosting option by specifying the appropriate downloader in your configuration.
+model.eval()
+batch = torch.export.Dim("batch", min=1, max=64)
+ep = torch.export.export(model, (dummy_input,), dynamic_shapes={"x": {0: batch}})
+torch.export.save(ep, "model.pt2")
+```
+
+Verify that the exported model produces the same outputs as the original. Models are hosted on [Hugging Face Hub](https://huggingface.co/tomas-gajarsky).
 
 #### Configuration
 ##### Create yaml file
@@ -272,6 +310,13 @@ the requirements of the new model.
 
 
 ### Update environment
+
+#### uv (used by Docker dev/test images)
+* Add packages with corresponding versions to ```pyproject.toml``` dependencies
+* Lock the environment: ```uv lock```
+* Sync the environment: ```uv sync --extra dev```
+
+#### conda (for conda-forge users)
 CPU:
 * Add packages with corresponding versions to ```environment.yml``` file
 * Lock the environment: ```conda lock -p linux-64 -f environment.yml --lockfile conda-lock.yml```

conf/analyzer/detector/retinaface.yaml

@@ -4,9 +4,9 @@ _target_: facetorch.analyzer.detector.FaceDetector
 downloader:
   _target_: facetorch.downloader.DownloaderHuggingFace
   file_id: 1eMuOdGkiNCOUTiEbKKoPCHGCuDgiKeNC 
-  path_local: /opt/facetorch/models/torchscript/detector/1/model.pt # str
+  path_local: /opt/facetorch/models/exported/detector/1/model.pt2 # str
   repo_id: tomas-gajarsky/facetorch-detector-retinaface  # HuggingFace repo ID
-  filename: model.pt  # Filename in the HuggingFace repo
+  filename: model.pt2  # Filename in the HuggingFace repo
 
 device:
   _target_: torch.device

conf/analyzer/detector/retinaface_hf.yaml

@@ -4,9 +4,9 @@ _target_: facetorch.analyzer.detector.FaceDetector
 downloader:
   _target_: facetorch.downloader.DownloaderHuggingFace
   file_id: 1eMuOdGkiNCOUTiEbKKoPCHGCuDgiKeNC
-  path_local: /opt/facetorch/models/torchscript/detector/1/model.pt # str
+  path_local: /opt/facetorch/models/exported/detector/1/model.pt2 # str
   repo_id: tomas-gajarsky/facetorch-detector-retinaface  # HuggingFace repo ID
-  filename: model.pt  # Filename in the HuggingFace repo
+  filename: model.pt2  # Filename in the HuggingFace repo
 
 device:
   _target_: torch.device

conf/analyzer/predictor/align/synergy_mobilenet_v2.yaml

@@ -3,9 +3,9 @@ _target_: facetorch.analyzer.predictor.FacePredictor
 downloader:
   _target_: facetorch.downloader.DownloaderHuggingFace
   file_id: 16gNFQdEH2nWvW3zTbdIAniKIbPAp6qBA
-  path_local: /opt/facetorch/models/torchscript/predictor/align/1/model.pt # str
+  path_local: /opt/facetorch/models/exported/predictor/align/1/model.pt2 # str
   repo_id: tomas-gajarsky/facetorch-align-synergynet  # HuggingFace repo ID
-  filename: model.pt  # Filename in the HuggingFace repo
+  filename: model.pt2  # Filename in the HuggingFace repo
 
 device:
   _target_: torch.device