coco_pipe.decoding.interfaces
=============================

.. py:module:: coco_pipe.decoding.interfaces

.. autoapi-nested-parse::

   Lightweight public interfaces for decoding estimator families.
   ==============================================================

   These protocols define the structural contracts for models and extractors
   used within the decoding pipeline. Since they are runtime-checkable,
   the pipeline can verify capabilities without strict inheritance from
   scikit-learn base classes.



Classes
-------

.. autoapisummary::

   coco_pipe.decoding.interfaces.DecoderEstimator
   coco_pipe.decoding.interfaces.EmbeddingExtractor
   coco_pipe.decoding.interfaces.NeuralTrainable


Module Contents
---------------

.. py:class:: DecoderEstimator

   Bases: :py:obj:`Protocol`


   Protocol for scikit-learn-compatible decoding estimators.

   This interface defines the minimal set of methods required for an
   estimator to be integrated into the cross-validation engine.


   .. py:method:: fit(X, y = None, **fit_params)

      Fit the estimator to the provided data.

      :param X: Training vector, where n_samples is the number of samples and
                n_features is the number of features.
      :type X: array-like of shape (n_samples, n_features)
      :param y: Target values (class labels in classification, real numbers in
                regression).
      :type y: array-like of shape (n_samples,), optional
      :param \*\*fit_params: Parameters to pass to the underlying fit method.
      :type \*\*fit_params: dict

      :returns: **self** -- The fitted estimator.
      :rtype: DecoderEstimator



   .. py:method:: predict(X)

      Predict targets for the provided data.

      :param X: Samples to predict.
      :type X: array-like of shape (n_samples, n_features)

      :returns: **y_pred** -- Predicted target values per sample.
      :rtype: array-like of shape (n_samples,)



   .. py:method:: get_params(deep = True)

      Get parameters for this estimator.

      :param deep: If True, will return the parameters for this estimator and
                   contained subobjects that are estimators.
      :type deep: bool, default=True

      :returns: **params** -- Parameter names mapped to their values.
      :rtype: dict



   .. py:method:: set_params(**params)

      Set the parameters of this estimator.

      :param \*\*params: Estimator parameters.
      :type \*\*params: dict

      :returns: **self** -- The estimator instance.
      :rtype: DecoderEstimator



.. py:class:: EmbeddingExtractor

   Bases: :py:obj:`Protocol`


   Interface for pretrained or frozen feature extraction backbones.

   Embedding extractors typically represent foundation models or frozen
   neural networks that transform raw data into a fixed-dimensional
   vector space before classical decoding.


   .. py:method:: transform(X)

      Extract features from the provided data.

      :param X: The raw data to be transformed.
      :type X: array-like

      :returns: **embeddings** -- The extracted feature vectors.
      :rtype: array-like



   .. py:method:: get_embedding_info()

      Return technical metadata about the extractor and its output space.

      :returns: **info** -- A dictionary containing provider name, model name, pooling
                strategy, and output dimensionality.
      :rtype: dict



.. py:class:: NeuralTrainable

   Bases: :py:obj:`Protocol`


   Interface for trainable neural estimators with diagnostic metadata.

   This protocol exposes internal training states and histories for
   reporting and verification purposes.


   .. py:method:: get_training_history()

      Get the step-by-step training history (e.g., loss per epoch).

      :returns: **history** -- A list of diagnostic records, one per training iteration.
      :rtype: list of dict



   .. py:method:: get_checkpoint_manifest()

      Get information about saved model checkpoints.

      :returns: **manifest** -- Metadata including checkpoint paths and best-epoch indices.
      :rtype: dict



   .. py:method:: get_model_card_info()

      Get high-level model card metadata for the artifact registry.

      :returns: **info** -- Information about model architecture, training configuration,
                and hyperparameters.
      :rtype: dict



   .. py:method:: get_failure_diagnostics()

      Get technical diagnostics if training failed or diverged.

      :returns: **diagnostics** -- Information about gradients, NaN detection, or hardware state.
      :rtype: dict



   .. py:method:: get_artifact_metadata()

      Aggregate all diagnostic metadata into a single dictionary.

      :returns: **metadata** -- A serializable dictionary containing history, model card, and checkpoints.
      :rtype: dict