Upgrading from 1.x
==================
``image-match`` 2.0 is a modernization of the original project. The guiding
rule was **data compatibility**: signatures, word encodings, and stored record
formats are unchanged, so an index built with 1.x keeps working — no reindex
is needed to keep searching existing data.

What stays compatible
---------------------
* **Signatures** — ``ImageSignature`` still produces the same 648-dimensional
  int8 vector (``n_grid=9``, ``crop_percentile=(5, 95)``, ``P=34``). A
  signature generated by 1.x matches the same images under 2.0.
* **Record format** — ``simple_word_0`` … ``simple_word_62`` plus ``path``,
  ``signature``, ``timestamp``, and ``metadata`` are stored exactly as before.
* **Search semantics** — word-overlap pre-filter, ``normalized_distance``
  scoring, and the ``distance_cutoff=0.45`` default are unchanged.
* **Public API names** — ``SignatureES``, ``SignatureMongo``,
  ``add_image``, ``search_image``, ``make_record``, ``get_words``,
  ``words_to_int`` are all still where they were.

Breaking changes
----------------
Python version
    Requires **Python 3.13 or newer** (1.x targeted Python 2.7/early 3.x).
Backend dependencies are extras
    ``elasticsearch``, ``opensearch-py``, and ``pymongo`` are no longer
    installed by default. Install the extra for your backend::

        pip install "image-match[elasticsearch]"   # or [opensearch], [mongo],
                                                   # [elasticsearch-async], …
``SignatureES`` constructor
    * ``doc_type`` was removed — Elasticsearch 7 no longer uses mapping types.
      Indexes created with a doc_type still work; new documents are simply
      indexed without one.
    * ``timeout`` is now a string (``"10s"``, default) rather than an int of
      seconds.
    * Argument order is now ``(es, index, timeout, size, …)``. If you called
      the 1.x signature positionally — ``SignatureES(es, 'images', 'image',
      10, 100)`` — switch to keyword arguments.
Elasticsearch client
    Requires ``elasticsearch`` **7.x** (``>=7.17,<8``). The 8.x/9.x clients
    removed the ``body=`` parameter the driver uses; OpenSearch users should
    install the ``[opensearch]`` extra instead.
MongoDB driver
    Requires ``pymongo>=4.0``. ``SignatureMongo(collection)`` itself is
    unchanged.

New in 2.0
----------
* OpenSearch drivers (``SignatureOpenSearch``, ``SignatureOpenSearchKNN``)
  for OpenSearch 2.x and 3.x, including a ``knn_vector``/HNSW index — see
  :doc:`migration` for moving an existing index to k-NN.
* Async drivers for Elasticsearch and OpenSearch.
* ``add_images()`` bulk ingestion and ``insert_records()`` for pre-generated
  records; ``delete_image()`` removes all records with an exact path.
* ``pre_filter`` metadata filtering on ``search_image``, ``refresh_after`` on
  inserts, ``minimum_should_match``/``use_filter_context`` tuning, and a
  configurable ``delete_duplicates_limit``.

Recommended upgrade path
------------------------
1. Upgrade Python to 3.13+ and reinstall with the extra matching your
   backend.
2. Update ``SignatureES(...)`` calls to keyword arguments (drop ``doc_type``).
3. Existing indexes and Mongo collections keep working — run a known
   near-duplicate pair through ``search_image`` to confirm.
4. Optionally migrate an existing index to the OpenSearch k-NN mapping with
   ``tools/migrate_to_knn.py`` (see :doc:`migration`); the word drivers keep
   working on the migrated hybrid index, so this is reversible.