coco_pipe.decoding.interfaces#

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#

`DecoderEstimator`	Protocol for scikit-learn-compatible decoding estimators.
`EmbeddingExtractor`	Interface for pretrained or frozen feature extraction backbones.
`NeuralTrainable`	Interface for trainable neural estimators with diagnostic metadata.

Module Contents#

class coco_pipe.decoding.interfaces.DecoderEstimator#

Bases: 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.

fit(X, y=None, **fit_params)#

Fit the estimator to the provided data.

Parameters:

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

Returns:

self – The fitted estimator.

Return type:

DecoderEstimator

predict(X)#

Predict targets for the provided data.

Parameters:: X (array-like of shape (n_samples, n_features)) – Samples to predict.
Returns:: y_pred – Predicted target values per sample.
Return type:: array-like of shape (n_samples,)

get_params(deep=True)#

Get parameters for this estimator.

Parameters:: deep (bool, default=True) – If True, will return the parameters for this estimator and contained subobjects that are estimators.
Returns:: params – Parameter names mapped to their values.
Return type:: dict

set_params(**params)#

Set the parameters of this estimator.

Parameters:: **params (dict) – Estimator parameters.
Returns:: self – The estimator instance.
Return type:: DecoderEstimator

class coco_pipe.decoding.interfaces.EmbeddingExtractor#

Bases: 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.

transform(X)#

Extract features from the provided data.

Parameters:: X (array-like) – The raw data to be transformed.
Returns:: embeddings – The extracted feature vectors.
Return type:: array-like

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.
Return type:: dict

class coco_pipe.decoding.interfaces.NeuralTrainable#

Bases: Protocol

Interface for trainable neural estimators with diagnostic metadata.

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

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.
Return type:: list of dict

get_checkpoint_manifest()#

Get information about saved model checkpoints.

Returns:: manifest – Metadata including checkpoint paths and best-epoch indices.
Return type:: dict

get_model_card_info()#

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

Returns:: info – Information about model architecture, training configuration, and hyperparameters.
Return type:: dict

get_failure_diagnostics()#

Get technical diagnostics if training failed or diverged.

Returns:: diagnostics – Information about gradients, NaN detection, or hardware state.
Return type:: dict

get_artifact_metadata()#

Aggregate all diagnostic metadata into a single dictionary.

Returns:: metadata – A serializable dictionary containing history, model card, and checkpoints.
Return type:: dict