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:

pip install "quantum-learn[hf]"

Local save and load

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

from qlearn import VariationalQuantumClassifier

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

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

Load from the Hub

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:

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.