pdstools.infinity.resources.prediction_studio.local_model_utils =============================================================== .. py:module:: pdstools.infinity.resources.prediction_studio.local_model_utils Attributes ---------- .. autoapisummary:: pdstools.infinity.resources.prediction_studio.local_model_utils.logger pdstools.infinity.resources.prediction_studio.local_model_utils.PEGA_METADATA Exceptions ---------- .. autoapisummary:: pdstools.infinity.resources.prediction_studio.local_model_utils.ONNXModelCreationError pdstools.infinity.resources.prediction_studio.local_model_utils.ONNXModelValidationError Classes ------- .. autoapisummary:: pdstools.infinity.resources.prediction_studio.local_model_utils.OutcomeType pdstools.infinity.resources.prediction_studio.local_model_utils.Predictor pdstools.infinity.resources.prediction_studio.local_model_utils.Output pdstools.infinity.resources.prediction_studio.local_model_utils.Metadata pdstools.infinity.resources.prediction_studio.local_model_utils.PMMLModel pdstools.infinity.resources.prediction_studio.local_model_utils.H2OModel pdstools.infinity.resources.prediction_studio.local_model_utils.ONNXModel Module Contents --------------- .. py:data:: logger .. py:data:: PEGA_METADATA :value: 'pegaMetadata' .. py:class:: OutcomeType(*args, **kwds) Bases: :py:obj:`enum.Enum` Supported outcome types for local Prediction Studio model metadata. .. py:attribute:: BINARY :value: 'binary' .. py:attribute:: CATEGORICAL :value: 'categorical' .. py:attribute:: CONTINUOUS :value: 'continuous' .. py:class:: Predictor(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` A single predictor (feature) in an ONNX model. **Automatic name derivation** — When *pega_property* is supplied (e.g. ``".Customer.Age"``) and *name* is omitted, the predictor ``name`` is automatically set to the leaf segment of the property path (``"Age"``). Pega Prediction Studio auto‑maps predictors by matching ``name`` against its data‑model properties, so this guarantees correct field mapping on upload without any manual work. If *name* is provided explicitly it is always used as‑is. .. seealso:: :py:obj:`Metadata.build_predictor_list` Batch‑build predictors from a list of Pega property paths or plain feature names. .. py:attribute:: name :type: str | None :value: None .. py:attribute:: index :type: int | None :value: None .. py:attribute:: input_name :type: str | None :value: None .. py:attribute:: data_type :type: str :value: None .. py:attribute:: pega_property :type: str | None :value: None .. py:method:: validate_input_name(v) .. py:method:: validate_name(v) .. py:method:: validate_index(v) .. py:method:: validate_data_type(v) .. py:class:: Output(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Model output metadata stored in the embedded Pega metadata block. .. py:attribute:: possible_values :type: list[str | int | float] :value: None .. py:attribute:: label_name :type: str | None :value: None .. py:attribute:: score_name :type: str | None :value: None .. py:attribute:: min_value :type: float | None :value: None .. py:attribute:: max_value :type: float | None :value: None .. py:method:: validate_label_name(v) .. py:class:: Metadata(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Top-level Pega metadata embedded in an ONNX model. .. py:attribute:: type :type: OutcomeType | None :value: None .. py:attribute:: predictor_list :type: list[Predictor] :value: None .. py:attribute:: output :type: Output | None :value: None .. py:attribute:: modeling_technique :type: str | None :value: None .. py:attribute:: internal :type: bool | None :value: None .. py:attribute:: file_source :type: str | None :value: None .. py:attribute:: objective :type: str | None :value: None .. py:attribute:: rule_set :type: str | None :value: None .. py:attribute:: rule_set_version :type: str | None :value: None .. py:attribute:: predict_method_uses_name_value_pair :type: bool | None :value: None .. py:attribute:: model_version :type: str | None :value: None .. py:attribute:: created_by :type: str | None :value: None .. py:attribute:: created_date :type: str | None :value: None .. py:attribute:: last_modified_date :type: str | None :value: None .. py:attribute:: training_dataset :type: str | None :value: None .. py:attribute:: experiment_id :type: str | None :value: None .. py:attribute:: parent_model_id :type: str | None :value: None .. py:attribute:: baseline_auc :type: float | None :value: None .. py:attribute:: baseline_accuracy :type: float | None :value: None .. py:attribute:: performance_threshold :type: float | None :value: None .. py:method:: validate_type(v, values) .. py:method:: validate_output(v, values) .. py:method:: to_json() -> str .. py:method:: from_json(json_str: str) -> Metadata :classmethod: .. py:method:: build_predictor_list(features: list[str], input_name: str = 'features', *, data_types: list[str] | dict[str, str] | None = None) -> list[Predictor] :staticmethod: Build a predictor list from feature names or Pega property paths. This is the **recommended** one‑liner for constructing predictors. Each entry in ``features`` can be a **Pega property path** starting with ``"."`` (for example ``".Customer.Age"``). The leaf segment becomes the predictor ``name`` (``"Age"``) and the full path is stored as ``pega_property`` so Pega Prediction Studio auto-maps the field on upload. Each entry can also be a **plain feature name** (for example ``"Age"``). In that case the value is used as-is for ``name`` and ``pega_property`` is left unset. Indices are assigned automatically (1‑based) in the order the features appear. :param features: Ordered list of feature identifiers. The order **must** match the column order in the ONNX input tensor. Accepts any mix of plain names and Pega property paths. :param input_name: Name of the ONNX input node. Default ``"features"``. :param data_types: Optional type annotations for features. Accepts either a **list** of ``"Numeric"`` / ``"Symbolic"`` values, one per feature and matching ``features`` length, or a **dict** mapping feature *names* (the leaf segment for Pega paths) to ``"Numeric"`` or ``"Symbolic"``. Only the features present in the dict are overridden; the rest default to ``"Numeric"``. When ``None`` every feature defaults to ``"Numeric"``. :rtype: list[Predictor] .. rubric:: Examples >>> # Using Pega property paths (recommended for auto-mapping): >>> Metadata.build_predictor_list( ... [".Customer.Age", ".Customer.Tenure", ".Customer.MonthlyCharges"], ... ) # doctest: +SKIP >>> # Using plain feature names: >>> Metadata.build_predictor_list(["Age", "Tenure", "MonthlyCharges"]) ... # doctest: +SKIP >>> # Sparse overrides via dict: >>> Metadata.build_predictor_list( ... [".Customer.Age", ".Customer.ContractType"], ... data_types={"ContractType": "Symbolic"}, ... ) # doctest: +SKIP .. py:exception:: ONNXModelCreationError Bases: :py:obj:`Exception` Exception for errors during ONNX conversion and save. .. py:exception:: ONNXModelValidationError Bases: :py:obj:`pdstools.infinity.resources.prediction_studio.base.ModelValidationError` Exception for errors during ONNX validation. .. py:class:: PMMLModel(file_path: str) Bases: :py:obj:`pdstools.infinity.resources.prediction_studio.base.LocalModel` Wrapper around a PMML file path. .. py:attribute:: file_path :type: str .. py:method:: get_file_path() -> str Returns the file path of the model. :returns: **str** :rtype: The file path of the model. .. py:class:: H2OModel(file_path: str) Bases: :py:obj:`pdstools.infinity.resources.prediction_studio.base.LocalModel` Wrapper around an H2O model file path. .. py:attribute:: file_path :type: str .. py:method:: get_file_path() -> str Returns the file path of the model. :returns: **str** :rtype: The file path of the model. .. py:class:: ONNXModel(model: onnx.ModelProto) Bases: :py:obj:`pdstools.infinity.resources.prediction_studio.base.LocalModel` Wrapper around an in-memory ONNX model plus Pega metadata helpers. .. py:method:: from_onnx_proto(model: onnx.ModelProto) -> ONNXModel :classmethod: Creates an ONNXModel object. :param model: An onnx ModelProto object :type model: ModelProto :returns: An instance of the ONNXModel class. :rtype: ONNXModel :raises ImportError: If the optional dependencies for ONNX Conversion are not installed. :raises ONNXModelCreationError: If the ONNXModel object cannot be created. .. py:method:: from_sklearn_pipeline(model: sklearn.pipeline.Pipeline, initial_types: list) -> ONNXModel :classmethod: Creates an ONNXModel object. :param model: A sklearn Pipeline object :type model: Pipeline :param initial_types: A list of initial types for the model's input variables if the model is a Sklearn Pipeline object. :type initial_types: list :returns: An instance of the ONNXModel class. :rtype: ONNXModel :raises ImportError: If the optional dependencies for ONNX Conversion are not installed. :raises ONNXModelCreationError: If the ONNXModel object cannot be created. .. py:method:: from_pytorch(model, dummy_input, *, input_names: list[str] | None = None, output_names: list[str] | None = None, opset_version: int = 17, fixed_batch_size: bool = True) -> ONNXModel :classmethod: Create an ONNXModel from a PyTorch ``nn.Module``. The model is exported via ``torch.onnx.export`` with static shapes. When *fixed_batch_size* is ``True`` (the default), any remaining dynamic dimensions are replaced with a batch size of 1 so that the resulting ONNX file is accepted by Pega Prediction Studio. :param model: A PyTorch ``nn.Module`` (already in eval mode is recommended). :param dummy_input: Example input tensor(s) matching the model's forward signature. :param input_names: Optional list of ONNX input node names. Defaults to ``["input"]``. :param output_names: Optional list of ONNX output node names. Defaults to ``["output"]``. :param opset_version: ONNX opset version. Default ``17``. :param fixed_batch_size: Replace dynamic dimensions with batch size 1. :rtype: ONNXModel :raises ONNXModelCreationError: If PyTorch is not installed or the export fails. .. py:method:: get_metadata() -> Metadata | None Return the embedded ``Metadata`` or ``None`` if absent. .. py:method:: add_metadata(metadata: Metadata) -> ONNXModel Adds metadata to the ONNX model. :param metadata: The metadata to be added. :type metadata: Meta :returns: The ONNXModel object with the added metadata. :rtype: ONNXModel :raises ImportError: If the optional dependencies for ONNX Metadata addition are not installed. .. py:method:: validate() -> bool Validates an ONNX model. :raises ImportError: If the optional dependencies for ONNX Validation are not installed. :raises ONNXModelValidationError: If the model is invalid or if the validation process fails. .. py:method:: run(test_data: dict) Run the prediction using the provided test data. :param test_data: The test data to be used for prediction. It is a dictionary where each key is a column name from the dataset, and each value is a NumPy array representing the column data as a vector. :type test_data: dict :returns: The prediction result. :rtype: Any .. rubric:: Examples ``test_data`` should look like: .. code-block:: python { "column1": array([[value1], [value2], [value3]]), "column2": array([[value4], [value5], [value6]]), "column3": array([[value7], [value8], [value9]]), } .. py:method:: save(onnx_file_path: str) Saves the ONNX model to the specified file path. :param onnx_file_path: The file path where the ONNX model should be saved. :type onnx_file_path: str :raises ImportError: If the optional dependencies for ONNX Conversion are not installed.