v1.0.0-rc.3

This candidate officially expands the tested PyTorch runtime range while reusing
the immutable model artifacts published for RC2. The section becomes released
only when the v1.0.0-rc.3 tag and all publication receipts are verified.

Added

• Official PyTorch 2.6-2.13 support with exact matching torchvision pairs
• Reproducible CPU and CUDA lock profiles for every supported PyTorch minor line
• Cross-runtime release validation that proves all eight runtime lines execute the
  same two digest-pinned artifact cohorts on CPU and CUDA

Changed

• Package bounds expanded to torch>=2.6,<2.14 and
  torchvision>=0.21,<0.29
• Torch 2.6 artifacts now route to runtimes 2.6-2.8; Torch 2.11 artifacts route
  to runtimes 2.9-2.13
• CPU CI and dependency auditing now cover every supported runtime profile
• Immutable model pins now reference README-only child revisions whose cards
  document the expanded runtime range; weights and validation metadata are unchanged

Known limitations

• PyTorch 2.8 emits an upstream deprecation warning when loading the older PT2
  archive container; loading and inference remain within the approved tolerances

v1.0.0-rc.2

This is the v1 release candidate change set. The section becomes released only
when the immutable v1.0.0-rc.2 tag and all publication receipts have been verified.
The v1.0.0-rc.1 tag is retained as an unpublished, aborted candidate: its
release-note gate failed before a GitHub draft or any external registry write.

Breaking Changes

• Minimum Python version raised from 3.8 to 3.10
• Supported Python range is explicitly capped at <3.13 for Python 3.10-3.12
• PyTorch support is bounded to the explicit 2.6.x and 2.11.x cohort lines;
  2.3-2.5 and 2.7-2.10 are rejected before model download
• Default models migrated from TorchScript (.pt) to torch.export (.pt2);
  verified TorchScript artifacts now require explicit allow_legacy_models=True
• Google Drive model configs are deprecated and fail closed without immutable size
  and digest metadata
• 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
• A custom-component guide separating runtime predictor/detector injection,
  digest-pinned external artifacts, and the governed built-in model contribution
  process
• 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
• Versioned model-artifact manifest with immutable Hub revisions, byte sizes,
  SHA-256 digests, real formats, runtime/schema cohorts, and device eligibility
• Verified atomic downloads, concurrent first-use locking, cache quarantine,
  explicit offline mode, and persistent schema-incompatibility records
• Cost-planning and explicit prefetch APIs plus non-executing legacy inspection,
  exact-hash migration, quarantine reporting, and confirmed cleanup APIs
• Cohort export/validation/upload script: scripts/export_model_cohorts_hf.py
• Device-aware cohort validation in export script via --validate-devices (for example cpu,cuda)
• Fail-closed cohort validation for recursive non-finite outputs, strict state
  reconstruction, complete batch/shape/device matrices, output schemas, and
  task-level invariants
• Digest-bound, review-gated model publication plans with per-model atomic Hub
  commits, resumable receipts, and manifest-last promotion
• Publication evidence now requires finite per-case numerical proof, exact Hub
  parent lineage on resume, and the immutable remote manifest path
• Machine-readable compatibility and per-model governance/limitations records;
  incomplete weight rights or source-checkpoint mapping block manifest approval
• Immutable Hub object auditor and complete local CPU/CUDA cohort-matrix verifier
• CPU-golden model validation with a recorded highest-precision float32 policy,
  deterministic cuDNN settings, and TensorFloat-32 disabled
• Export-only model_defs/ architecture definitions for reproducible .pt2 cohort generation without making them runtime model dependencies
• Dependency alignment check script: scripts/check_dependency_sync.py
• uv.lock for reproducible PyPI-based dependency resolution
• [tool.uv] configuration in pyproject.toml
• Exact CPU and CUDA uv lock profiles for every supported Torch cohort, refreshed
  CPU/GPU conda locks, dependency advisory gating, and CycloneDX SBOM generation
• Tiered CI for source tests, Python 3.10-3.12 wheel installs, Torch 2.6/2.11
  CPU cohorts, branch-wheel conda validation, and frozen production images
• Owner-only protected-commit local GPU workflow covering all cohort devices, the
  installed default analyzer, public notebook, and both production images

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
• Model artifact strategy changed to prioritize portability and install-time simplicity over TorchScript-specific runtime behavior: .pt2 artifacts do not require bundled model source code, while versioned cohorts handle PyTorch exported-program schema differences across supported torch runtimes (2.6, 2.11)
• Built-in Hugging Face model configs now select exactly one declared compatible
  manifest artifact; they no longer synthesize filenames or cascade downloads
• AU predictor model rewritten with timm Swin Transformer backbone for torch.export compatibility
• Build metadata now uses PEP 639 SPDX license fields with setuptools>=77.0.3, removing the setuptools license-table deprecation warning
• uv PyTorch index configuration now uses explicit torch/torchvision sources instead of a global extra index, so non-PyTorch packages resolve from PyPI by default
• Docker images no longer set a global uv PyTorch extra index; GPU images install CUDA torch wheels explicitly with uv's --torch-backend cu124 after the base install/sync step
• Docker dev/test images no longer read or write Python bytecode from bind-mounted source trees
• Docker dev/test images use container-local model and coverage caches for tests, avoiding root-owned artifacts in bind-mounted checkouts
• Docker build contexts now exclude local model/export artifacts that are not part of release images
• Docker dev/test images migrated from conda/conda-lock to uv for faster builds
• Docker production images now install facetorch from the checked-out release source with uv instead of racing against the PyPI publication job
• Development dependencies consolidated from requirements.dev.txt into pyproject.toml
• Development release-validation dependencies now include build and packaging>=25.0 for Metadata 2.4 / PEP 639 checks
• Replaced the misleading open-ended Torch dependency with a bounded disjoint
  specifier matching the two declared artifact cohorts
• Removed the Torch 2.3 cohort because GHSA-53q9-r3pm-6pq6 is a critical
  torch.load(weights_only=True) remote-code-execution advisory
• Retained the validated Torch 2.6/CUDA 12.4 cohort under three exact moderate
  advisory exceptions, limited to unused APIs and expiring on 2026-11-20
• Docker base images updated to Python 3.12 and CUDA 12.4
• Production images now build and install the exact branch wheel as a non-root
  user from the same locked Torch 2.6 CPU/CUDA 12.4 profiles used in CI
• Candidate Python support narrowed to 3.10, 3.11, and 3.12 pending final CI lanes
• Predictor cohort validation defines batches as independent faces from one image;
  multi-image batching remains outside the v1 API
• GPU environment updated from CUDA 11.2 to CUDA 12.4+
• Development status remains Beta through the approved release-candidate soak
• Google Colab notebook updated to the exact 1.0.0rc2 contract and immutable
  source tag
• RC onboarding now separates stable and prerelease channels, preinstalls an
  explicit CPU/GPU PyTorch cohort, and pins immutable Docker image tags

Fixed

• Release-note extraction now confines an optional heading suffix to one line and
  has release-blocker coverage, preventing a non-empty candidate section from
  being misread as empty
• NumPy arrays that look CHW/BCHW or are plausible under both channel-first and
  channel-last conventions now require an explicit layout instead of guessing
• Inferred signed-integer range failures no longer claim that the caller supplied
  an InputSpec
• Detector coordinate restoration no longer applies the resize scale twice when
  custom postprocessors expose boxes as a view of dets
• Atomic model-cache promotion fsyncs the parent directory after publishing the
  verified artifact
• Model-cache locks publish complete ownership records atomically before they
  become visible to competing downloaders
• URLReader charges DNS resolution against its total deadline and rejects
  multicast, site-local, and other non-unicast network targets
• Model governance approval requires exact hosted-checkpoint digest verification
• Stable alias promotion now fails closed on GitHub authentication, API, or
  network errors while accepting only a schema-validated missing latest release
• The deprecated run_legacy adapter accepts both positional layouts shipped
  across v0.x, preserves historical source-alias precedence, and keeps direct
  Pillow decode failures within the public InputError hierarchy
• Analyzer execution now fails clearly when selected predictors have no unifier,
  validates one prediction per input face, and uses explicit utilizer dependencies
  instead of component-name coupling or first-face inference state
• The shipped detector preprocessor isolates caller-configurable transforms from
  the canonical raw tensor, including transforms configured for in-place mutation;
  custom preprocessors retain defensive copying by default
• Python 3.11 now runs the full source suite on the lowest supported Torch cohort,
  in addition to the existing Python 3.10 cohort and Python 3.12 container suites
• RetinaFace postprocessing creates priors and NMS temporaries on the incoming
  inference tensor device rather than relying on potentially stale configured state
• Google Drive failures that produce no file now raise an actionable
  ArtifactIntegrityError instead of a bare FileNotFoundError
• "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...

v0.6.2

Released on April 17, 2026.

Fixed

• AU predictor CUDA deadlock with PyTorch >= 2.0 and CUDA >= 12.0 by loading model as native PyTorch nn.Module instead of TorchScript

Added

• Native PyTorch implementation of OpenGraphAU model (Swin Transformer backbone + GNN head)
• Support for loading native PyTorch models via native_model_class parameter in BaseModel
• timm dependency for model utilities (DropPath, to_2tuple, trunc_normal_)

Changed

• AU predictor device restored from forced CPU to configurable device (CUDA support re-enabled)

v0.6.1

Released on April 14, 2026.

Fixed

• PostArgMax post-processor to handle tuple inputs (resolves TypeError: argmax(): argument 'input' must be Tensor, not tuple)
• PostSigmoidBinary post-processor to handle tuple inputs for consistency with other post-processors

Changed

• Replaced pypi-publish and docker-push workflows with unified release workflow triggered by GitHub Release
• Switched conda CI from miniconda (classic solver) to miniforge (libmamba), reducing run time from ~60 min to ~1 min
• Updated all GitHub Actions to latest versions (checkout@v4, setup-python@v5, setup-miniconda@v3)
• Removed non-working paperswithcode badges from README for better readability

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

v0.6.0

Added

• DownloaderHuggingFace for downloading models from Hugging Face Hub

Changed

• default model download source from Google Drive to Hugging Face Hub

v0.5.1

0.5.1

Released on November 17, 2024.

Changed

• UnversalReader to read PIL images as RGB
• UniversalReader to read numpy arrays to torch directly
• RetinaFace pre-normalization color space to RGB
• torch.cross torch.linalg.cross in 3D landmark drawer

v0.5.0

Added

• UniversalReader for loading data like PIL images, numpy arrays, torch tensors, bytes, urls, and file paths

Changed

• Enable conda virtual environment by default in Docker images
• FaceAnalyzer run method to accept various input types via image_source parameter

v0.4.2

Added

• Tensor input support for FaceAnalyzer run method
• TensorReader for transforming incoming torch tensors

v0.4.1

Changed

• postprocessor for label confidence pairs to have no offset by default
• Resize transform configs to enable antialiasing by default
• notebook to version 0.4.0 or higher
• notebook to include Action Unit and Valence Arousal predictors

v0.4.0

Added

• predictor for facial valence arousal - ELIM AL from Kim et al.
• predictor postprocessor for creating label confidence pairs

Changed

• FaceAnalyzer can run without any predictors or utilizers