Core API Reference 📖

Complete API reference for MLPotion's framework-agnostic core components.

Auto-Generated Documentation

This page is automatically populated with API documentation from the source code.

Protocols

mlpotion.core.protocols

Framework-agnostic protocols using Python 3.10+ type hints.

These protocols define interfaces that work across TensorFlow, PyTorch, and other frameworks.

Classes

DataLoader

Bases: Protocol[DatasetT]

Protocol for data loading components.

This protocol defines the interface for loading data into a framework-specific format. Any class that implements a load() method returning a dataset satisfies this protocol.

Type Parameters

DatasetT: The type of the dataset returned (e.g., tf.data.Dataset, torch.utils.data.DataLoader).

Example

class MyCSVLoader:
    def load(self) -> tf.data.Dataset:
        # Implementation details...
        return dataset

loader: DataLoader = MyCSVLoader()

Functions

load

load() -> DatasetT

Load data and return a framework-specific dataset.

Returns:

Name	Type	Description
DatasetT	DatasetT	The loaded dataset in a framework-specific format.

Source code in mlpotion/core/protocols.py

def load(self) -> DatasetT:
    """Load data and return a framework-specific dataset.

    Returns:
        DatasetT: The loaded dataset in a framework-specific format.
    """
    ...

DataTransformer

Bases: Protocol[DatasetT, ModelT]

Protocol for data transformation components.

This protocol defines the interface for transforming datasets using a model, commonly used for tasks like generating embeddings or pre-processing data.

Type Parameters

DatasetT: The type of the dataset. ModelT: The type of the model used for transformation.

Functions

transform

transform(
    dataset: DatasetT, model: ModelT, **kwargs: Any
) -> DatasetT

Transform a dataset using a model.

Parameters:

Name	Type	Description	Default
dataset	DatasetT	The input dataset to transform.	required
model	ModelT	The model to use for the transformation.	required
**kwargs	Any	Additional framework-specific arguments (e.g., batch_size, device).	{}

Returns:

Name	Type	Description
DatasetT	DatasetT	The transformed dataset.

Source code in mlpotion/core/protocols.py

def transform(
    self,
    dataset: DatasetT,
    model: ModelT,
    **kwargs: Any,
) -> DatasetT:
    """Transform a dataset using a model.

    Args:
        dataset: The input dataset to transform.
        model: The model to use for the transformation.
        **kwargs: Additional framework-specific arguments (e.g., batch_size, device).

    Returns:
        DatasetT: The transformed dataset.
    """
    ...

DatasetOptimizer

Bases: Protocol[DatasetT]

Protocol for dataset optimization components.

This protocol defines the interface for optimizing datasets, such as applying batching, caching, prefetching, or shuffling.

Type Parameters

DatasetT: The type of the dataset to be optimized.

Functions

optimize

optimize(dataset: DatasetT) -> DatasetT

Optimize a dataset for training or inference.

Parameters:

Name	Type	Description	Default
dataset	DatasetT	The input dataset to optimize.	required

Returns:

Name	Type	Description
DatasetT	DatasetT	The optimized dataset, ready for consumption by a model.

Source code in mlpotion/core/protocols.py

def optimize(self, dataset: DatasetT) -> DatasetT:
    """Optimize a dataset for training or inference.

    Args:
        dataset: The input dataset to optimize.

    Returns:
        DatasetT: The optimized dataset, ready for consumption by a model.
    """
    ...

ModelEvaluator

Bases: Protocol[ModelT, DatasetT]

Protocol for model evaluation components.

This protocol defines the interface for evaluating models.

Type Parameters

ModelT: The type of the model to be evaluated. DatasetT: The type of the dataset used for evaluation.

Functions

evaluate

evaluate(
    model: ModelT,
    dataset: DatasetT,
    config: EvaluationConfig,
) -> EvaluationResult

Evaluate a model on a given dataset.

Parameters:

Name	Type	Description	Default
model	ModelT	The model to evaluate.	required
dataset	DatasetT	The dataset to evaluate on.	required
config	EvaluationConfig	Configuration object containing evaluation parameters.	required

Returns:

Name	Type	Description
EvaluationResult	EvaluationResult	An object containing the evaluation metrics.

Source code in mlpotion/core/protocols.py

def evaluate(
    self,
    model: ModelT,
    dataset: DatasetT,
    config: EvaluationConfig,
) -> EvaluationResult:
    """Evaluate a model on a given dataset.

    Args:
        model: The model to evaluate.
        dataset: The dataset to evaluate on.
        config: Configuration object containing evaluation parameters.

    Returns:
        EvaluationResult: An object containing the evaluation metrics.
    """
    ...

ModelExporter

Bases: Protocol[ModelT]

Protocol for model export components.

This protocol defines the interface for exporting models to various formats for deployment.

Type Parameters

ModelT: The type of the model to be exported.

Functions

export

export(model: ModelT, config: ExportConfig) -> ExportResult

Export a model for serving or deployment.

Parameters:

Name	Type	Description	Default
model	ModelT	The model to export.	required
config	ExportConfig	Configuration object containing export parameters (path, format, etc.).	required

Returns:

Name	Type	Description
ExportResult	ExportResult	An object containing details about the exported model.

Source code in mlpotion/core/protocols.py

def export(
    self,
    model: ModelT,
    config: ExportConfig,
) -> ExportResult:
    """Export a model for serving or deployment.

    Args:
        model: The model to export.
        config: Configuration object containing export parameters (path, format, etc.).

    Returns:
        ExportResult: An object containing details about the exported model.
    """
    ...

ModelInspector

Bases: Protocol[ModelT]

Protocol for model inspection components.

This protocol defines the interface for inspecting models to extract metadata such as layer configuration, input/output shapes, and parameter counts.

Type Parameters

ModelT: The type of the model to be inspected.

Functions

inspect

inspect(model: ModelT) -> dict[str, Any]

Inspect a model and return structured metadata.

Parameters:

Name	Type	Description	Default
model	ModelT	The model to inspect.	required

Returns:

Type	Description
dict[str, Any]	dict[str, Any]: A dictionary containing model metadata (inputs, outputs, parameters, layers, etc.).

Source code in mlpotion/core/protocols.py

def inspect(self, model: ModelT) -> dict[str, Any]:
    """Inspect a model and return structured metadata.

    Args:
        model: The model to inspect.

    Returns:
        dict[str, Any]: A dictionary containing model metadata (inputs, outputs, parameters, layers, etc.).
    """
    ...

ModelPersistence

Bases: Protocol[ModelT]

Protocol for model persistence operations (save/load).

This protocol defines the interface for saving and loading models to/from disk.

Type Parameters

ModelT: The type of the model to be persisted.

Functions

load

load(**kwargs: Any) -> tuple[ModelT, dict[str, Any] | None]

Load a model from the configured path.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional framework-specific loading options.	{}

Returns:

Type	Description
tuple[ModelT, dict[str, Any] | None]	tuple[ModelT, dict[str, Any] | None]: A tuple containing the loaded model and optional metadata.

Source code in mlpotion/core/protocols.py

def load(self, **kwargs: Any) -> tuple[ModelT, dict[str, Any] | None]:
    """Load a model from the configured path.

    Args:
        **kwargs: Additional framework-specific loading options.

    Returns:
        tuple[ModelT, dict[str, Any] | None]: A tuple containing the loaded model and optional metadata.
    """
    ...

save

save(**kwargs: Any) -> None

Save a model to the configured path.

Parameters:

Name	Type	Description	Default
**kwargs	Any	Additional framework-specific saving options.	{}

Source code in mlpotion/core/protocols.py

def save(self, **kwargs: Any) -> None:
    """Save a model to the configured path.

    Args:
        **kwargs: Additional framework-specific saving options.
    """
    ...

ModelTrainer

Bases: Protocol[ModelT, DatasetT]

Protocol for model training components.

This protocol defines the standard interface for training models across different frameworks.

Type Parameters

ModelT: The type of the model to be trained. DatasetT: The type of the dataset used for training.

Functions

train

train(
    model: ModelT,
    dataset: DatasetT,
    config: TrainingConfig,
    validation_dataset: DatasetT | None = None,
) -> TrainingResult[ModelT]

Train a model using the provided dataset and configuration.

Parameters:

Name	Type	Description	Default
model	ModelT	The model instance to train.	required
dataset	DatasetT	The training dataset.	required
config	TrainingConfig	Configuration object containing training parameters (epochs, learning rate, etc.).	required
validation_dataset	DatasetT | None	Optional dataset for validation during training.	None

Returns:

Type	Description
TrainingResult[ModelT]	TrainingResult[ModelT]: An object containing the trained model, training history, and metrics.

Source code in mlpotion/core/protocols.py

def train(
    self,
    model: ModelT,
    dataset: DatasetT,
    config: TrainingConfig,
    validation_dataset: DatasetT | None = None,
) -> TrainingResult[ModelT]:
    """Train a model using the provided dataset and configuration.

    Args:
        model: The model instance to train.
        dataset: The training dataset.
        config: Configuration object containing training parameters (epochs, learning rate, etc.).
        validation_dataset: Optional dataset for validation during training.

    Returns:
        TrainingResult[ModelT]: An object containing the trained model, training history, and metrics.
    """
    ...

Result Types

mlpotion.core.results

Result types using dataclasses with Python 3.10+ features.

Classes

EvaluationResult dataclass

Result container for model evaluation operations.

Attributes:

Name	Type	Description
metrics	dict[str, float]	A dictionary of evaluation metric values.
config	Any	The configuration object used for this evaluation.
evaluation_time	float | None	The total time taken for evaluation in seconds.

Functions

get_metric

get_metric(name: str) -> float | None

Retrieve a specific metric value.

Parameters:

Name	Type	Description	Default
name	str	The name of the metric to retrieve.	required

Returns:

Type	Description
float | None	float | None: The value of the metric, or None if not found.

Source code in mlpotion/core/results.py

def get_metric(self, name: str) -> float | None:
    """Retrieve a specific metric value.

    Args:
        name: The name of the metric to retrieve.

    Returns:
        float | None: The value of the metric, or None if not found.
    """
    return self.metrics.get(name)

ExportResult dataclass

Result container for model export operations.

Attributes:

Name	Type	Description
export_path	str	The absolute path where the model was exported.
format	str	The format of the exported model (e.g., 'saved_model', 'onnx').
config	Any	The configuration object used for this export.
metadata	dict[str, Any]	Additional metadata generated during export.

InspectionResult dataclass

Result container for model inspection operations.

Attributes:

Name	Type	Description
name	str	The name of the model.
backend	str	The framework backend used (e.g., 'tensorflow', 'pytorch').
trainable	bool	Whether the model is trainable.
inputs	list[dict[str, Any]]	List of input specifications (shape, dtype, etc.).
input_names	list[str]	List of input names.
outputs	list[dict[str, Any]]	List of output specifications.
output_names	list[str]	List of output names.
parameters	dict[str, int]	Dictionary of parameter counts (total, trainable, non_trainable).
signatures	dict[str, Any]	Model signatures (specific to TensorFlow SavedModel).
layers	list[dict[str, Any]]	List of layer details (name, class, args).

LoadingResult dataclass

Bases: Generic[ModelT]

Result from model loading.

TrainingResult dataclass

Bases: Generic[ModelT]

Result container for model training operations.

This dataclass encapsulates all relevant information produced during a model training session.

Attributes:

Name	Type	Description
model	ModelT	The trained model instance.
history	dict[str, list[float]]	A dictionary mapping metric names to lists of values per epoch.
metrics	dict[str, float]	A dictionary of the final metric values after training.
config	Any	The configuration object used for this training session.
training_time	float | None	The total time taken for training in seconds.
best_epoch	int | None	The epoch number where the best performance was achieved (if applicable).

Functions

get_history

get_history(metric: str) -> list[float] | None

Retrieve the history of a specific metric over epochs.

Parameters:

Name	Type	Description	Default
metric	str	The name of the metric to retrieve history for.	required

Returns:

Type	Description
list[float] | None	list[float] | None: The list of metric values per epoch, or None if not found.

Source code in mlpotion/core/results.py

def get_history(self, metric: str) -> list[float] | None:
    """Retrieve the history of a specific metric over epochs.

    Args:
        metric: The name of the metric to retrieve history for.

    Returns:
        list[float] | None: The list of metric values per epoch, or None if not found.
    """
    return self.history.get(metric)

get_metric

get_metric(name: str) -> float | None

Retrieve a specific final metric value.

Parameters:

Name	Type	Description	Default
name	str	The name of the metric to retrieve.	required

Returns:

Type	Description
float | None	float | None: The value of the metric, or None if not found.

Source code in mlpotion/core/results.py

def get_metric(self, name: str) -> float | None:
    """Retrieve a specific final metric value.

    Args:
        name: The name of the metric to retrieve.

    Returns:
        float | None: The value of the metric, or None if not found.
    """
    return self.metrics.get(name)

TransformationResult dataclass

Result from data transformation.

Configurations

mlpotion.core.config

Framework-agnostic base configuration models using Pydantic 2.x.

This module contains only truly framework-agnostic configuration classes. Framework-specific configurations should be defined in their respective framework modules (keras, tensorflow, pytorch).

Classes

EvaluationConfig

Bases: BaseSettings

Base configuration for model evaluation.

Attributes:

Name	Type	Description
batch_size	int	Batch size for evaluation (must be >= 1).
verbose	int	Verbosity level (0=silent, 1=progress bar, 2=one line per epoch).
framework_options	dict[str, Any]	Dictionary for framework-specific options.

ExportConfig

Bases: BaseSettings

Base configuration for model export.

Attributes:

Name	Type	Description
export_path	str	Destination path for the exported model.
format	str	Format identifier for the export (e.g., 'saved_model', 'onnx').
include_optimizer	bool	Whether to include the optimizer state in the export.
metadata	dict[str, Any]	Additional metadata to include with the export.

TrainingConfig

Bases: BaseSettings

Base configuration for model training.

This class defines the standard configuration parameters for training models. Framework-specific configurations should inherit from this class.

Attributes:

Name	Type	Description
epochs	int	Number of training epochs (must be >= 1).
batch_size	int	Batch size for training (must be >= 1).
learning_rate	float	Learning rate for the optimizer (must be > 0.0).
validation_split	float	Fraction of data to use for validation (0.0 to 1.0).
shuffle	bool	Whether to shuffle the training data.
verbose	int	Verbosity level (0=silent, 1=progress bar, 2=one line per epoch).
framework_options	dict[str, Any]	Dictionary for framework-specific options that don't fit standard fields.

Exceptions

mlpotion.core.exceptions

Exception hierarchy for MLPotion.

Classes

ConfigurationError

Bases: MLPotionError

Raised when there is an issue with the provided configuration.

DataLoadingError

Bases: MLPotionError

Raised when an error occurs during data loading or preprocessing.

DataTransformationError

Bases: MLPotionError

Raised when an error occurs during data transformation operations.

EvaluationError

Bases: MLPotionError

Raised when an error occurs during model evaluation.

ExportError

Bases: MLPotionError

Raised when an error occurs during model export operations.

FrameworkNotInstalledError

Bases: MLPotionError

Raised when a required framework (e.g., TensorFlow, PyTorch) is not installed or cannot be imported.

MLPotionError

Bases: Exception

Base exception for all MLPotion errors.

ModelEvaluatorError

Bases: MLPotionError

Raised when an error occurs specifically within a ModelEvaluator component.

ModelExporterError

Bases: MLPotionError

Raised when an error occurs specifically within a ModelExporter component.

ModelInspectorError

Bases: MLPotionError

Raised when an error occurs during model inspection.

ModelPersistenceError

Bases: MLPotionError

Raised when an error occurs during model saving or loading.

ModelTrainerError

Bases: MLPotionError

Raised when an error occurs specifically within a ModelTrainer component.

TrainingError

Bases: MLPotionError

Raised when an error occurs during the model training process.

ValidationError

Bases: MLPotionError

Raised when data or model validation fails.

Utilities

Framework Detection

mlpotion.utils.framework

Framework detection and validation utilities.

Classes

FrameworkChecker

Utility class to check availability of ML frameworks.

Functions

is_available classmethod

is_available(framework: FrameworkName) -> bool

Check whether a framework is installed and importable.

Parameters:

Name	Type	Description	Default
framework	FrameworkName	Framework identifier supported by this checker.	required

Returns:

Type	Description
bool	True if the framework can be imported, otherwise False.

Raises:

Type	Description
ValueError	If the provided framework is not known.

Example

if FrameworkChecker.is_available("torch"):
    print("PyTorch is installed!")
else:
    print("PyTorch is missing.")

Source code in mlpotion/utils/framework.py

@classmethod
def is_available(cls, framework: FrameworkName) -> bool:
    """Check whether a framework is installed and importable.

    Args:
        framework: Framework identifier supported by this checker.

    Returns:
        True if the framework can be imported, otherwise False.

    Raises:
        ValueError: If the provided framework is not known.

    Example:
        ```python
        if FrameworkChecker.is_available("torch"):
            print("PyTorch is installed!")
        else:
            print("PyTorch is missing.")
        ```
    """
    if framework not in cls._FRAMEWORK_IMPORTS:
        msg = f"Unsupported framework: {framework}"
        logger.error(msg)
        raise ValueError(msg)

    module_name = cls._FRAMEWORK_IMPORTS[framework]

    try:
        import_module(module_name)
        return True
    except ImportError:
        return False

Functions

get_available_frameworks

get_available_frameworks() -> list[FrameworkName]

Get list of available frameworks.

Returns:

Type	Description
list[FrameworkName]	List of framework names that are installed

Source code in mlpotion/utils/framework.py

def get_available_frameworks() -> list[FrameworkName]:
    """Get list of available frameworks.

    Returns:
        List of framework names that are installed
    """
    frameworks: list[FrameworkName] = list(FrameworkChecker._FRAMEWORK_IMPORTS.keys())
    return [f for f in frameworks if is_framework_available(f)]

require_framework

require_framework(
    framework: FrameworkName, install_command: str
) -> None

Require a framework to be installed.

Parameters:

Name	Type	Description	Default
framework	FrameworkName	Framework name	required
install_command	str	Installation command to show in error	required

Raises:

Type	Description
FrameworkNotInstalledError	If framework is not installed

Source code in mlpotion/utils/framework.py

def require_framework(framework: FrameworkName, install_command: str) -> None:
    """Require a framework to be installed.

    Args:
        framework: Framework name
        install_command: Installation command to show in error

    Raises:
        FrameworkNotInstalledError: If framework is not installed
    """
    if not is_framework_available(framework):
        raise FrameworkNotInstalledError(
            f"{framework} is not installed. "
            f"Install it with: poetry add {install_command}"
        )

Decorators

mlpotion.utils.decorators

Classes

trycatch

trycatch(
    error: Type[Exception], success_msg: str | None = None
) -> None

Decorator for wrapping methods with unified exception handling and logging.

Parameters:

Name	Type	Description	Default
error	Type[Exception]	Exception type to raise when unexpected errors occur.	required
success_msg	str | None	Optional success message to log on method completion.	None

Example

@trycatch(error=DataLoadingError, success_msg="Dataset loaded")
def load(self):
    ...

Source code in mlpotion/utils/decorators.py

def __init__(
    self,
    error: Type[Exception],
    success_msg: str | None = None,
) -> None:
    self.error = error
    self.success_msg = success_msg

---

For framework-specific APIs, see the respective framework documentation