API Stability
=============

psipose follows semantic versioning from version 1.0.0 onward.

Stable Public API
-----------------

The 1.x public API includes documented imports from ``psipose`` and the
documented subpackages:

* ``psipose.feature_maps``
* ``psipose.ansatze``
* ``psipose.measurements``
* ``psipose.models``
* ``psipose.estimators``
* ``psipose.preprocessing``
* ``psipose.datasets``
* ``psipose.training``
* ``psipose.logging``

Patch releases should preserve backward compatibility. Minor releases may add
new features, parameters, and components while keeping existing documented
behavior compatible.

Deprecations
------------

If a documented API must change during the 1.x series, psipose should first
emit a deprecation warning and document the replacement. Removal should wait
for a later minor release unless the behavior is unsafe or already broken.

Non-Stable Internals
--------------------

Private names, undocumented helper functions, test utilities, and generated
build artifacts are not part of the stable API. Code that imports private
members may break between patch releases.

Scikit-Learn Compatibility
--------------------------

psipose estimators are designed to follow scikit-learn conventions such as
``fit``, ``predict``, ``score``, ``get_params``, and ``set_params``.
Quantum training is stochastic and can be expensive, so the project uses
targeted sklearn compatibility tests rather than claiming full
``check_estimator`` coverage for every estimator.