HeModel#

class HeModel#

A class to represent an AI model that is encoded and possibly encrypted under HE, that supports running an inference and possibly training process.

static compile(plain: pyhelayers.PlainModel, he_run_req: pyhelayers.HeRunRequirements) → pyhelayers.HeProfile | None#

Compiles a plain model under a given HE run requirements. Returns an optional HE profile that is populated if the compilation is possible given the plain model and requirements, or empty otherwise.

Parameters:

plain – The plain model. Must be initialized.
he_run_req – The HE run requirements.

static create_context(profile: pyhelayers.HeProfile) → pyhelayers.HeContext#

Creates, initializes and returns an HE context given an HE profile that was obtained as an output of model compilation.

Parameters:: profile – The given HE profile.

create_model_io_encoder(self: pyhelayers.HeModel) → pyhelayers.ModelIoEncoder#: Create a model IO encoder for this model.

decrypt_decode(self: pyhelayers.HeModel) → pyhelayers.PlainModel#: Decrypts a trained model (after calling “fit”) to obtain a trained plain model. Requires the HE context to contain a secret key.

encode(*args, **kwargs)#

Overloaded function.

encode(self: pyhelayers.HeModel, plain: pyhelayers.PlainModel, profile: pyhelayers.HeProfile, inputs: List[numpy.ndarray[numpy.float64]] = []) -> None

Encodes a model given a plain model and an HE profile that was obtained as an output of model compilation. The resulting model will have non-encrypted weights.

param plain:

The plain model. Must be initialized.

param profile:

The given HE profile.

param inputs:

An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.
encode(self: pyhelayers.HeModel, streams: List[bytes], files: List[str], he_run_req: pyhelayers.HeRunRequirements, hyper_params: pyhelayers.PlainModelHyperParams = <pyhelayers.PlainModelHyperParams object at 0x7f60252dbcb0>, inputs: List[numpy.ndarray[numpy.float64]] = []) -> None

Loads the given model and prepared it to run with encrypted data, with the model itself not encrypted. Optional parameters can control various additional settings.

Internally, this method initializes a plain model using PlainModel.init, compiles a model using HeModel.compile and calls HeModel.encode.

param streams:

List of streams with content to load, depending on the underlying model. All streams must be rewindable.

param files:

List of file names corresponding to each stream.

param he_run_req:

The HE run requirements.

param hyper_params:

The hyperparameters object.

param inputs:

An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.
encode(self: pyhelayers.HeModel, files: List[str], he_run_req: pyhelayers.HeRunRequirements, hyper_params: pyhelayers.PlainModelHyperParams = <pyhelayers.PlainModelHyperParams object at 0x7f60231260b0>, inputs: List[numpy.ndarray[numpy.float64]] = []) -> None

Loads the given model and prepared it to run with encrypted data, with the model itself not encrypted. Optional parameters can control various additional settings.

Internally, this method initializes a plain model using PlainModel.init, compiles a model using HeModel.compile and calls HeModel.encode.

param files:

List of file names with content to load, depending on the underlying model.

param he_run_req:

The HE run requirements.

param hyper_params:

The hyperparameters object.

param inputs:

An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.

encode_encrypt(*args, **kwargs)#

Overloaded function.

encode_encrypt(self: pyhelayers.HeModel, plain: pyhelayers.PlainModel, profile: pyhelayers.HeProfile, inputs: List[numpy.ndarray[numpy.float64]] = []) -> None

Encodes and encrypts a model given a plain model and an HE profile that was obtained as an output of model compilation. The resulting model will have encrypted weights.

NOTE: while the model weights are encrypted, the model architecture and/or structure is not hidden. For example, in neural network the non-hidden architecture includes the number of layers, the order of the layers, each layer’s type, input shape, output shape and internal parameters (e.g. number of neurons in Dense layer; size of kernel, strides and padding in Conv2D layer; the degree of a polynomial activation layer and the sign of its leading coefficient, etc.).

param plain:

The plain model. Must be initialized.

param profile:

The given HE profile.

param inputs:

An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.
encode_encrypt(self: pyhelayers.HeModel, streams: List[bytes], files: List[str], he_run_req: pyhelayers.HeRunRequirements, hyper_params: pyhelayers.PlainModelHyperParams = <pyhelayers.PlainModelHyperParams object at 0x7f60252dbb30>, inputs: List[numpy.ndarray[numpy.float64]] = []) -> None

Loads the given model and prepared it to run with encrypted data, and encrypted model. Optional parameters can control various additional

settings.

Internally, this method initializes a plain model using PlainModel.init, compiles a model using HeModel.compile and calls HeModel.encode_encrypt.

param streams:

List of streams with content to load, depending on the underlying model. All streams must be rewindable.

param files:

List of file names corresponding to each stream.

param he_run_req:

The HE run requirements.

param hyper_params:

The hyperparameters object.

param inputs:

An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.
encode_encrypt(self: pyhelayers.HeModel, files: List[str], he_run_req: pyhelayers.HeRunRequirements, hyper_params: pyhelayers.PlainModelHyperParams = <pyhelayers.PlainModelHyperParams object at 0x7f60252dbfb0>, inputs: List[numpy.ndarray[numpy.float64]] = []) -> None

Loads the given model and prepared it to run with encrypted data, and encrypted model. Optional parameters can control various additional

settings.

Internally, this method initializes a plain model using PlainModel.init, compiles a model using HeModel.compile and calls HeModel.encode_encrypt.

param files:

List of file names with content to load, depending on the underlying model.

param he_run_req:

The HE run requirements.

param hyper_params:

The hyperparameters object.

param inputs:

An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.

fit(self: pyhelayers.HeModel, inputs: pyhelayers.EncryptedData) → None#

Fit (train) the model under FHE.

Parameters:: inputs – The encrypted training inputs.

get_can_switch_between_predict_fit_modes(self: pyhelayers.HeModel) → bool#: Check whether this model can be switched from fit to predict mode.

get_created_he_context(self: pyhelayers.HeModel) → pyhelayers.HeContext#: Returns a shared pointer to the HeContext object that was created while initializing this model using encode() or encodeEncrypt() method directly from plain model files or streams. Returns null if this model was initialized with an HeContext created beforehand.

get_encrypted_internals(self: pyhelayers.HeModel) → pyhelayers.EncryptedData#: Returns the encrypted internals (e.g., weights) of this model. The packing of the encrypted internals depends on the model type. The encrypted internals can be decrypted and decoded independently, and be given as input to the method get_plain_model_from_decoded_internals().

get_fit_hyperparams(self: pyhelayers.HeModel) → pyhelayers.FitHyperParams#: Returns common training related hyper parameters

get_he_context(self: pyhelayers.HeModel) → pyhelayers.HeContext#: Returns the HE context object this model uses

get_plain_model_from_decoded_internals(self: pyhelayers.HeModel, decoded_internals: list) → pyhelayers.PlainModel#

Constructs a plain model from the given decoded internals (decrypted and decoded from the output of getEncryptedInternals()). The same HeModel object should be used for both getEncryptedInternals() and this method.

Parameters:: decoded_internals – The decoded internals which were decrypted and

decoded from the output of getEncryptedInternals().

get_profile(self: pyhelayers.HeModel) → pyhelayers.HeProfile#: Returns the HE profile that was used to build the model.

load_encrypted_data(self: pyhelayers.HeModel, buf: bytes) → pyhelayers.EncryptedData#

Loads encrypted data from the given buffer.

Parameters:: buf – The buffer to load from.
Raises:: RuntimeError – If the given buffer does not contain an EncryptedData object, or if the object was saved with a mismatching HElayers version.

load_encrypted_data_from_file(self: pyhelayers.HeModel, path: str) → pyhelayers.EncryptedData#

Loads encrypted data from the given file.

Parameters:: path – The path of the file to load from.
Raises:: RuntimeError – If the given file does not contain an EncryptedData object, or if the object was saved with a mismatching HElayers version.

predict(*args, **kwargs)#

Overloaded function.

predict(self: pyhelayers.HeModel, res: pyhelayers.EncryptedData, inputs: pyhelayers.EncryptedData) -> None

Run prediction (inference) over the model under FHE.

param res:

An output parameter to store the prediction result (encrypted predictions) in.

param inputs:

The encrypted inputs.
predict(self: pyhelayers.HeModel, res: pyhelayers.EncryptedBatch, inputs: pyhelayers.EncryptedBatch) -> None

Run prediction (inference) of a single batch over the model under FHE.

param res:

An output parameter to store the prediction result (encrypted predictions of a single batch) in.

param inputs:

A single batch of encrypted inputs.

switch_to_predict_mode(self: pyhelayers.HeModel) → None#: Switch this model from fit to predict mode.

class HeModel : public helayers::Saveable#

A class to represent an AI model that is encoded and possibly encrypted under HE, that supports running an inference and possibly training process.

Subclassed by helayers::Aml, helayers::Arima, helayers::DTree, helayers::KMeans, helayers::LogisticRegression, helayers::NeuralNet, helayers::XGBoost

Public Functions

HeModel() = default#: Construct an empty HE Model object.

HeModel(const HeContext &he)#

Construct a new HE Model object.

Parameters:: he – An initialized HE context.

virtual ~HeModel() = default#: Destroy the HE Model object.

HeModel(const HeModel &src) = delete#: Deleted copy constructor.

HeModel &operator=(const HeModel &src) = delete#: Deleted operator=.

void encode(const PlainModel &plain, const HeProfile &profile, const std::vector<DoubleTensorCPtr> &inputs = {})#

Encodes a model given a plain model and an HE profile that was obtained as an output of model compilation.

The resulting model will have non-encrypted weights.

Parameters:

plain – The plain model. Must be initialized.
profile – The given HE profile.
inputs – An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.

void encode(const std::vector<std::shared_ptr<std::istream>> &streams, const std::vector<std::string> &files, const HeRunRequirements &heRunReq, const PlainModelHyperParams &hyperParams = PlainModelHyperParams(), const std::vector<DoubleTensorCPtr> &inputs = {})#

Loads the given model and prepared it to run with encrypted data, with the model itself not encrypted.

Optional parameters can control various additional settings.

Internally, this method initializes a plain model using PlainModel::init, compiles a model using HeModel::compile and calls HeModel::encode.

Parameters:

streams – List of streams with content to load, depending on the underlying model. All streams must be rewindable.
files – List of file names corresponding to each stream.
heRunReq – The HE run requirements.
hyperParams – The hyperparameters object.
inputs – An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.

void encode(const std::vector<std::string> &files, const HeRunRequirements &heRunReq, const PlainModelHyperParams &hyperParams = PlainModelHyperParams(), const std::vector<DoubleTensorCPtr> &inputs = {})#

Loads the given model and prepared it to run with encrypted data, with the model itself not encrypted.

Optional parameters can control various additional settings.

Internally, this method initializes a plain model using PlainModel::init, compiles a model using HeModel::compile and calls HeModel::encode.

Parameters:

files – List of file names with content to load, depending on the underlying model.
heRunReq – The HE run requirements.
hyperParams – The hyperparameters object.
inputs – An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.

void encodeEncrypt(const PlainModel &plain, const HeProfile &profile, const std::vector<DoubleTensorCPtr> &inputs = {})#

Encodes and encrypts a model given a plain model and an HE profile that was obtained as an output of model compilation.

The resulting model will have encrypted weights.

NOTE: while the model weights are encrypted, the model architecture and/or structure is not hidden. For example, in neural network the non-hidden architecture includes the number of layers, the order of the layers, each layer’s type, input shape, output shape and internal parameters (e.g. number of neurons in Dense layer; size of kernel, strides and padding in Conv2D layer; the degree of a polynomial activation layer and the sign of its leading coefficient, etc.).

Parameters:

plain – The plain model. Must be initialized.
profile – The given HE profile.
inputs – An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.

void encodeEncrypt(const std::vector<std::shared_ptr<std::istream>> &streams, const std::vector<std::string> &files, const HeRunRequirements &heRunReq, const PlainModelHyperParams &hyperParams = PlainModelHyperParams(), const std::vector<DoubleTensorCPtr> &inputs = {})#

Loads the given model and prepared it to run with encrypted data, and encrypted model.

Optional parameters can control various additional settings.

Internally, this method initializes a plain model using PlainModel::init, compiles a model using HeModel::compile and calls HeModel::encodeEncrypt.

Parameters:

streams – List of streams with content to load, depending on the underlying model. All streams must be rewindable.
files – List of file names corresponding to each stream.
heRunReq – The HE run requirements.
hyperParams – The hyperparameters object.
inputs – An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.

void encodeEncrypt(const std::vector<std::string> &files, const HeRunRequirements &heRunReq, const PlainModelHyperParams &hyperParams = PlainModelHyperParams(), const std::vector<DoubleTensorCPtr> &inputs = {})#

Loads the given model and prepared it to run with encrypted data, and encrypted model.

Optional parameters can control various additional settings.

Internally, this method initializes a plain model using PlainModel::init, compiles a model using HeModel::compile and calls HeModel::encodeEncrypt.

Parameters:

files – List of file names with content to load, depending on the underlying model.
heRunReq – The HE run requirements.
hyperParams – The hyperparameters object.
inputs – An optional representative plaintext inputs, to be used for preventing overflows. It is recommended to include representative inputs, including ones that might produce intermediate results with high values during the computation, as these inputs will be used to tune the model. NOTE: Providing inputs and running the overflows prevention mechanism may result in derivatives of the given inputs or model weights to be present in plaintext inside the model and in any IO processor created from it.

const HeProfile &getProfile() const#: Returns the HE profile that was used to build the model.

const HeContext &getHeContext() const#: Returns the HE context object this model uses.

const std::shared_ptr<HeContext> getCreatedHeContext() const#

Returns a shared pointer to the HeContext object that was created while initializing this model using encode() or encodeEncrypt() method directly from plain model files or streams.

Returns null if this model was initialized with an HeContext created beforehand.

const FitHyperParams &getFitHyperParams() const#: Returns common training related hyper parameters.

inline const PlainModelHyperParams &getPlainModelHyperParams() const#: Returns the hyper parameters of this model.

inline const std::vector<HeTensorMetadata> &getInputsHeTensorMetadata() const#: Returns “inputsHeTensorMetadata” member, which holds metadata on the encrypted input tensors.

inline const std::vector<HeTensorMetadata> &getOutputsHeTensorMetadata() const#: Returns “outputsHeTensorMetadata” member, which holds metadata on the encrypted output tensors.

inline std::optional<DimInt> getFixedBatchSizeRequirement() const#: Return an optional value, indicating the fixed batch size if such a size was specified by model.

const circuit::Circuit &getCircuit() const#: Return the circuit that was generated.

void predict(EncryptedData &res, const EncryptedData &inputs) const#

Run prediction (inference) over the model under FHE.

Parameters:

res – An output parameter to store the prediction result (encrypted predictions) in.
inputs – The encrypted inputs.

void predict(EncryptedBatch &res, const EncryptedBatch &inputs) const#

Run prediction (inference) of a single batch over the model under FHE.

Parameters:

res – An output parameter to store the prediction result (encrypted predictions of a single batch) in.
inputs – A single batch of encrypted inputs.

void fit(const EncryptedData &inputs)#

Fit (train) the model under FHE.

Parameters:: inputs – The encrypted training inputs.

virtual std::shared_ptr<PlainModel> decryptDecode() const#

Decrypts a trained model (after calling “fit”) to obtain a trained plain model.

Requires the HE context to contain a secret key.

virtual EncryptedData getEncryptedInternals() const#

Returns the encrypted internals (e.g., weights) of this model.

The packing of the encrypted internals depends on the model type. The encrypted internals can be decrypted and decoded independently, and be given as input to the method getPlainModelFromDecodedInternals().

virtual std::shared_ptr<PlainModel> getPlainModelFromDecodedInternals(const std::vector<DoubleTensorCPtr> &decodedInternals) const#

Constructs a plain model from the given decoded internals (decrypted and decoded from the output of getEncryptedInternals()).

The same HeModel object should be used for both getEncryptedInternals() and this method.

Parameters:: decodedInternals – The decoded internals which were decrypted and decoded from the output of getEncryptedInternals().

bool isFitMode() const#

bool getIsEncryptedMode() const#

ModelIoEncoder createModelIoEncoder() const#: Create a model IO encoder for this model.

std::shared_ptr<EncryptedData> loadEncryptedData(std::istream &stream) const#

Loads encrypted data from the given stream.

Parameters:: stream – The stream to load from.
Throws:: runtime_error – If the given stream does not contain an EncryptedData object, or if the object was saved with a mismatching HElayers version.

std::shared_ptr<EncryptedData> loadEncryptedDataFromFile(const std::string &fileName) const#

Loads encrypted data from the given file.

Parameters:: fileName – The name of the file to load from.
Throws:: runtime_error – If the given file does not contain an EncryptedData object, or if the object was saved with a mismatching HElayers version.

virtual void switchToPredictMode()#: Switch this model from fit mode to predict mode.

inline bool getCanSwitchBetweenPredictFitModes()#: Whether this model can switch from fit mode to predict mode.

Public Static Functions

static std::optional<HeProfile> compile(const PlainModel &plain, const HeRunRequirements &heRunReq)#

Compiles a plain model under a given HE run requirements.

Returns an optional HE profile that is populated if the compilation is possible given the plain model and requirements, or empty otherwise.

Parameters:

plain – The plain model. Must be initialized.
heRunReq – The HE run requirements.

static std::shared_ptr<HeContext> createContext(const HeProfile &profile)#

Creates, initializes and returns an HE context given an HE profile that was obtained as an output of model compilation.

Parameters:: profile – The given HE profile.

Friends

friend class ModelIoEncoder

friend class ModelIoEncoderImpl