ictonyx.core

Model wrappers: KerasModelWrapper, ScikitLearnModelWrapper, PyTorchModelWrapper, HuggingFaceModelWrapper.

ictonyx.core.accuracy_score(y_true, y_pred)

Numpy fallback when sklearn is not installed.

class ictonyx.core.TrainingResult(history, params=<factory>)

Bases: object

Standardized training output from any model wrapper.

Every wrapper’s fit() method must produce one of these. Replaces the Keras-specific .history.history probing pattern.

Parameters:

• history (Dict[str, list])

• params (Dict[str, Any])

history

Dict mapping metric names to lists of per-epoch values. Keys follow the convention: ‘loss’, ‘accuracy’, ‘val_loss’, ‘val_accuracy’, or any custom metric name.

Type:

Dict[str, list]

params

Training parameters (epochs, batch_size, etc.)

Type:

Dict[str, Any]

history: Dict[str, list]

params: Dict[str, Any]

class ictonyx.core.BaseModelWrapper(model, model_id='')

Bases: ABC

Abstract base class for wrapping ML models with a common interface.

All model wrappers (Keras, scikit-learn, PyTorch) inherit from this class and implement its abstract methods. The wrapper provides:

• A consistent fit / predict / evaluate / assess API.

• Automatic resource cleanup via cleanup().

• A standardized TrainingResult output from fit().

• Memory tracking via MemoryManager.

Subclasses must implement: fit(), predict(), predict_proba(), evaluate(), assess(), save_model(), load_model(), and _cleanup_implementation().

Parameters:

• model (Any) – The underlying model object (Keras Model, sklearn estimator, PyTorch Module, etc.).

• model_id (str) – An optional string identifier for logging and display.

training_result: TrainingResult | None

predictions: ndarray | None

cleanup()

Clean up resources used by this model.

abstractmethod fit(train_data, validation_data=None, **kwargs)

Trains (fits) the encapsulated model on the provided data.

This is an abstract method that must be implemented by concrete subclasses (e.g., KerasModelWrapper, ScikitLearnModelWrapper). The implementation is responsible for handling its specific data format (e.g., tf.data.Dataset vs. numpy arrays) and storing the training history (if any) in the self.training_result attribute.

Parameters:

• train_data (Any) – The data to train the model on. The required format is defined by the subclass (e.g., a tuple (X, y) or a tf.data.Dataset).

• validation_data (Optional[Any], optional) – The data to use for validation during training. The format should be compatible with train_data. Defaults to None.

• **kwargs – Additional, framework-specific arguments to be passed to the model’s underlying .fit() method (e.g., epochs, batch_size, callbacks).

abstractmethod predict(data, **kwargs)

Generates predictions for the given input data.

This abstract method must be implemented by subclasses. It is responsible for running the model’s prediction logic.

The implementation should: 1. Generate raw predictions from self.model. 2. For classification models, convert probabilities or logits into

final class indices (e.g., np.argmax(…, axis=1)).

3. For regression models, return the predicted values directly.

4. Store the final predictions in the self.predictions attribute.

5. Return the final predictions.

Parameters:

• data (np.ndarray) – The input data to generate predictions for.

• **kwargs – Additional, framework-specific arguments to be passed to the model’s underlying .predict() method.

Returns:

An array of predictions. For classification, this should be class indices (integers). For regression, this should be the predicted values (floats).

Return type:

np.ndarray

abstractmethod predict_proba(data, **kwargs)

Generates class probability predictions for the given input data.

This abstract method is only applicable for classification models. It must be implemented by subclasses that support probability outputs.

The implementation should: 1. Generate raw probability scores from self.model. 2. Ensure the output is a 2D array of shape (n_samples, n_classes). 3. For binary models with a single sigmoid output, this means

stacking (1-p, p) to create the 2D array.

4. For multi-class models, this is typically the direct output of a softmax layer.

Parameters:

• data (np.ndarray) – The input data to generate probabilities for.

• **kwargs – Additional, framework-specific arguments to be passed to the model’s underlying .predict_proba() method.

Returns:

A 2D array of shape (n_samples, n_classes) containing the probability for each class.

Return type:

np.ndarray

Raises:

• NotImplementedError – If the underlying model does not support

• probability predictions (e.g., SVM with linear kernel). –

• ValueError – If called on a regression model.

abstractmethod evaluate(data, **kwargs)

Evaluates the encapsulated model on a given dataset (e.g., test set).

This abstract method must be implemented by subclasses. Unlike predict, the data argument here is expected to contain both features and true labels in whatever format the underlying framework requires (e.g., a tuple (X, y) or a tf.data.Dataset).

Parameters:

• data (Any) – The data to evaluate the model on, including features and true labels.

• **kwargs – Additional, framework-specific arguments to be passed to the model’s underlying .evaluate() method.

Returns:

A dictionary of metrics, where keys are the metric names (e.g., ‘loss’, ‘accuracy’) and values are the scalar metric values.

Return type:

Dict[str, Any]

abstractmethod assess(true_labels)

Provides a quick assessment of model performance using stored predictions.

This method is typically called after predict() has been run. It compares the stored self.predictions against a set of true labels to calculate simple, high-level metrics (like accuracy).

This differs from evaluate(), which often runs the model’s built-in evaluation method on a dataset.

Parameters:

true_labels (np.ndarray) – A 1D array of the true ground-truth labels, corresponding to the stored self.predictions.

Returns:

A simple dictionary of one or more assessment metrics, e.g., {‘accuracy’: 0.95}.

Return type:

Dict[str, float]

Raises:

ValueError – If predict() has not been called yet and self.predictions is None.

abstractmethod save_model(path)

Saves the encapsulated model to a specified path.

This abstract method must be implemented by subclasses. It is responsible for serializing the inner model (e.g., the Keras model or scikit-learn estimator) and saving it to disk in the appropriate format (e.g., HDF5, pickle).

Parameters:

path (str) – The file path (or directory path, depending on the framework) where the model should be saved.

abstractmethod classmethod load_model(path)

Loads a model from a file and wraps it in a new class instance.

This abstract class method must be implemented by subclasses. It is responsible for deserializing a model from disk and returning a new, fully-functional instance of the wrapper class (e.g., KerasModelWrapper(loaded_keras_model)).

Parameters:

path (str) – The file path (or directory path) from which to load the model.

Returns:

A new instance of the concrete wrapper class (e.g., KerasModelWrapper) containing the loaded model.

Return type:

BaseModelWrapper

get_memory_report()

Get comprehensive memory usage report (available on all model wrappers).

Return type:

Dict[str, Any]

check_memory_and_cleanup_if_needed()

Run cleanup and report if significant memory was freed.

Returns a summary dict if more than 50 MB was freed, otherwise None.

Return type:

Dict[str, Any] | None