# Copyright (c) 2025 Oracle and/or its affiliates.
|
#
|
# This program is free software; you can redistribute it and/or modify
|
# it under the terms of the GNU General Public License, version 2.0, as
|
# published by the Free Software Foundation.
|
#
|
# This program is designed to work with certain software (including
|
# but not limited to OpenSSL) that is licensed under separate terms,
|
# as designated in a particular file or component or in included license
|
# documentation. The authors of MySQL hereby grant you an
|
# additional permission to link the program and your derivative works
|
# with the separately licensed software that they have either included with
|
# the program or referenced in the documentation.
|
#
|
# Without limiting anything contained in the foregoing, this file,
|
# which is part of MySQL Connector/Python, is also subject to the
|
# Universal FOSS Exception, version 1.0, a copy of which can be found at
|
# http://oss.oracle.com/licenses/universal-foss-exception.
|
#
|
# This program is distributed in the hope that it will be useful, but
|
# WITHOUT ANY WARRANTY; without even the implied warranty of
|
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
# See the GNU General Public License, version 2.0, for more details.
|
#
|
# You should have received a copy of the GNU General Public License
|
# along with this program; if not, write to the Free Software Foundation, Inc.,
|
# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
|
"""Generic transformer utilities for MySQL Connector/Python.
|
|
Provides a scikit-learn compatible Transformer using HeatWave for fit/transform
|
and scoring operations.
|
"""
|
from typing import Optional, Union
|
|
import numpy as np
|
import pandas as pd
|
from sklearn.base import TransformerMixin
|
|
from mysql.ai.ml.base import MyBaseMLModel
|
from mysql.ai.ml.model import ML_TASK
|
from mysql.ai.utils import copy_dict
|
from mysql.connector.abstracts import MySQLConnectionAbstract
|
|
|
class MyGenericTransformer(MyBaseMLModel, TransformerMixin):
|
"""
|
MySQL HeatWave scikit-learn compatible generic transformer.
|
|
Can be used as the transformation step in an sklearn pipeline. Implements fit, transform,
|
explain, and scoring capability, passing options for server-side transform logic.
|
|
Args:
|
db_connection (MySQLConnectionAbstract): Active MySQL connector database connection.
|
task (str): ML task type for transformer (default: "classification").
|
score_metric (str): Scoring metric to request from backend (default: "balanced_accuracy").
|
model_name (str, optional): Custom name for the deployed model.
|
fit_extra_options (dict, optional): Extra fit options.
|
transform_extra_options (dict, optional): Extra options for transformations.
|
score_extra_options (dict, optional): Extra options for scoring.
|
|
Attributes:
|
score_metric (str): Name of the backend metric to use for scoring
|
(e.g. "balanced_accuracy").
|
score_extra_options (dict): Dictionary of optional scoring parameters;
|
passed to backend score.
|
transform_extra_options (dict): Dictionary of inference (/predict)
|
parameters for the backend.
|
fit_extra_options (dict): See MyBaseMLModel.
|
_model (MyModel): Underlying interface for database model operations.
|
|
Methods:
|
fit(X, y): Fit the underlying model using the provided features/targets.
|
transform(X): Transform features using the backend model.
|
score(X, y): Score data using backend metric and options.
|
"""
|
|
def __init__(
|
self,
|
db_connection: MySQLConnectionAbstract,
|
task: Union[str, ML_TASK] = ML_TASK.CLASSIFICATION,
|
score_metric: str = "balanced_accuracy",
|
model_name: Optional[str] = None,
|
fit_extra_options: Optional[dict] = None,
|
transform_extra_options: Optional[dict] = None,
|
score_extra_options: Optional[dict] = None,
|
):
|
"""
|
Initialize transformer with required and optional arguments.
|
|
Args:
|
db_connection: Active MySQL backend database connection.
|
task: ML task type for transformer.
|
score_metric: Requested backend scoring metric.
|
model_name: Optional model name for storage.
|
fit_extra_options: Optional extra options for fitting.
|
transform_extra_options: Optional extra options for transformation/inference.
|
score_extra_options: Optional extra scoring options.
|
|
Raises:
|
DatabaseError:
|
If a database connection issue occurs.
|
If an operational error occurs during execution.
|
"""
|
MyBaseMLModel.__init__(
|
self,
|
db_connection,
|
task,
|
model_name=model_name,
|
fit_extra_options=fit_extra_options,
|
)
|
|
self.score_metric = score_metric
|
self.score_extra_options = copy_dict(score_extra_options)
|
|
self.transform_extra_options = copy_dict(transform_extra_options)
|
|
def transform(
|
self, X: pd.DataFrame
|
) -> pd.DataFrame: # pylint: disable=invalid-name
|
"""
|
Transform input data to model predictions using the underlying helper.
|
|
Args:
|
X: DataFrame of features to predict/transform.
|
|
Returns:
|
pd.DataFrame: Results of transformation as returned by backend.
|
|
Raises:
|
DatabaseError:
|
If provided options are invalid or unsupported,
|
or if the model is not initialized, i.e., fit or import has not
|
been called
|
If a database connection issue occurs.
|
If an operational error occurs during execution.
|
"""
|
return self._model.predict(X, options=self.transform_extra_options)
|
|
def score(
|
self,
|
X: Union[pd.DataFrame, np.ndarray], # pylint: disable=invalid-name
|
y: Union[pd.DataFrame, np.ndarray],
|
) -> float:
|
"""
|
Score the transformed data using the backend scoring interface.
|
|
Args:
|
X: Transformed features.
|
y: Target labels or data for scoring.
|
|
Returns:
|
float: Score based on backend metric.
|
|
Raises:
|
DatabaseError:
|
If provided options are invalid or unsupported,
|
or if the model is not initialized, i.e., fit or import has not
|
been called
|
If a database connection issue occurs.
|
If an operational error occurs during execution.
|
"""
|
return self._model.score(
|
X, y, self.score_metric, options=self.score_extra_options
|
)
|
