Hugging Face Hub Integration
============================

``quantum-learn`` can save trained ``VariationalQuantumClassifier`` models in a
Hugging Face-compatible artifact layout, push those artifacts to the Hub, and
reload them from either a local directory or a Hub repository.

Installation
------------

Hub support is optional. Install the Hugging Face extra before calling
``push_to_hub`` or loading a remote repository:

.. code-block:: bash

   pip install "quantum-learn[hf]"

Local save and load
-------------------

.. code-block:: python

   from qlearn import VariationalQuantumClassifier

   model = VariationalQuantumClassifier()
   model.fit(X_train, y_train)

   model.save_pretrained("./iris-vqc")

   loaded = VariationalQuantumClassifier.from_pretrained("./iris-vqc")
   predictions = loaded.predict(X_test)

The saved directory contains:

- ``config.json``: model class, init parameters, fitted classifier state, VQC
  backend settings, and schema version
- ``weights.npz``: trained numerical VQC parameters
- ``metadata.json``: package versions, Python version, backend, creation time,
  and schema version
- ``README.md``: a basic Hugging Face model card

Push to the Hugging Face Hub
----------------------------

.. code-block:: python

   from qlearn import VariationalQuantumClassifier

   model = VariationalQuantumClassifier()
   model.fit(X_train, y_train)

   model.push_to_hub("KUQCI/iris-vqc-pennylane")

Load from the Hub
-----------------

.. code-block:: python

   from qlearn import VariationalQuantumClassifier

   model = VariationalQuantumClassifier.from_pretrained(
       "KUQCI/iris-vqc-pennylane"
   )
   predictions = model.predict(X_test)

``from_pretrained`` also accepts Hub options such as ``revision``,
``cache_dir``, ``token``, and ``local_files_only``.

Private repositories
--------------------

Pass a token when creating or loading private repositories:

.. code-block:: python

   model.push_to_hub(
       "KUQCI/private-vqc",
       private=True,
       token="hf_...",
   )

   loaded = VariationalQuantumClassifier.from_pretrained(
       "KUQCI/private-vqc",
       token="hf_...",
   )

Model cards
-----------

``save_pretrained`` writes ``README.md`` when one does not already exist. The
generated card includes the ``quantum-learn`` library name, quantum machine
learning tags, loading instructions, backend information, and a note that
metrics are not provided unless the user adds them.

Serialization limits
--------------------

The current implementation avoids pickle and arbitrary code execution. It
supports the default ``VariationalQuantumClassifier`` workflow backed by a
``qlearn`` backend ``VariationalQuantumCircuit``. Custom target encoders,
prediction decoders, probability decoders, ansatz callables, callable
measurements, and callable losses are rejected with clear errors because they
cannot be reconstructed safely from JSON.