chore: Release v3.5.2

* fix: Fix installation conflict between onnxruntime and onnxruntime-gpu

* fix: Fix CI, notebooks, type hints, and packaging issues found in audit

* feat: Add new release config

* ci: Automate release pipeline and document release process

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Build
+name: CI
 
 on:
   push:
@@ -37,6 +37,8 @@ jobs:
             python-version: "3.10"
           - os: ubuntu-latest
             python-version: "3.11"
+          - os: ubuntu-latest
+            python-version: "3.12"
           - os: ubuntu-latest
             python-version: "3.13"
           - os: ubuntu-latest
@@ -59,7 +61,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install .[dev]
+          python -m pip install ".[cpu,dev]"
 
       - name: Check ONNX Runtime providers
         run: |

.github/workflows/docs.yml

@@ -1,9 +1,8 @@
-name: Deploy docs
+name: Deploy Documentation
 
 on:
-  push:
-    tags:
-      - "v*.*.*"
+  release:
+    types: [released]
   workflow_dispatch:
 
 permissions:
@@ -15,7 +14,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Fetch full history for git-committers and git-revision-date plugins
+          fetch-depth: 0
 
       - uses: actions/setup-python@v5
         with:

.github/workflows/pipeline.yml

@@ -0,0 +1,221 @@
+name: Release Pipeline
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version (e.g. 3.6.0, 3.6.0b1, 3.6.0rc1)'
+        required: true
+
+concurrency:
+  group: pipeline
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      is_prerelease: ${{ steps.prerelease.outputs.is_prerelease }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Validate version (PEP 440)
+        run: |
+          python - <<'EOF'
+          import re, sys
+          v = "${{ inputs.version }}"
+          if not re.fullmatch(r'\d+\.\d+\.\d+((a|b|rc)\d+|\.dev\d+)?', v):
+              print(f"Invalid version: {v}")
+              print("Expected forms: 3.6.0, 3.6.0a1, 3.6.0b1, 3.6.0rc1, 3.6.0.dev1")
+              sys.exit(1)
+          EOF
+
+      - name: Check tag does not exist
+        run: |
+          if git rev-parse "v${{ inputs.version }}" >/dev/null 2>&1; then
+            echo "Tag v${{ inputs.version }} already exists."
+            exit 1
+          fi
+
+      - name: Detect pre-release
+        id: prerelease
+        run: |
+          if [[ "${{ inputs.version }}" =~ (a|b|rc|\.dev)[0-9]+ ]]; then
+            echo "is_prerelease=true" >> $GITHUB_OUTPUT
+          else
+            echo "is_prerelease=false" >> $GITHUB_OUTPUT
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: validate
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[cpu,dev]"
+
+      - name: Run tests
+        run: pytest -v --tb=short
+
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    needs: test
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Update pyproject.toml
+        run: |
+          python - <<'EOF'
+          import re, pathlib
+          p = pathlib.Path('pyproject.toml')
+          text = p.read_text()
+          new = re.sub(r'^version\s*=\s*".*"', f'version = "${{ inputs.version }}"', text, count=1, flags=re.M)
+          if new == text:
+              raise SystemExit("Failed to update version in pyproject.toml")
+          p.write_text(new)
+          EOF
+
+      - name: Update uniface/__init__.py
+        run: |
+          python - <<'EOF'
+          import re, pathlib
+          p = pathlib.Path('uniface/__init__.py')
+          text = p.read_text()
+          new = re.sub(r"^__version__\s*=\s*'.*'", f"__version__ = '${{ inputs.version }}'", text, count=1, flags=re.M)
+          if new == text:
+              raise SystemExit("Failed to update __version__ in uniface/__init__.py")
+          p.write_text(new)
+          EOF
+
+      - name: Commit, tag, push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml uniface/__init__.py
+          git commit -m "chore: Release v${{ inputs.version }}"
+          git tag "v${{ inputs.version }}"
+          git push origin HEAD:${{ github.ref_name }}
+          git push origin "v${{ inputs.version }}"
+
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: [validate, release]
+    permissions:
+      contents: write
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/uniface/
+
+    steps:
+      - name: Checkout tag
+        uses: actions/checkout@v4
+        with:
+          ref: v${{ inputs.version }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: 'pip'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: v${{ inputs.version }}
+          files: dist/*
+          generate_release_notes: true
+          prerelease: ${{ needs.validate.outputs.is_prerelease }}
+
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: [validate, publish]
+    if: needs.validate.outputs.is_prerelease == 'false'
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout tag
+        uses: actions/checkout@v4
+        with:
+          ref: v${{ inputs.version }}
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material pymdown-extensions mkdocs-git-committers-plugin-2 mkdocs-git-revision-date-localized-plugin
+
+      - name: Build docs
+        env:
+          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.MKDOCS_GIT_COMMITTERS_APIKEY }}
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          destination_dir: docs

.github/workflows/publish.yml

@@ -3,7 +3,7 @@ name: Publish to PyPI
 on:
   push:
     tags:
-      - "v*.*.*"  # Trigger only on version tags like v0.1.9
+      - "v*.*.*"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -54,7 +54,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10", "3.11", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - name: Checkout code
@@ -69,7 +69,7 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          python -m pip install .[dev]
+          python -m pip install ".[cpu,dev]"
 
       - name: Run tests
         run: pytest -v
@@ -112,8 +112,19 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
         run: twine upload dist/*
 
+      - name: Detect pre-release
+        id: prerelease
+        run: |
+          if [[ "${{ needs.validate.outputs.version }}" =~ (a|b|rc|\.dev)[0-9]+ ]]; then
+            echo "is_prerelease=true" >> $GITHUB_OUTPUT
+          else
+            echo "is_prerelease=false" >> $GITHUB_OUTPUT
+          fi
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v1
         with:
+          token: ${{ secrets.RELEASE_TOKEN }}
           files: dist/*
           generate_release_notes: true
+          prerelease: ${{ steps.prerelease.outputs.is_prerelease }}

.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version (e.g. 3.6.0, 3.6.0b1, 3.6.0rc1)'
+        required: true
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Validate version (PEP 440)
+        run: |
+          python - <<'EOF'
+          import re, sys
+          v = "${{ inputs.version }}"
+          # PEP 440 subset: X.Y.Z, optional aN / bN / rcN / .devN
+          if not re.fullmatch(r'\d+\.\d+\.\d+((a|b|rc)\d+|\.dev\d+)?', v):
+              print(f"Invalid version: {v}")
+              print("Expected forms: 3.6.0, 3.6.0a1, 3.6.0b1, 3.6.0rc1, 3.6.0.dev1")
+              sys.exit(1)
+          EOF
+
+      - name: Check tag does not exist
+        run: |
+          if git rev-parse "v${{ inputs.version }}" >/dev/null 2>&1; then
+            echo "Tag v${{ inputs.version }} already exists."
+            exit 1
+          fi
+
+      - name: Update pyproject.toml
+        run: |
+          python - <<'EOF'
+          import re, pathlib
+          p = pathlib.Path('pyproject.toml')
+          text = p.read_text()
+          new = re.sub(r'^version\s*=\s*".*"', f'version = "${{ inputs.version }}"', text, count=1, flags=re.M)
+          if new == text:
+              raise SystemExit("Failed to update version in pyproject.toml")
+          p.write_text(new)
+          EOF
+
+      - name: Update uniface/__init__.py
+        run: |
+          python - <<'EOF'
+          import re, pathlib
+          p = pathlib.Path('uniface/__init__.py')
+          text = p.read_text()
+          new = re.sub(r"^__version__\s*=\s*'.*'", f"__version__ = '${{ inputs.version }}'", text, count=1, flags=re.M)
+          if new == text:
+              raise SystemExit("Failed to update __version__ in uniface/__init__.py")
+          p.write_text(new)
+          EOF
+
+      - name: Commit, tag, push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add pyproject.toml uniface/__init__.py
+          git commit -m "chore: Release v${{ inputs.version }}"
+          git tag "v${{ inputs.version }}"
+          git push origin HEAD:${{ github.ref_name }}
+          git push origin "v${{ inputs.version }}"

CONTRIBUTING.md

@@ -59,12 +59,12 @@ This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formattin
 #### General Rules
 
 - **Line length:** 120 characters maximum
-- **Python version:** 3.11+ (use modern syntax)
+- **Python version:** 3.10+ (use modern syntax)
 - **Quote style:** Single quotes for strings, double quotes for docstrings
 
 #### Type Hints
 
-Use modern Python 3.11+ type hints (PEP 585 and PEP 604):
+Use modern Python 3.10+ type hints (PEP 585 and PEP 604):
 
 ```python
 # Preferred (modern)
@@ -188,6 +188,49 @@ Example notebooks demonstrating library usage:
 | Face Vector Store  | [10_face_vector_store.ipynb](examples/10_face_vector_store.ipynb)   |
 | Head Pose Estimation | [11_head_pose_estimation.ipynb](examples/11_head_pose_estimation.ipynb) |
 
+## Release Process
+
+Releases are fully automated via GitHub Actions. Only maintainers with branch-protection bypass privileges on `main` can trigger a release.
+
+### Cutting a release
+
+1. Go to **Actions → Release → Run workflow** on GitHub.
+2. Enter the version following [PEP 440](https://peps.python.org/pep-0440/):
+   - Stable: `0.7.0`, `1.0.0`
+   - Pre-release: `0.7.0rc1`, `0.7.0b1`, `0.7.0a1`, `0.7.0.dev1`
+3. Click **Run workflow**.
+
+### What happens automatically
+
+The `Release` workflow:
+
+1. Validates the version string.
+2. Updates `pyproject.toml` and `uniface/__init__.py`.
+3. Commits `chore: Release vX.Y.Z` to `main`.
+4. Creates and pushes tag `vX.Y.Z`.
+
+Pushing the tag then triggers:
+
+- **Publish to PyPI** — builds the package, runs tests on Python 3.10–3.14, uploads to PyPI, and creates a GitHub Release (flagged as pre-release for `a`/`b`/`rc`/`.dev` versions).
+- **Deploy docs** — fires only after a **stable** GitHub Release is published. Pre-releases do not update the live documentation site.
+
+### Verifying a release
+
+- PyPI: <https://pypi.org/project/uniface/>
+- GitHub Releases: <https://github.com/yakhyo/uniface/releases>
+- Docs (stable only): <https://yakhyo.github.io/uniface/>
+
+### Installing a pre-release
+
+End users can opt in to pre-releases with the `--pre` flag:
+
+```bash
+pip install uniface --pre                # latest pre-release
+pip install uniface==0.7.0rc1            # specific pre-release
+```
+
+Without `--pre`, `pip install uniface` always resolves to the latest stable version.
+
 ## Questions?
 
 Open an issue or start a discussion on GitHub.

README.md

@@ -1,4 +1,4 @@
-<h1 align="center">UniFace: All-in-One Face Analysis Library</h1>
+<h1 align="center">UniFace: A Unified Face Analysis Library for Python</h1>
 
 <div align="center">
 
@@ -14,12 +14,12 @@
 </div>
 
 <div align="center">
-    <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/uniface_rounded_q80.webp" width="90%" alt="UniFace - All-in-One Open-Source Face Analysis Library">
+    <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/uniface_rounded_q80.webp" width="90%" alt="UniFace - A Unified Face Analysis Library for Python">
 </div>
 
 ---
 
-**UniFace** is a lightweight, production-ready face analysis library built on ONNX Runtime. It provides high-performance face detection, recognition, landmark detection, face parsing, gaze estimation, and attribute analysis with hardware acceleration support across platforms.
+**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.
 
 ---
 
@@ -76,23 +76,25 @@
 
 ## Installation
 
-**Standard installation**
+**CPU / Apple Silicon**
 
 ```bash
-pip install uniface
+pip install uniface[cpu]
 ```
 
-**GPU support (CUDA)**
+**GPU support (NVIDIA CUDA)**
 
 ```bash
 pip install uniface[gpu]
 ```
 
+> **Why separate extras?** `onnxruntime` and `onnxruntime-gpu` conflict when both are installed — they own the same Python namespace. Installing only the extra you need prevents that conflict entirely.
+
 **From source (latest version)**
 
 ```bash
 git clone https://github.com/yakhyo/uniface.git
-cd uniface && pip install -e .
+cd uniface && pip install -e ".[cpu]"   # or .[gpu] for CUDA
 ```
 
 **FAISS vector store**
@@ -224,7 +226,7 @@ cv2.imwrite("green_screen.jpg", result)
 | [02_face_alignment.ipynb](examples/02_face_alignment.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/02_face_alignment.ipynb) | Face alignment for recognition |
 | [03_face_verification.ipynb](examples/03_face_verification.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/03_face_verification.ipynb) | Compare faces for identity |
 | [04_face_search.ipynb](examples/04_face_search.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/04_face_search.ipynb) | Find a person in group photos |
-| [05_face_analyzer.ipynb](examples/05_face_analyzer.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/05_face_analyzer.ipynb) | All-in-one analysis |
+| [05_face_analyzer.ipynb](examples/05_face_analyzer.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/05_face_analyzer.ipynb) | Unified face analysis |
 | [06_face_parsing.ipynb](examples/06_face_parsing.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/06_face_parsing.ipynb) | Semantic face segmentation |
 | [07_face_anonymization.ipynb](examples/07_face_anonymization.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/07_face_anonymization.ipynb) | Privacy-preserving blur |
 | [08_gaze_estimation.ipynb](examples/08_gaze_estimation.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/08_gaze_estimation.ipynb) | Gaze direction estimation |

docs/concepts/execution-providers.md

@@ -93,7 +93,7 @@ print("Available providers:", providers)
 No additional setup required. ARM64 optimizations are built into `onnxruntime`:
 
 ```bash
-pip install uniface
+pip install uniface[cpu]
 ```
 
 Verify ARM64:
@@ -110,7 +110,7 @@ python -c "import platform; print(platform.machine())"
 
 ### NVIDIA GPU (CUDA)
 
-Install with GPU support:
+Install with GPU support (this installs `onnxruntime-gpu`, which already includes CPU fallback):
 
 ```bash
 pip install uniface[gpu]
@@ -140,7 +140,7 @@ else:
 CPU execution is always available:
 
 ```bash
-pip install uniface
+pip install uniface[cpu]
 ```
 
 Works on all platforms without additional configuration.
@@ -215,7 +215,7 @@ for image_path in image_paths:
 
 3. Reinstall with GPU support:
    ```bash
-   pip uninstall onnxruntime onnxruntime-gpu
+   pip uninstall onnxruntime onnxruntime-gpu -y
    pip install uniface[gpu]
    ```
 

docs/concepts/overview.md

@@ -64,16 +64,14 @@ graph TB
 
 ## Design Principles
 
-### 1. ONNX-First
+### 1. Cross-Platform Inference
 
-UniFace runs inference primarily via ONNX Runtime for core components:
+UniFace uses portable model runtimes to provide consistent inference across macOS, Linux, and Windows. Most core components run through ONNX Runtime, while optional components may use PyTorch where appropriate.
 
 - **Cross-platform**: Same models work on macOS, Linux, Windows
 - **Hardware acceleration**: Automatic selection of optimal provider
 - **Production-ready**: No Python-only dependencies for inference
 
-Some optional components (e.g., emotion TorchScript, torchvision NMS) require PyTorch.
-
 ### 2. Minimal Dependencies
 
 Core dependencies are kept minimal:

docs/contributing.md

@@ -99,6 +99,14 @@ docs: Update installation instructions
 
 ---
 
+## Releases
+
+Releases are automated via GitHub Actions. Maintainers trigger **Actions → Release → Run workflow** with a [PEP 440](https://peps.python.org/pep-0440/) version (e.g. `0.7.0`, `0.7.0rc1`). The workflow bumps `pyproject.toml` + `uniface/__init__.py`, tags the commit, and publishes to PyPI. Docs redeploy only for stable releases.
+
+See [CONTRIBUTING.md](https://github.com/yakhyo/uniface/blob/main/CONTRIBUTING.md#release-process) for the full process.
+
+---
+
 ## Questions?
 
 Open an issue on [GitHub](https://github.com/yakhyo/uniface/issues).

docs/index.md

@@ -10,7 +10,7 @@ template: home.html
 
 # UniFace { .hero-title }
 
-<p class="hero-subtitle">All-in-One Open-Source Face Analysis Library</p>
+<p class="hero-subtitle">A Unified Face Analysis Library for Python</p>
 
 [![PyPI Version](https://img.shields.io/pypi/v/uniface.svg?label=Version)](https://pypi.org/project/uniface/)
 [![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
@@ -20,7 +20,7 @@ template: home.html
 [![Kaggle Badge](https://img.shields.io/badge/Notebooks-Kaggle?label=Kaggle&color=blue)](https://www.kaggle.com/yakhyokhuja/code)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord&logoColor=white)](https://discord.gg/wdzrjr7R5j)
 
-<!-- <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/uniface_rounded_q80.webp" alt="UniFace - All-in-One Open-Source Face Analysis Library" style="max-width: 70%; margin: 1rem 0;"> -->
+<!-- <img src="https://raw.githubusercontent.com/yakhyo/uniface/main/.github/logos/uniface_rounded_q80.webp" alt="UniFace - A Unified Face Analysis Library for Python" style="max-width: 70%; margin: 1rem 0;"> -->
 
 [Get Started](quickstart.md){ .md-button .md-button--primary }
 [View on GitHub](https://github.com/yakhyo/uniface){ .md-button }
@@ -31,7 +31,7 @@ template: home.html
 
 <div class="feature-card" markdown>
 ### :material-face-recognition: Face Detection
-ONNX-optimized detectors (RetinaFace, SCRFD, YOLO) with 5-point landmarks.
+RetinaFace, SCRFD, and YOLO detectors with 5-point landmarks.
 </div>
 
 <div class="feature-card" markdown>
@@ -90,14 +90,14 @@ FAISS-backed embedding store for fast multi-identity face search.
 
 ## Installation
 
-UniFace runs inference primarily via **ONNX Runtime**; some optional components (e.g., emotion TorchScript, torchvision NMS) require **PyTorch**.
+UniFace uses portable model runtimes for consistent inference across macOS, Linux, and Windows. Most core components run through **ONNX Runtime**, while optional components may use **PyTorch** where appropriate.
 
-**Standard**
+**CPU / Apple Silicon**
 ```bash
-pip install uniface
+pip install uniface[cpu]
 ```
 
-**GPU (CUDA)**
+**GPU (NVIDIA CUDA)**
 ```bash
 pip install uniface[gpu]
 ```
@@ -106,7 +106,7 @@ pip install uniface[gpu]
 ```bash
 git clone https://github.com/yakhyo/uniface.git
 cd uniface
-pip install -e .
+pip install -e ".[cpu]"   # or .[gpu] for CUDA
 ```
 
 ---

docs/installation.md

@@ -11,15 +11,27 @@ This guide covers all installation options for UniFace.
 
 ---
 
+## Why Two Extras?
+
+`onnxruntime` (CPU) and `onnxruntime-gpu` (CUDA) both own the same Python namespace.
+Installing both at the same time causes file conflicts and silent provider mismatches.
+UniFace exposes them as separate, mutually exclusive extras so you install exactly one.
+
+---
+
 ## Quick Install
 
-The simplest way to install UniFace:
+=== "CPU / Apple Silicon"
 
-```bash
-pip install uniface
-```
+    ```bash
+    pip install uniface[cpu]
+    ```
 
-This installs the CPU version with all core dependencies.
+=== "NVIDIA GPU (CUDA)"
+
+    ```bash
+    pip install uniface[gpu]
+    ```
 
 ---
 
@@ -27,14 +39,16 @@ This installs the CPU version with all core dependencies.
 
 ### macOS (Apple Silicon - M1/M2/M3/M4)
 
-For Apple Silicon Macs, the standard installation automatically includes ARM64 optimizations:
+The `[cpu]` extra pulls in the standard `onnxruntime` package, which has native ARM64 support
+built in since version 1.13. No additional setup is needed for CoreML acceleration.
 
 ```bash
-pip install uniface
+pip install uniface[cpu]
 ```
 
 !!! tip "Native Performance"
-    The base `onnxruntime` package has native Apple Silicon support with ARM64 optimizations built-in since version 1.13+. No additional configuration needed.
+    `onnxruntime` 1.13+ includes ARM64 optimizations out of the box.
+    UniFace automatically detects and enables `CoreMLExecutionProvider` on Apple Silicon.
 
 Verify ARM64 installation:
 
@@ -47,18 +61,22 @@ python -c "import platform; print(platform.machine())"
 
 ### Linux/Windows with NVIDIA GPU
 
-For CUDA acceleration on NVIDIA GPUs:
-
 ```bash
 pip install uniface[gpu]
 ```
 
+This installs `onnxruntime-gpu`, which includes both `CUDAExecutionProvider` and
+`CPUExecutionProvider` — no separate CPU package is needed.
+
 **Requirements:**
 
-- `uniface[gpu]` automatically installs `onnxruntime-gpu`. Requirements depend on the ORT version and execution provider.
+- NVIDIA driver compatible with your CUDA version
+- CUDA 11.x or 12.x toolkit
+- cuDNN 8.x
 
 !!! info "CUDA Compatibility"
-    See the [ONNX Runtime GPU compatibility matrix](https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html) for matching CUDA and cuDNN versions.
+    See the [ONNX Runtime GPU compatibility matrix](https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html)
+    for matching CUDA and cuDNN versions.
 
 Verify GPU installation:
 
@@ -70,23 +88,10 @@ print("Available providers:", ort.get_available_providers())
 
 ---
 
-### FAISS Vector Store
-
-For fast multi-identity face search using a FAISS vector store:
-
-```bash
-pip install faiss-cpu   # CPU
-pip install faiss-gpu   # NVIDIA GPU (CUDA)
-```
-
-See the [Stores module](modules/stores.md) for usage.
-
----
-
 ### CPU-Only (All Platforms)
 
 ```bash
-pip install uniface
+pip install uniface[cpu]
 ```
 
 Works on all platforms with automatic CPU fallback.
@@ -100,37 +105,58 @@ For development or the latest features:
 ```bash
 git clone https://github.com/yakhyo/uniface.git
 cd uniface
-pip install -e .
+
+pip install -e ".[cpu]"   # CPU / Apple Silicon
+pip install -e ".[gpu]"   # NVIDIA GPU
 ```
 
 With development dependencies:
 
 ```bash
-pip install -e ".[dev]"
+pip install -e ".[cpu,dev]"
 ```
 
 ---
 
+## FAISS Vector Store
+
+For fast multi-identity face search using a FAISS vector store:
+
+```bash
+pip install faiss-cpu   # CPU
+pip install faiss-gpu   # NVIDIA GPU (CUDA)
+```
+
+See the [Stores module](modules/stores.md) for usage.
+
+---
+
 ## Dependencies
 
-UniFace has minimal dependencies:
+UniFace has minimal core dependencies:
 
 | Package | Purpose |
 |---------|---------|
 | `numpy` | Array operations |
 | `opencv-python` | Image processing |
-| `onnxruntime` | Model inference |
 | `scikit-image` | Geometric transforms |
+| `scipy` | Signal processing |
 | `requests` | Model download |
 | `tqdm` | Progress bars |
 
-**Optional:**
+**Runtime extras (install exactly one):**
 
-| Package | Install extra | Purpose |
-|---------|---------------|---------|
+| Extra | Package | Use case |
+|-------|---------|---------|
+| `uniface[cpu]` | `onnxruntime` | CPU inference, Apple Silicon |
+| `uniface[gpu]` | `onnxruntime-gpu` | NVIDIA CUDA inference |
+
+**Other optional packages:**
+
+| Package | Install | Purpose |
+|---------|---------|---------|
 | `faiss-cpu` / `faiss-gpu` | `pip install faiss-cpu` | FAISS vector store |
-| `onnxruntime-gpu` | `uniface[gpu]` | CUDA acceleration |
-| `torch` | `pip install torch` | Emotion model uses TorchScript |
+| `torch` | `pip install torch` | Emotion model (TorchScript) |
 | `torchvision` | `pip install torchvision` | Faster NMS for YOLO detectors |
 
 ---
@@ -155,17 +181,81 @@ print("Installation successful!")
 
 ---
 
+## Upgrading
+
+When upgrading UniFace, stay consistent with your runtime extra:
+
+```bash
+pip install --upgrade uniface[cpu]   # or uniface[gpu]
+```
+
+If you are switching from CPU to GPU (or vice versa):
+
+```bash
+pip uninstall onnxruntime onnxruntime-gpu -y
+pip install uniface[gpu]   # install the one you want
+```
+
+---
+
+## Pre-release Versions
+
+UniFace ships release candidates and betas to PyPI ahead of stable releases (versions like `0.7.0rc1`, `0.7.0b1`, `0.7.0a1`). These let you try upcoming features before they're finalized.
+
+`pip install uniface` always installs the latest **stable** release. To opt in to pre-releases:
+
+```bash
+# Latest pre-release (if newer than latest stable)
+pip install uniface[cpu] --pre
+
+# A specific pre-release
+pip install uniface[cpu]==0.7.0rc1
+```
+
+Pre-releases are not recommended for production — APIs may still change before the stable release.
+
+---
+
 ## Troubleshooting
 
+### onnxruntime Not Found
+
+If you see:
+
+```
+ImportError: onnxruntime is not installed. Install it with one of:
+  pip install uniface[cpu]   # CPU / Apple Silicon
+  pip install uniface[gpu]   # NVIDIA GPU (CUDA)
+```
+
+You installed uniface without an extra. Run the appropriate command above.
+
+---
+
+### Both onnxruntime and onnxruntime-gpu Installed
+
+If you previously ran `pip install uniface[gpu]` on top of a `pip install uniface[cpu]`
+(or vice versa), you may have both packages installed simultaneously, which causes conflicts.
+Fix it with:
+
+```bash
+pip uninstall onnxruntime onnxruntime-gpu -y
+pip install uniface[gpu]   # or uniface[cpu]
+```
+
+---
+
 ### Import Errors
 
-If you encounter import errors, ensure you're using Python 3.10+:
+Ensure you're using Python 3.10+:
 
 ```bash
 python --version
 # Should show: Python 3.10.x or higher
 ```
 
+---
+
 ### Model Download Issues
 
 Models are automatically downloaded on first use. If downloads fail:
@@ -179,6 +269,25 @@ model_path = verify_model_weights(RetinaFaceWeights.MNET_V2)
 print(f"Model downloaded to: {model_path}")
 ```
 
+---
+
+### CUDA Not Detected
+
+1. Verify CUDA installation:
+   ```bash
+   nvidia-smi
+   ```
+
+2. Check CUDA version compatibility with ONNX Runtime.
+
+3. Reinstall the GPU extra cleanly:
+   ```bash
+   pip uninstall onnxruntime onnxruntime-gpu -y
+   pip install uniface[gpu]
+   ```
+
+---
+
 ### Performance Issues on Mac
 
 Verify you're using the ARM64 build (not x86_64 via Rosetta):

docs/notebooks.md

@@ -12,7 +12,7 @@ Run UniFace examples directly in your browser with Google Colab, or download and
 | [Face Alignment](https://github.com/yakhyo/uniface/blob/main/examples/02_face_alignment.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/02_face_alignment.ipynb) | Align faces for recognition |
 | [Face Verification](https://github.com/yakhyo/uniface/blob/main/examples/03_face_verification.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/03_face_verification.ipynb) | Compare faces for identity |
 | [Face Search](https://github.com/yakhyo/uniface/blob/main/examples/04_face_search.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/04_face_search.ipynb) | Find a person in group photos |
-| [Face Analyzer](https://github.com/yakhyo/uniface/blob/main/examples/05_face_analyzer.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/05_face_analyzer.ipynb) | All-in-one face analysis |
+| [Face Analyzer](https://github.com/yakhyo/uniface/blob/main/examples/05_face_analyzer.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/05_face_analyzer.ipynb) | Unified face analysis |
 | [Face Parsing](https://github.com/yakhyo/uniface/blob/main/examples/06_face_parsing.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/06_face_parsing.ipynb) | Semantic face segmentation |
 | [Face Anonymization](https://github.com/yakhyo/uniface/blob/main/examples/07_face_anonymization.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/07_face_anonymization.ipynb) | Privacy-preserving blur |
 | [Gaze Estimation](https://github.com/yakhyo/uniface/blob/main/examples/08_gaze_estimation.ipynb) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/yakhyo/uniface/blob/main/examples/08_gaze_estimation.ipynb) | Gaze direction estimation |
@@ -34,7 +34,7 @@ git clone https://github.com/yakhyo/uniface.git
 cd uniface
 
 # Install dependencies
-pip install uniface jupyter
+pip install "uniface[cpu]" jupyter   # or uniface[gpu] for CUDA
 
 # Launch Jupyter
 jupyter notebook examples/

examples/01_face_detection.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -31,7 +31,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/02_face_alignment.ipynb

@@ -17,7 +17,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -34,7 +34,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/03_face_verification.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -30,7 +30,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/04_face_search.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -28,7 +28,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/05_face_analyzer.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -30,7 +30,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/06_face_parsing.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -32,7 +32,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/07_face_anonymization.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -31,7 +31,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/08_gaze_estimation.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -30,7 +30,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/09_face_segmentation.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -32,7 +32,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/10_face_vector_store.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -33,7 +33,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface faiss-cpu\n",
+    "%pip install -q \"uniface[cpu]\" faiss-cpu\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/11_head_pose_estimation.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -30,7 +30,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/12_face_recognition.ipynb

@@ -14,7 +14,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -44,7 +44,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

examples/13_portrait_matting.ipynb

@@ -13,7 +13,7 @@
     "  <a style=\"margin-bottom:6px;\" href=\"https://github.com/yakhyo/uniface\"><img alt=\"GitHub Stars\" src=\"https://img.shields.io/github/stars/yakhyo/uniface.svg?style=social\"></a>\n",
     "</div>\n",
     "\n",
-    "**UniFace** is a lightweight, production-ready, all-in-one face analysis library built on ONNX Runtime.\n",
+    "**UniFace** is a lightweight, production-ready Python library for face detection, recognition, tracking, landmark analysis, face parsing, gaze estimation, and face attributes.\n",
     "\n",
     "🔗 **GitHub**: [github.com/yakhyo/uniface](https://github.com/yakhyo/uniface) | 📚 **Docs**: [yakhyo.github.io/uniface](https://yakhyo.github.io/uniface)\n",
     "\n",
@@ -30,7 +30,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "%pip install -q uniface\n",
+    "%pip install -q \"uniface[cpu]\"\n",
     "\n",
     "# Clone repo for assets (Colab only)\n",
     "import os\n",

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: UniFace
-site_description: All-in-One Face Analysis Library with ONNX Runtime
+site_description: A Unified Face Analysis Library for Python
 site_author: Yakhyokhuja Valikhujaev
 site_url: https://yakhyo.github.io/uniface
 

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "uniface"
-version = "3.5.0"
-description = "UniFace: A Comprehensive Library for Face Detection, Recognition, Tracking, Landmark Analysis, Face Parsing, Gaze Estimation, Age, and Gender Detection"
+version = "3.5.2"
+description = "UniFace: A Unified Face Analysis Library for Python"
 readme = "README.md"
 license = "MIT"
 authors = [{ name = "Yakhyokhuja Valikhujaev", email = "yakhyo9696@gmail.com" }]
@@ -44,7 +44,6 @@ classifiers = [
 dependencies = [
     "numpy>=1.21.0",
     "opencv-python>=4.5.0",
-    "onnxruntime>=1.16.0",
     "scikit-image>=0.22.0",
     "scipy>=1.7.0",
     "requests>=2.28.0",
@@ -52,8 +51,15 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest>=7.0.0", "ruff>=0.4.0"]
+cpu = ["onnxruntime>=1.16.0"]
 gpu = ["onnxruntime-gpu>=1.16.0"]
+dev = ["pytest>=7.0.0", "ruff>=0.4.0", "pre-commit>=3.0.0"]
+docs = [
+    "mkdocs-material>=9.0",
+    "pymdown-extensions>=10.0",
+    "mkdocs-git-committers-plugin-2>=1.0",
+    "mkdocs-git-revision-date-localized-plugin>=2.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/yakhyo/uniface"

requirements.txt

@@ -1,7 +1,9 @@
 numpy>=1.21.0
 opencv-python>=4.5.0
-onnxruntime>=1.16.0
 scikit-image>=0.22.0
 scipy>=1.7.0
 requests>=2.28.0
 tqdm>=4.64.0
+# Install ONE of the following (not both):
+# onnxruntime>=1.16.0        # CPU / Apple Silicon  →  pip install uniface[cpu]
+# onnxruntime-gpu>=1.16.0    # NVIDIA CUDA          →  pip install uniface[gpu]

uniface/__init__.py

@@ -31,7 +31,7 @@ from __future__ import annotations
 
 __license__ = 'MIT'
 __author__ = 'Yakhyokhuja Valikhujaev'
-__version__ = '3.5.0'
+__version__ = '3.5.2'
 
 import contextlib
 

uniface/landmark/models.py

@@ -58,7 +58,7 @@ class Landmark106(BaseLandmarker):
         self.model_path = verify_model_weights(model_name)
         self._initialize_model()
 
-    def _initialize_model(self):
+    def _initialize_model(self) -> None:
         """
         Initialize the ONNX model from the stored model path.
 

uniface/onnx_utils.py

@@ -12,7 +12,15 @@ from __future__ import annotations
 
 import functools
 
-import onnxruntime as ort
+try:
+    import onnxruntime as ort
+except ImportError as e:
+    raise ImportError(
+        'onnxruntime is not installed. Install it with one of:\n'
+        '  pip install uniface[cpu]   # CPU / Apple Silicon\n'
+        '  pip install uniface[gpu]   # NVIDIA GPU (CUDA)\n'
+        'Do not install both — they conflict.'
+    ) from e
 
 from uniface.log import Logger
 

uniface/privacy/blur.py

@@ -4,11 +4,14 @@
 
 from __future__ import annotations
 
-from typing import ClassVar
+from typing import TYPE_CHECKING, ClassVar
 
 import cv2
 import numpy as np
 
+if TYPE_CHECKING:
+    from uniface.types import Face
+
 __all__ = ['BlurFace', 'EllipticalBlur']
 
 
@@ -137,7 +140,7 @@ class BlurFace:
     def anonymize(
         self,
         image: np.ndarray,
-        faces: list,
+        faces: list[Face],
         inplace: bool = False,
     ) -> np.ndarray:
         """Anonymize faces in an image.