.. _relnotes_v0.9.5:

v0.9.5
======

.. _relnotes_v0.9.5_Upgrade Notes:

Upgrade Notes
-------------

- Binary files for the docs are now added through a pull request against the
  ``assets`` branch instead of a force-push. Contributors who used the old
  recipe follow the updated "Adding binary files to the docs" section of
  ``CONTRIBUTING.md``.

- The file format of a serializable class is now declared on the class itself
  under one set of names, and the module-level constants that held it are
  gone. ``_FILE_SUFFIX`` became ``__file_format__``, ``_METADATA_KEY`` became
  ``__metadata_key__``, ``_CLASS_KEY`` became ``__class_key__``,
  ``_STATE_KEYS`` became ``__state_keys__``, and every per-module format
  version (``_CLUSTERING_EMBEDDER_FILE_FORMAT_VERSION``,
  ``_NEURAL_EMBEDDER_FORMAT_VERSION``, ``_PIPELINE_FORMAT_VERSION``,
  ``_CLIP_EMBEDDER_FORMAT_VERSION``, ``_STORE_FORMAT_VERSION``) became
  ``__format_version__`` on the class that writes it. Their compatibility
  table is ``__compatibility_mapping__``. Subclasses outside the library that
  set any of the old names have to rename them: the old names are no longer
  read, and ``SerializerMixin`` now raises a ``TypeError`` at class-definition
  time when a class that implements ``to_dict`` and ``from_dict`` leaves one
  of the required attributes undeclared.

- ``pyvisim.serialization.EMBEDDER_METADATA_KEY`` and
  ``pyvisim._base_classes.EMBEDDER_FILE_SUFFIX`` were removed. Read them from
  the embedder class instead, for example
  ``VLADEmbedder.__metadata_key__`` and ``VLADEmbedder.__file_format__``.

- Subclasses outside the library that implement ``_embed`` now receive one
  batch as a list of canonical ``uint8`` ``(H, W[, C])`` images, without
  ``dims`` and ``value_range``, since ``ImageEmbedderBase.embed`` normalizes
  and batches the input. Drop the two parameters and the batching loop from
  your ``_embed``.

- ``SerializerMixin.to_dict`` is no longer abstract. It adds the format
  version and the class name to the mapping returned by the new abstract
  ``_state`` method. Subclasses outside the library rename their ``to_dict``
  to ``_state`` and drop the ``format_version`` and class-name entries from
  it, and ``__state_keys__`` no longer lists the class key. Loading a file
  whose state lacks the format version or the class name raises a
  ``ValueError``.

- ``pyvisim.serialization.embedder_to_dict`` and
  ``pyvisim.serialization.embedder_from_dict`` are removed. Code importing
  them calls ``embedder.to_dict()`` instead, and
  ``SerializableImageEmbedder.from_dict(state)`` to rebuild an embedder of
  any class from its state.


.. _relnotes_v0.9.5_New Features:

New Features
------------

- The ``KMeans``, ``DiagCovarGaussianMixture`` and ``PCA`` models of the
  classic embedders can be saved on their own with ``save_to_disk`` and
  loaded back with ``load_from_disk``, as ``.safetensors`` files.


.. _relnotes_v0.9.5_Enhancement Notes:

Enhancement Notes
-----------------

- The ``Benchmarks`` workflow pushes its barplots to
  ``docs/benchmark-barplots`` for review instead of publishing them directly.
  The new ``Squash assets`` workflow keeps ``assets`` at a single commit
  after each merge.

- Every embedder rejects an empty input with the same ``ValueError``
  ("Expected at least one image, got none.") instead of a NumPy concatenation
  error or an embedder-specific message.

- Every ``load_from_disk`` reports an unreadable file the same way, as
  "File ... is not a valid <suffix> file" followed by the reason. The image
  store used to raise the bare reason, while the embedders dropped it.

- The clustering models of ``VLADEmbedder`` and ``FisherVectorEmbedder``
  record a ``format_version`` in their part of the ``.embedder`` file.
  Files written before still load.