API Reference#

Core#

Core API module for the OpenModels library.

This module contains the SerializationManager class, which is the main interface for serializing and deserializing machine learning models using various formats.

class openmodels.core.SerializationManager(model_serializer: ModelSerializer)[source]#

Bases: object

Manage the serialization and deserialization of machine learning models.

This class coordinates the process of converting models to various formats and back, using specified model serializers and format converters.

Attributes:

model_serializerModelSerializer: The serializer used to convert models to and from dictionary representations.

deserialize(serialized_model: Any, format_name: str = 'json') → Any[source]#

Deserialize a model from the specified format.

Parameters:

serialized_modelAny: The serialized model data.
format_namestr, optional: The format of the serialized data (default is “json”).

Returns:

Any: The deserialized machine learning model.

Raises:

DeserializationError: If the format converter doesn’t return a dictionary or if there’s an error during deserialization.
UnsupportedFormatError: If the specified format_name is not supported.

Examples

>>> manager = SerializationManager(SklearnSerializer())
>>> deserialized_model = manager.deserialize(serialized_model, format_name="json")
>>> predictions = deserialized_model.predict(X_test)

load(file_path: str | Path, format_name: str = 'json') → Any[source]#

Load and deserialize a model from a file.

Parameters:

file_pathUnion[str, Path]: The path to the file containing the serialized model.
format_namestr, optional: The format of the serialized data (default is “json”).

Returns:

Any: The deserialized machine learning model.

Raises:

DeserializationError: If deserialization or file I/O fails.
UnsupportedFormatError: If the specified format is not supported.

Examples

>>> manager = SerializationManager(SklearnSerializer())
>>> loaded_model = manager.load("model.json", format_name="json")

save(model: Any, file_path: str | Path, format_name: str = 'json') → None[source]#

Save a model to a file in the specified format.

Parameters:

modelAny: The machine learning model to serialize and save.
file_pathUnion[str, Path]: The path to the file where the model will be saved.
format_namestr, optional: The target format (default is “json”).

Raises:

SerializationError: If there’s an error during serialization or file I/O.
UnsupportedFormatError: If the specified format is not supported.

Examples

>>> manager = SerializationManager(SklearnSerializer())
>>> model = LogisticRegression()
>>> manager.save(model, "model.json", format_name="json")

serialize(model: Any, format_name: str = 'json') → Any[source]#

Serialize a model to the specified format.

Parameters:

modelAny: The machine learning model to serialize.
format_namestr, optional: The target format (default is “json”).

Returns:

Any: The serialized model in the specified format.

Raises:

SerializationError: If the model serializer doesn’t return a dictionary or if there’s an error during serialization.
UnsupportedFormatError: If the specified format is not supported.

Examples

>>> manager = SerializationManager(SklearnSerializer())
>>> model = LogisticRegression()
>>> serialized_model = manager.serialize(model, format_name="json")

Protocols#

Protocol definitions for the OpenModels library.

This module defines the protocols (interfaces) that model serializers and format converters must implement to be compatible with the SerializationManager.

class openmodels.protocols.FormatConverter(*args, **kwargs)[source]#

Bases: Protocol

Protocol for format converters.

abstract static deserialize_from_format(formatted_data: Any) → Dict[str, Any][source]#

Convert data from a specific format to a dictionary.

Parameters:

formatted_dataAny: The data in the specific format.

Returns:

Dict[str, Any]: The dictionary representation of the data.

abstract static serialize_to_format(data: Dict[str, Any]) → Any[source]#

Convert a dictionary to a specific format.

Parameters:

dataDict[str, Any]: The dictionary to convert.

Returns:

Any: The data in the specific format.

class openmodels.protocols.ModelSerializer(*args, **kwargs)[source]#

Bases: Protocol

Protocol for model serializers.

abstract deserialize(data: Dict[str, Any]) → Any[source]#

Deserialize a model from a dictionary representation.

Parameters:

dataDict[str, Any]: The dictionary representation of the model.

Returns:

Any: The deserialized model.

abstract serialize(model: Any) → Dict[str, Any][source]#

Serialize a model to a dictionary representation.

Parameters:

modelAny: The model to serialize.

Returns:

Dict[str, Any]: A dictionary representation of the model.

Format Registry#

Format registry module for the OpenModels library.

This module provides a registry for format converters, allowing dynamic registration and retrieval of converters for different serialization formats.

class openmodels.format_registry.FormatRegistry[source]#

Bases: object

A registry for format converters.

This class manages the registration and retrieval of format converters, allowing the SerializationManager to support multiple serialization formats.

Attributes:

_convertersDict[str, Type[FormatConverter]]: A dictionary mapping format names to their respective converter classes.

classmethod get_converter(format_name: str) → Type[FormatConverter][source]#

Retrieve a format converter by name.

Parameters:

format_namestr: The name of the format to retrieve.

Returns:

Type[FormatConverter]: The converter class for the specified format.

Raises:

UnsupportedFormatError: If the specified format is not supported.

Examples

>>> json_converter = FormatRegistry.get_converter("json")
>>> serialized_data = json_converter.serialize_to_format(data_dict)

classmethod register(format_name: str, converter: Type[FormatConverter]) → None[source]#

Parameters:

format_namestr: The name of the format (e.g., “json”, “pickle”).
converterType[FormatConverter]: The converter class for the format.

Examples

>>> FormatRegistry.register("json", JSONConverter)

Serializers#

Sklearn Serializer#

Scikit-learn model serializer for the OpenModels library.

This module provides a serializer for scikit-learn models, allowing them to be converted to and from dictionary representations.

class openmodels.serializers.sklearn.sklearn_serializer.SklearnSerializer(custom_estimators: Callable[[...], Any] | List[Any] | Tuple[Any, ...] | Dict[str, Type[sklearn.base.BaseEstimator]] | None = None)[source]#

Bases: ModelSerializer, NumpySerializerMixin, ScipySerializerMixin

Serializer for scikit-learn estimators.

This class provides methods to convert scikit-learn estimators to and from dictionary representations, which can then be used with various format converters.

The serializer supports a wide range of scikit-learn estimators and handles the conversion of numpy arrays and other non-JSON-serializable types.

Parameters:

custom_estimatorscallable, list, tuple, or dict, optional

Optional collection of third-party or custom estimator classes to support during serialization and deserialization. This can be:

A callable returning an iterable or dict of (name, class) pairs (e.g., a function like all_estimators).
A list or tuple of (name, class) pairs.
A dict mapping estimator names to their classes.

These estimators are merged into the serializer’s internal registry for this instance only, allowing support for custom or external estimators without affecting the global registry.

Notes

For third-party packages compatible with scikit-learn, it is recommended to implement an all_estimators() utility following the scikit-learn API and template above. This enables automatic discovery and integration of custom estimators for serialization.

If you are maintaining a scikit-learn compatible package, let us know! We are happy to extend our testing to include your estimators, ensuring everything works smoothly and that we cover any unique types or patterns used in your library.

To request official support for your package, please open an issue at: Gnpd/openmodels#issues

References

[1]

scikit-learn developer guide: https://scikit-learn.org/stable/developers/develop.html

[2]

sklearn.utils.discovery.all_estimators: https://scikit-learn.org/stable/modules/generated/sklearn.utils.discovery.all_estimators.html

[3]

skltemplate.utils.discovery.all_estimators (project template): https://contrib.scikit-learn.org/project-template/generated/skltemplate.utils.discovery.all_estimators.html

static all_estimators(type_filter: str | None = None) → List[Tuple[str, Type[sklearn.base.BaseEstimator]]][source]#

Get all scikit-learn supported estimators.

Parameters:

type_filterstr, optional: If provided, filter estimators by type (e.g., ‘classifier’, ‘regressor’).

Returns:

list of tuple: List of (name, class) pairs for supported estimators.

deserialize(data: Dict[str, Any]) → sklearn.base.BaseEstimator[source]#

Deserialize a dictionary representation back into a scikit-learn estimator.

This method reconstructs a scikit-learn estimator from its dictionary representation, converting attributes back to their original types.

Parameters:

dataDict[str, Any]: The dictionary representation of the model.

Returns:

BaseEstimator: The deserialized scikit-learn estimator.

Raises:

UnsupportedEstimatorError: If the estimator class is not supported.

Examples

>>> serializer = SklearnSerializer()
>>> deserialized_model = serializer.deserialize(serialized_dict)
>>> predictions = deserialized_model.predict(X_test)

serialize(model: sklearn.base.BaseEstimator) → Dict[str, Any][source]#

Serialize a scikit-learn estimator to a dictionary.

This method extracts relevant attributes from the model, converts them to JSON-serializable types, and returns a dictionary representation of the model.

Parameters:

modelBaseEstimator: The scikit-learn estimator to serialize.

Returns:

Dict[str, Any]: A dictionary representation of the model.

Raises:

SerializationError: If there’s an error during serialization.

Examples

>>> from sklearn.linear_model import LogisticRegression
>>> from sklearn.datasets import make_classification
>>> X, y = make_classification(n_samples=100, n_features=20, n_classes=2)
>>> model = LogisticRegression().fit(X, y)
>>> serializer = SklearnSerializer()
>>> serialized_dict = serializer.serialize(model)

Converters#

JSON Converter#

JSON converter for the OpenModels library.

This module provides a converter for serializing to and from JSON format.

class openmodels.converters.json_converter.JSONConverter(*args, **kwargs)[source]#

Bases: FormatConverter

Converter for JSON format.

This class provides static methods to convert between dictionary representations and JSON strings.

static deserialize_from_format(formatted_data: str) → Dict[str, Any][source]#

Convert a JSON string to a dictionary.

Parameters:

formatted_datastr: The JSON string to convert.

Returns:

Dict[str, Any]: The dictionary representation of the JSON data.

Raises:

json.JSONDecodeError: If the input string is not valid JSON.

static serialize_to_format(data: Dict[str, Any]) → str[source]#

Convert a dictionary to a JSON string.

Parameters:

dataDict[str, Any]: The dictionary to convert.

Returns:

str: The JSON string representation of the data.

Pickle Converter#

Pickle converter for the OpenModels library.

This module provides a converter for serializing to and from pickle format.

Warning

Unpickling can execute arbitrary code. Only deserialize pickle data from sources you trust - see SECURITY.md. Prefer the JSON format for data from untrusted sources.

class openmodels.converters.pickle_converter.PickleConverter(*args, **kwargs)[source]#

Bases: FormatConverter

Converter for pickle format.

This class provides static methods to convert between dictionary representations and pickle byte strings.

Warning

deserialize_from_format calls pickle.loads(), which can execute arbitrary code as part of deserialization. Only use this converter with pickle data from sources you trust.

static deserialize_from_format(formatted_data: bytes) → Dict[str, Any][source]#

Convert a pickle byte string to a dictionary.

Parameters:

formatted_databytes: The pickle byte string to convert.

Returns:

Dict[str, Any]: The dictionary representation of the pickle data.

Raises:

pickle.UnpicklingError: If the input bytes cannot be unpickled.

Warns:

Unpickling can execute arbitrary code. Only call this with pickle data from a
source you trust.

static serialize_to_format(data: Dict[str, Any]) → bytes[source]#

Convert a dictionary to a pickle byte string.

Parameters:

dataDict[str, Any]: The dictionary to convert.

Returns:

bytes: The pickle byte string representation of the data.