pdstools.infinity.resources.prediction_studio.local_model_utils¶

Attributes¶

`logger`
`PEGA_METADATA`

Exceptions¶

`ONNXModelCreationError`	Exception for errors during ONNX conversion and save.
`ONNXModelValidationError`	Exception for errors during ONNX validation.

Classes¶

`OutcomeType`	Supported outcome types for local Prediction Studio model metadata.
`Predictor`	A single predictor (feature) in an ONNX model.
`Output`	Model output metadata stored in the embedded Pega metadata block.
`Metadata`	Top-level Pega metadata embedded in an ONNX model.
`PMMLModel`	Wrapper around a PMML file path.
`H2OModel`	Wrapper around an H2O model file path.
`ONNXModel`	Wrapper around an in-memory ONNX model plus Pega metadata helpers.

Module Contents¶

logger¶

PEGA_METADATA = 'pegaMetadata'¶

class OutcomeType(*args, **kwds)¶

Bases: enum.Enum

Supported outcome types for local Prediction Studio model metadata.

BINARY = 'binary'¶

CATEGORICAL = 'categorical'¶

CONTINUOUS = 'continuous'¶

class Predictor(/, **data: Any)¶

Bases: 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.

See also

Metadata.build_predictor_list: Batch‑build predictors from a list of Pega property paths or plain feature names.

Parameters:: data (Any)

name: str | None = None¶

index: int | None = None¶

input_name: str | None = None¶

data_type: str = None¶

pega_property: str | None = None¶

validate_input_name(v)¶

validate_name(v)¶

validate_index(v)¶

validate_data_type(v)¶

class Output(/, **data: Any)¶

Bases: pydantic.BaseModel

Model output metadata stored in the embedded Pega metadata block.

Parameters:: data (Any)

possible_values: list[str | int | float] = None¶

label_name: str | None = None¶

score_name: str | None = None¶

min_value: float | None = None¶

max_value: float | None = None¶

validate_label_name(v)¶

class Metadata(/, **data: Any)¶

Bases: pydantic.BaseModel

Top-level Pega metadata embedded in an ONNX model.

Parameters:: data (Any)

type: OutcomeType | None = None¶

predictor_list: list[Predictor] = None¶

output: Output | None = None¶

modeling_technique: str | None = None¶

internal: bool | None = None¶

file_source: str | None = None¶

objective: str | None = None¶

rule_set: str | None = None¶

rule_set_version: str | None = None¶

predict_method_uses_name_value_pair: bool | None = None¶

model_version: str | None = None¶

created_by: str | None = None¶

created_date: str | None = None¶

last_modified_date: str | None = None¶

training_dataset: str | None = None¶

experiment_id: str | None = None¶

parent_model_id: str | None = None¶

baseline_auc: float | None = None¶

baseline_accuracy: float | None = None¶

performance_threshold: float | None = None¶

validate_type(v, values)¶

validate_output(v, values)¶

to_json() → str¶

Return type:: str

classmethod from_json(json_str: str) → Metadata¶

Parameters:: json_str (str)
Return type:: Metadata

static build_predictor_list(features: list[str], input_name: str = 'features', *, data_types: list[str] | dict[str, str] | None = None) → list[Predictor]¶

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.

Parameters:

features (list[str]) – 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.
input_name (str) – Name of the ONNX input node. Default "features".
data_types (list[str] | dict[str, str] | None) –
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".

Return type:

list[Predictor]

Examples

>>> # Using Pega property paths (recommended for auto-mapping):
>>> Metadata.build_predictor_list(
...     [".Customer.Age", ".Customer.Tenure", ".Customer.MonthlyCharges"],
... )

>>> # Using plain feature names:
>>> Metadata.build_predictor_list(["Age", "Tenure", "MonthlyCharges"])
...

>>> # Sparse overrides via dict:
>>> Metadata.build_predictor_list(
...     [".Customer.Age", ".Customer.ContractType"],
...     data_types={"ContractType": "Symbolic"},
... )

exception ONNXModelCreationError¶

Bases: Exception

Exception for errors during ONNX conversion and save.

exception ONNXModelValidationError¶

Bases: pdstools.infinity.resources.prediction_studio.base.ModelValidationError

Exception for errors during ONNX validation.

class PMMLModel(file_path: str)¶

Bases: pdstools.infinity.resources.prediction_studio.base.LocalModel

Wrapper around a PMML file path.

Parameters:: file_path (str)

file_path: str¶

get_file_path() → str¶

Returns the file path of the model.

Returns:: str
Return type:: The file path of the model.

class H2OModel(file_path: str)¶

Bases: pdstools.infinity.resources.prediction_studio.base.LocalModel

Wrapper around an H2O model file path.

Parameters:: file_path (str)

file_path: str¶

get_file_path() → str¶

Returns the file path of the model.

Returns:: str
Return type:: The file path of the model.

class ONNXModel(model: onnx.ModelProto)¶

Bases: pdstools.infinity.resources.prediction_studio.base.LocalModel

Wrapper around an in-memory ONNX model plus Pega metadata helpers.

Parameters:: model (onnx.ModelProto)

classmethod from_onnx_proto(model: onnx.ModelProto) → ONNXModel¶

Creates an ONNXModel object.

Parameters:

model (ModelProto) – An onnx ModelProto object

Returns:

An instance of the ONNXModel class.

Return type:

ONNXModel

Raises:

ImportError – If the optional dependencies for ONNX Conversion are not installed.
ONNXModelCreationError – If the ONNXModel object cannot be created.

classmethod from_sklearn_pipeline(model: sklearn.pipeline.Pipeline, initial_types: list) → ONNXModel¶

Creates an ONNXModel object.

Parameters:

model (Pipeline) – A sklearn Pipeline object
initial_types (list) – A list of initial types for the model’s input variables if the model is a Sklearn Pipeline object.

Returns:

An instance of the ONNXModel class.

Return type:

ONNXModel

Raises:

ImportError – If the optional dependencies for ONNX Conversion are not installed.
ONNXModelCreationError – If the ONNXModel object cannot be created.

classmethod 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¶

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.

Parameters:

model – A PyTorch nn.Module (already in eval mode is recommended).
dummy_input – Example input tensor(s) matching the model’s forward signature.
input_names (list[str] | None) – Optional list of ONNX input node names. Defaults to ["input"].
output_names (list[str] | None) – Optional list of ONNX output node names. Defaults to ["output"].
opset_version (int) – ONNX opset version. Default 17.
fixed_batch_size (bool) – Replace dynamic dimensions with batch size 1.

Return type:

ONNXModel

Raises:

ONNXModelCreationError – If PyTorch is not installed or the export fails.

get_metadata() → Metadata | None¶

Return the embedded Metadata or None if absent.

Return type:: Metadata | None

add_metadata(metadata: Metadata) → ONNXModel¶

Adds metadata to the ONNX model.

Parameters:: metadata (Meta) – The metadata to be added.
Returns:: The ONNXModel object with the added metadata.
Return type:: ONNXModel
Raises:: ImportError – If the optional dependencies for ONNX Metadata addition are not installed.

validate() → bool¶

Validates an ONNX model.

Raises:

ImportError – If the optional dependencies for ONNX Validation are not installed.
ONNXModelValidationError – If the model is invalid or if the validation process fails.

Return type:

bool

run(test_data: dict)¶

Run the prediction using the provided test data.

Parameters:: test_data (dict) – 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.
Returns:: The prediction result.
Return type:: Any

Examples

test_data should look like:

{
    "column1": array([[value1], [value2], [value3]]),
    "column2": array([[value4], [value5], [value6]]),
    "column3": array([[value7], [value8], [value9]]),
}

save(onnx_file_path: str)¶

Saves the ONNX model to the specified file path.

Parameters:: onnx_file_path (str) – The file path where the ONNX model should be saved.
Raises:: ImportError – If the optional dependencies for ONNX Conversion are not installed.