API Reference¶

Comprehensive technical documentation for the Rory platform, detailing the endpoints for the Client, Manager, and Worker components. This reference covers secure data mining protocols using homomorphic (Liu, CKKS) and order-preserving (FDHOPE) encryption schemes.

Rory Client¶

The Client acts as the Data Owner (DO) and the primary Decryption Authority. It is responsible for local data preparation, cryptographic key management, and participating as a secure decryption authority in interactive privacy-preserving protocols.

Route Summary¶

Clustering¶

Method	Route	Function	Description
`POST`	`/clustering/kmeans`	`kmeans`	Distributed K-Means on plaintext data.
`POST`	`/clustering/skmeans`	`skmeans`	Secure K-Means using the Liu scheme.
`POST`	`/clustering/dbskmeans`	`dbskmeans`	Double-blind Secure K-Means protocol.
`POST`	`/clustering/pqc_skmeans`	`pqc_skmeans`	Post-Quantum Secure K-Means (CKKS).
`POST`	`/clustering/nnc`	`nnc`	Nearest Neighbor Clustering execution.
`POST`	`/clustering/dbsnnc`	`dbsnnc`	Double-blind Nearest Neighbor Clustering.
`POST`	`/clustering/pqc_dbskmeans`	`pqc_dbskmeans`	Post-Quantum Double-blind K-Means.

Classification¶

Method	Route	Function	Description
`POST`	`/classification/knn_train`	`knn_train`	Local training of the KNN model.
`POST`	`/classification/knn_predict`	`knn_predict`	Standard KNN prediction (Plaintext).
`POST`	`/classification/sknn_train`	`sknn_train`	Secure KNN weight training protocol.
`POST`	`/classification/sknn_predict`	`sknn_predict`	Secure KNN prediction (FDHOPE).
`POST`	`/classification/sknn_pqc_train`	`sknn_pqc_train`	Post-Quantum Secure KNN training.
`POST`	`/classification/sknn_pqc_predict`	`sknn_pqc_predict`	Post-Quantum Secure KNN prediction.

Clustering (Client-side)¶

Endpoints to initiate secure data grouping. These routes handle local encryption and the externalization of datasets to the CSS.

`dbskmeans()` `async` ¶

This method implements a privacy-preserving protocol that ensures both the Worker and the Manager remain "blind" to the underlying data. It leverages a hybrid encryption approach, using Liu's homomorphic scheme for initial data protection and the FDHOPE scheme for secure operations on distance metrics.

Note: Multi-Party Security: Parameters for the double-blind execution are handled via HTTP Headers. Ensure the correct 'Experiment-Id' is provided for session tracking.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Unique ID for the matrix. Defaults to "matrix0".
`Plaintext-Matrix-Filename`	`str`	Local file to be processed. Defaults to "matrix0".
`K`	`int`	Number of clusters. Defaults to "3".
`Sens`	`float`	Sensitivity parameter for the FDHOPE scheme. Defaults to 0.00000001.
`Max-Iterations`	`int`	Maximum protocol rounds. Defaults to 10.
`Experiment-Id`	`str`	Tracking ID for performance auditing.

Returns:

Name	Type	Description
`label_vector`	`list`	Final cluster assignments.
`iterations`	`int`	Total rounds performed.
`algorithm`	`str`	"dbskmeans".
`worker_id`	`str`	ID of the node that performed the secure computations.
`service_time_manager`	`float`	Time spent in Worker allocation.
`service_time_worker`	`float`	Cumulative time of remote computation.
`service_time_client`	`float`	Total local time (Encryption/Decryption/IO).
`response_time_clustering`	`float`	End-to-end execution time.

Raises:

Type	Description
`Exception`	Returns a 500 status code if the process executor is unavailable, or if failures occur during the hybrid encryption/decryption chain or CSS communication.

`dbsnnc()` `async` ¶

This method implements a non-iterative, privacy-preserving clustering protocol based on nearest neighbors. It utilizes a Double-Blind Secure (DBS) approach where sensitive data and distance metrics are protected using a combination of Liu's homomorphic encryption and the FDHOPE scheme.

Note: All identifiers for the input matrices and distance metrics are extracted from HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Unique ID for the matrix. Defaults to "matrix0".
`Plaintext-Matrix-Filename`	`str`	Local file to be processed. Defaults to "matrix-0".
`Sens`	`float`	Sensitivity parameter for FDHOPE encryption. Defaults to 0.00000001.
`Threshold`	`float`	Distance threshold for clustering. If -1, it is calculated automatically from the dataset.
`Experiment-Id`	`str`	Tracking ID for performance auditing.

Returns:

Name	Type	Description
`label_vector`	`list`	The resulting cluster assignments.
`algorithm`	`str`	"dbsnnc".
`worker_id`	`str`	ID of the node that performed the secure computations.
`service_time_manager`	`float`	Time spent in Worker allocation.
`service_time_worker`	`float`	Cumulative time of remote computation.
`service_time_client`	`float`	Total local time (Encryption/Decryption/IO).
`response_time_clustering`	`float`	End-to-end execution time.

Raises: Exception: Returns a 500 status code if the process executor is missing, or if errors occur during encryption, CSS communication, or Worker execution.

`kmeans()` `async` ¶

This method handles the lifecycle of a clustering task by reading a local plaintext dataset, externalizing it to the Cloud Storage System (CSS), requesting an available execution node (Worker) from the Manager, and finally triggering the privacy-preserving mining process. The method also tracks and logs performance metrics (service times) for the Client, Manager, and Worker interactions to facilitate experimental auditing.

Note: Protocol Initiation: All execution parameters for this algorithm are passed exclusively via HTTP Headers. The request body must remain empty.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Unique identifier for the matrix in CSS. Defaults to "matrix-0".
`Plaintext-Matrix-Filename`	`str`	Name of the local file (without extension). Defaults to "matrix-0".
`Extension`	`str`	File extension of the local dataset (e.g., "csv", "npy"). Defaults to "csv".
`K`	`int`	The number of clusters to form. Defaults to "3".
`Experiment-Id`	`str`	A unique identifier for the execution trace. Defaults to a hex UUID.

Returns:

Name	Type	Description
`label_vector`	`list`	The cluster assignment for each dataset point.
`iterations`	`int`	Total iterations performed by the algorithm.
`algorithm`	`str`	The name of the algorithm executed (kmeans).
`worker_id`	`str`	Identifier of the worker node that processed the task.
`service_time_manager`	`float`	Time spent coordinating with the Manager.
`service_time_worker`	`float`	Time spent during Worker execution.
`service_time_client`	`float`	Time spent in local data preparation/reading.
`response_time_clustering`	`float`	Total end-to-end execution time.

Raises:

Type	Description
`Exception`	Captures and logs any failure during local I/O, CSS communication, or Manager/Worker interaction, returning a 500 status code with the error details in the headers.

`nnc()` `async` ¶

This method implements a distributed version of the Nearest Neighbor Clustering algorithm. Unlike its secure counterpart (DBSNNC), this version operates on plaintext data externalized to the Cloud Storage System (CSS), focusing on performance and orchestration within the Rory platform architecture.

Note: All identifiers for the input matrices and distance metrics are extracted from HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Unique identifier for the matrix in CSS. Defaults to "matrix0".
`Plaintext-Matrix-Filename`	`str`	Local filename (without extension). Defaults to "matrix-0".
`Extension`	`str`	Dataset file extension (e.g., "csv"). Defaults to "csv".
`Threshold`	`float`	Distance limit for clustering. If -1, it is calculated dynamically using platform utilities.
`Experiment-Id`	`str`	Unique ID for performance tracking and logging.

Returns:

Name	Type	Description
`label_vector`	`list`	Final cluster assignments for each data point.
`algorithm`	`str`	"nnc".
`worker_id`	`str`	ID of the worker node that processed the task.
`service_time_manager`	`float`	Time spent coordinating with the Manager.
`service_time_worker`	`float`	Time spent during Worker execution.
`service_time_client`	`float`	Time spent in local data preparation and IO.
`response_time_clustering`	`float`	Total end-to-end execution time.

Raises:

Type	Description
`Exception`	Returns a 500 status code if the process executor is missing, or if failures occur during local I/O, CSS communication, or Worker interaction.

`pqc_dbskmeans()` `async` ¶

This method achieves a "Double-Blind" state by combining CKKS for data protection and FDHOPE for secure distance matrix updates.

Note: Hybrid Secure Protocol: Combines post-quantum security with double-blind logic. Mandatory parameters are required in the HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Unique ID for CSS storage. Defaults to "matrix0".
`Plaintext-Matrix-Filename`	`str`	Local dataset name. Defaults to "matrix0".
`K`	`int`	Number of clusters. Required.
`Sens`	`float`	Sensitivity for FDHOPE. Defaults to 0.00000001.
`Max-Iterations`	`int`	Maximum protocol rounds. Defaults to 10.
`Experiment-Id`	`str`	Tracking ID for performance auditing.

Returns:

Name	Type	Description
`label_vector`	`list`	Final cluster assignments for the dataset.
`iterations`	`int`	Actual number of iterations performed.
`algorithm`	`str`	"dbskmeans pqc".
`worker_id`	`str`	ID of the node that performed the secure computations.
`service_time_manager`	`float`	Time spent in Worker allocation.
`service_time_worker`	`float`	Cumulative time of remote computation.
`service_time_client`	`float`	Total local time (Encryption/Decryption/IO).
`response_time_clustering`	`float`	End-to-end execution time.

Raises:

Type	Description
`Exception`	Returns a 500 status code if failures occur in the hybrid encryption chain (CKKS/FDHOPE), CSS I/O, or Worker orchestration.

`pqc_skmeans()` `async` ¶

This method implements a clustering protocol using the CKKS homomorphic encryption scheme. It is specifically designed for Post-Quantum Privacy-Preserving Data Mining as a Service (PPDMaaS), allowing complex floating-point computations on encrypted data while the Client retains the secret key.

Note: Post-Quantum Parameters: Security levels and CKKS-specific metadata are passed via HTTP Headers. Body content will be ignored.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Unique ID for the matrix. Defaults to "matrix0".
`Plaintext-Matrix-Filename`	`str`	Local file to be processed. Defaults to "matrix0".
`K`	`int`	Number of clusters. Required.
`Max-Iterations`	`int`	Maximum protocol rounds. Defaults to 10.
`Experiment-Id`	`str`	Tracking ID for performance auditing.

Returns:

Name	Type	Description
`label_vector`	`list`	Final cluster assignments for the dataset.
`iterations`	`int`	Actual number of iterations performed.
`algorithm`	`str`	"skmeans pqc".
`worker_id`	`str`	ID of the node that performed the secure computations.
`service_time_manager`	`float`	Time spent in Worker allocation.
`service_time_worker`	`float`	Cumulative time of remote computation.
`service_time_client`	`float`	Total local time (Encryption/Decryption/IO).
`response_time_clustering`	`float`	End-to-end execution time.

Raises:

Type	Description
`Exception`	Returns a 500 status code if the process executor is missing, CKKS context fails, or communication errors occur.

`skmeans()` `async` ¶

This method implements an interactive, privacy-preserving K-Means clustering protocol powered by Liu's homomorphic encryption scheme. The workflow is designed for Privacy-Preserving Data Mining as a Service (PPDMaaS), where the Client (Data Owner) remains the only entity capable of decrypting intermediate computations.

Note: Interactive Protocol: This endpoint initiates the secure clustering flow. All parameters, including cryptographic metadata, must be passed via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Unique ID for the matrix. Defaults to "matrix0".
`Plaintext-Matrix-Filename`	`str`	Local filename for data reading. Defaults to "matrix0".
`Extension`	`str`	File extension of the dataset. Defaults to "csv".
`K`	`int`	Number of clusters to identify. Required.
`Max-Iterations`	`int`	Maximum number of protocol rounds. Defaults to 10.
`Experiment-Id`	`str`	Tracking ID for performance auditing.
`Experiment-Iteration`	`str`	Current loop index of the experiment.

Returns:

Name	Type	Description
`label_vector`	`list`	Final cluster assignments for the dataset.
`iterations`	`int`	Actual number of iterations performed.
`algorithm`	`str`	"skmeans".
`worker_id`	`str`	ID of the node that performed the secure computations.
`service_time_manager`	`float`	Time spent in Worker allocation.
`service_time_worker`	`float`	Cumulative time of remote computation.
`service_time_client`	`float`	Total local time (Encryption/Decryption/IO).
`response_time_clustering`	`float`	End-to-end execution time.

Raises:

Type	Description
`Exception`	Returns a 500 status code if the process executor is missing, or if failures occur during encryption, CSS I/O, or Worker interaction.

`test()` ¶

Health check and component identification endpoint.

This method serves as a simple diagnostic tool to verify the availability of the Client component and confirm its role within the Rory platform architecture. It is used during deployment and orchestration to ensure proper network connectivity between nodes.

Returns:

Name	Type	Description
`Response`		A Flask Response object containing a JSON payload: component_type (str): Identifies this node as "client".
`Headers`		Component-Type: "client"
		Status Code: 200: If the service is running and reachable.

Classification (Client-side)¶

Endpoints for secure K-Nearest Neighbors (KNN) operations, managing the transformation between different encryption domains.

`knn_predict()` `async` ¶

This method orchestrates the classification of new data points using a previously "trained" (externalized) KNN model. The Client reads the test records locally, uploads them to the Cloud Storage System (CSS), and then communicates with the Manager and a designated Worker to perform the distributed nearest neighbor search.

Note: Plaintext Inference: Input record identifiers and model mapping parameters are passed exclusively via HTTP Headers.

Attributes:

Name	Type	Description
`Model-Id`	`str`	ID of the pre-trained model stored in CSS. Defaults to "model-0".
`Records-Test-Id`	`str`	Unique ID for the test records to be stored in CSS.
`Records-Test-Filename`	`str`	Local filename for the test dataset.
`Model-Labels-Shape`	`str`	The shape of the model's labels (Required for distributed distance calculations).
`Extension`	`str`	File extension of the source data. Defaults to "npy".
`Experiment-Id`	`str`	Tracking ID for performance benchmarking.

Returns:

Name	Type	Description
`label_vector`	`list`	The predicted class for each test record.
`worker_id`	`str`	ID of the worker node that performed the prediction.
`service_time_manager`	`float`	Latency introduced by the Manager interaction.
`service_time_worker`	`float`	Time spent in remote computation.
`service_time_client`	`float`	Time spent in local I/O and data preparation.
`service_time_predict`	`float`	Total end-to-end prediction time.
`algorithm`	`str`	The specific algorithm constant (knn_predict).

Raises:

Type	Description
`Response(500)`	If the "Model-Labels-Shape" header is missing, if the process executor is not configured, or if any error occurs during CSS interaction or Worker communication.

`knn_train()` `async` ¶

This method handles the "training" phase of the KNN algorithm within the Rory platform's distributed architecture. Since KNN is a lazy learner, this phase focuses on reading the reference dataset (features and labels) from local storage, segmenting them into chunks, and uploading them to the Cloud Storage System (CSS). This ensures that execution nodes (Workers) can access the model data for future prediction tasks.

Note: Model Generation: Configuration for model training, including target storage IDs, must be provided through HTTP Headers.

Attributes:

Name	Type	Description
`Model-Id`	`str`	Unique identifier for the model. Defaults to "matrix0model".
`Model-Filename`	`str`	Local name of the feature matrix file (without extension).
`Model-Labels-Filename`	`str`	Local name of the labels file (without extension).
`Extension`	`str`	File extension of the source data. Defaults to "npy".
`Experiment-Id`	`str`	Unique tracking ID for auditing and benchmarking.

Returns:

Name	Type	Description
`response_time`	`float`	Total time taken for the preparation and upload.
`algorithm`	`str`	The specific algorithm constant (knn_train).
`model_labels_shape`	`list`	The final dimensions of the uploaded labels matrix.

Raises:

Type	Description
`Response(500)`	If the process pool executor is not available in the app configuration.
`Response(500)`	If local file reading fails or if errors occur during the chunking and upload process to the CSS.

`sknn_pqc_predict()` `async` ¶

This method orchestrates a privacy-preserving K-Nearest Neighbors prediction leveraging the CKKS homomorphic encryption scheme. It follows a Double-Blind interactive protocol where the Client acts as a decryption oracle, allowing the distributed Rory architecture to identify nearest neighbors and assign labels without exposing plaintext data to the cloud infrastructure.

Note: Post-Quantum Classification: CKKS parameters and model identifiers are strictly handled via HTTP Headers to ensure protocol integrity.

Attributes:

Name	Type	Description
`Model-Id`	`str`	ID of the pre-trained PQC model in CSS. Defaults to "model0".
`Records-Test-Id`	`str`	Unique ID for the test records.
`Encrypted-Model-Shape`	`str`	Dimensions of the CKKS model matrix.
`Encrypted-Model-Dtype`	`str`	Data type of the encrypted model.
`Experiment-Id`	`str`	Tracking ID for performance auditing.
`Records-Test-Extension`	`str`	File extension (e.g., "npy").

Returns:

Name	Type	Description
`label_vector`	`list`	The predicted class assignments.
`worker_id`	`str`	ID of the worker node that processed the task.
`service_time_metrics`		Timing data for Client, Manager, and Worker.
`algorithm`	`str`	The SKNN_PQC_PREDICT constant.

Raises:

Type	Description
`Response(500)`	If mandatory headers (Shape/Dtype) are missing or if the process executor is not available.
`Response(500)`	If failures occur during CKKS decryption, chunking, or multi-node orchestration.

`sknn_pqc_train()` `async` ¶

This method manages the "training" phase for the PQC-enabled Secure K-Nearest Neighbors algorithm. It utilizes the CKKS homomorphic encryption scheme to protect the model's feature matrix, allowing for complex arithmetic operations on encrypted floating-point data. The Client handles the local encryption and segmentation before externalizing the secure artifacts to the Cloud Storage System (CSS).

Note: Post-Quantum Classification: CKKS parameters and model identifiers are strictly handled via HTTP Headers to ensure protocol integrity.

Attributes:

Name	Type	Description
`Model-Id`	`str`	Unique identifier for the model. Defaults to "matrix-0_model".
`Model-Filename`	`str`	Local filename for the feature matrix.
`Model-Labels-Filename`	`str`	Local filename for the label vector.
`Experiment-Id`	`str`	Tracking ID for performance auditing.
`Extension`	`str`	Source file extension. Defaults to "npy".

Returns:

Name	Type	Description
`response_time`	`str`	Total execution time for the preparation phase.
`encrypted_model_shape`	`str`	The dimensions of the CKKS-encrypted matrix.
`encrypted_model_dtype`	`str`	Data type (float32).
`algorithm`	`str`	The SKNN_PQC_TRAIN constant.
`model_labels_shape`	`list`	Dimensions of the uploaded labels matrix.

Raises:

Type	Description
`Response(500)`	If the ProcessPoolExecutor is unavailable or if model/label files are missing from the source path.
`Response(500)`	If errors occur during CKKS encryption, chunking, or asynchronous upload to the CSS.

`sknn_predict()` `async` ¶

This method orchestrates a privacy-preserving K-Nearest Neighbors prediction using Liu's homomorphic encryption scheme. It follows a protocol where the Worker performs heavy computations on encrypted data, and the Client acts as a decryption oracle to identify the nearest neighbors without revealing plaintext information to the remote nodes.

Note: Secure Inference: This method manages the transition between encryption domains. All required keys and IDs must be in the HTTP Headers.

Attributes:

Name	Type	Description
`Model-Id`	`str`	ID of the encrypted model in CSS. Defaults to "model0".
`Records-Test-Id`	`str`	ID for the encrypted test records.
`Encrypted-Model-Shape`	`str`	The 3D shape of the model (r, a, m).
`Encrypted-Model-Dtype`	`str`	Data type of the encrypted model.
`Model-Labels-Shape`	`str`	The shape of the labels vector.
`Experiment-Id`	`str`	Tracking ID for performance auditing.

Returns:

Name	Type	Description
`label_vector`	`list`	The final predicted classes.
`worker_id`	`str`	ID of the node that handled the encrypted computation.
`service_time_metrics`		Timing data for Client, Manager, and Worker.
`algorithm`	`str`	The specific constant for sknn_predict.

Raises:

Type	Description
`Response(500)`	If the process executor is missing or if mandatory headers (Shape/Dtype) are not provided.
`Response(500)`	If errors occur during the interactive encryption/decryption chain or during Worker orchestration.

`sknn_train()` `async` ¶

This method manages the "training" phase for the privacy-preserving KNN algorithm. Unlike the standard KNN preparation, this workflow incorporates Liu's homomorphic encryption scheme to protect the model's feature matrix. The Client performs local encryption using a ProcessPoolExecutor before segmenting and secure uploading it to the Cloud Storage System (CSS).

Note: Model Generation: Configuration for model training, including target storage IDs, must be provided through HTTP Headers.

Attributes:

Name	Type	Description
`Model-Id`	`str`	Unique identifier for the model and its labels. Defaults to "matrix-0_model".
`Model-Filename`	`str`	Local name of the feature matrix file.
`Model-Labels-Filename`	`str`	Local name of the labels vector file.
`Experiment-Id`	`str`	Unique ID for performance tracking.
`Extension`	`str`	Source data file extension. Defaults to "npy".

Returns:

Name	Type	Description
`response_time`	`float`	Total end-to-end preparation time.
`encrypted_model_shape`	`str`	The 3D shape of the Liu-encrypted matrix (Rows, Attributes, security parameter M).
`encrypted_model_dtype`	`str`	Data type of the encrypted matrix.
`algorithm`	`str`	The specific constant for sknn_train.
`model_labels_shape`	`list`	Dimensions of the uploaded labels matrix.

Raises:

Type	Description
`Response(500)`	If the ProcessPoolExecutor is missing or if the model/label files are not found in the local source path.
`Response(500)`	If any error occurs during the encryption chain, chunking process, or CSS communication.

`test()` ¶

Diagnostic and health check endpoint for the classification component.

This method provides a simple mechanism to verify that the classification routes are active and reachable. It is primarily used by the Rory platform's orchestration layer to identify the node type and ensure proper network synchronization before initiating machine learning workflows.

Returns:

Name	Type	Description
`Response`		A Flask Response object containing a JSON payload: component_type (str): "client".
`Headers`		Component-Type: "client"
		Status Code: 200: If the classification service is operational.

Rory Manager¶

The Manager is the central Orchestrator of the PPDMaaS ecosystem. Its primary function is to manage the lifecycle of mining tasks, perform load balancing, and assign available Workers to specific experimental requests while maintaining an audit trail of service times.

Route Summary¶

Method	Route	Function	Description
`POST`	`/workers/started`	`started`	Registers a new active Worker node.
`GET`	`/workers`	`getAll`	Retrieves metadata of all registered nodes.
`POST`	`/workers/deploy`	`deploy_worker`	Dynamically deploys a new Worker container.

Orchestration & Management¶

Endpoints for task status tracking, worker registration, and resource allocation.

`deploy_worker()` ¶

Orchestrates the dynamic deployment of a new Worker container within the Rory platform's infrastructure, facilitating on-demand scaling for privacy-preserving computations. This method utilizes the Replicator to spawn a containerized node, configuring its network identity, resource limits, and environment variables—including MictlanX and Liu scheme parameters—to ensure seamless integration into the distributed cluster.

Attributes:

Name	Type	Description
`Host-Port`	`str`	The network port on the host machine assigned to the worker.
`Container-Id`	`str`	The unique name or identifier for the Docker container.
`Container-Port`	`str`	The internal port where the worker service resides.
`Worker-Memory`	`str`	Memory resource limit for the container in bytes.
`Worker-Cpu`	`str`	CPU resource quota assigned to the worker.
`Source-Path`	`str`	Local path for dataset access within the container.
`Max-Iterations`	`str`	Limit for iterative mining algorithms like K-Means.
`Max-Threads`	`str`	Maximum concurrent threads for worker internal processing.

Returns:

Name	Type	Description
`container_id`	`str`	The unique identifier of the deployed container.
`port`	`str`	The assigned host port for the new service.

Raises:

Type	Description
`Exception`	If the Replicator fails to summon the container or an internal configuration error occurs.

`getAll()` ¶

Endpoint to retrieve a complete snapshot of all Worker nodes currently registered and active within the Manager orchestrator. This method facilitates monitoring of the entire system by returning metadata for the entire distributed pool, while also logging internal performance metrics to track the Manager's response efficiency during administrative queries.

Note

Query Execution: This endpoint does not require specific execution headers but logs the arrival and service time for auditing purposes.

Attributes:

Name	Type	Description
`None`		This request does not currently extract parameters from HTTP headers.

Returns:

Name	Type	Description
`workerId`	`str`	The unique identifier of the node.
`port`	`int`	The network port assigned to the worker service.
`isStarted`	`bool`	Current operational status of the worker.

Raises:

Type	Description
`Exception`	If the internal registry is inaccessible or an error occurs during the dictionary serialization process.

`started()` ¶

Endpoint to register a new Worker node in the Manager's global registry once its service becomes active. This method performs a thread-safe update to the internal worker collection, capturing the node's network identity to make it available for upcoming privacy-preserving data mining tasks within the PPDMaaS ecosystem.

Note

Registration Parameters: All attributes listed below must be passed exclusively via HTTP Headers.

Attributes:

Name	Type	Description
`Worker-Id`	`str`	Unique identifier for the registering worker node.
`Worker-Port`	`int`	The network port where the worker service is listening for instructions.

Returns:

Type	Description
	Object with a 204 status code indicating the worker was successfully added to the registry.

Raises:

Type	Description
`KeyError`	If mandatory headers (Worker-Id or Worker-Port) are missing from the request.
`Exception`	If an error occurs during the concurrent update of the global worker configuration.

Rory Worker¶

The Worker nodes represent the Cloud Computing Power. They perform high-performance data mining directly on encrypted data (ciphertext). They operate in a "zero-knowledge" state regarding the underlying plaintext, returning only encrypted intermediate or final results.

Route Summary¶

Clustering¶

Method	Route	Function	Description
`GET/POST`	`/test`	`test`	Verifies node connectivity and role identification.
`POST`	`/kmeans`	`kmeans`	Standard K-Means execution on plaintext data.
`POST`	`/skmeans`	`skmeans`	Interactive Secure K-Means (Liu Scheme).
`POST`	`/dbskmeans`	`dbskmeans`	Interactive Double-Blind Secure K-Means.
`POST`	`/nnc`	`nnc`	Standard Nearest Neighbor Clustering.
`POST`	`/dbsnnc`	`dbsnnc`	Double-Blind Nearest Neighbor Clustering.
`POST`	`/pqc/skmeans`	`pqc_skmeans`	Post-Quantum Secure K-Means (CKKS).
`POST`	`/pqc/dbskmeans`	`pqc_dbskmeans`	Post-Quantum Double-Blind K-Means (CKKS).

Classification¶

Method	Route	Function	Description
`POST`	`/knn/predict`	`knn_predict`	Standard KNN classification on plaintext data.
`POST`	`/sknn/predict`	`sknn_predict`	Interactive Secure KNN using the FDHOPE scheme.
`POST`	`/pqc/sknn/predict`	`sknn_pqc_predict`	Post-Quantum Secure KNN using the CKKS lattice-based scheme.

Clustering (Worker-side)¶

Execution logic for distributed K-Means, DBS K-Means, and NNC algorithms over encrypted matrices.

`dbskmeans()` `async` ¶

Main routing endpoint for the Double-Blind Secure K-Means (DBS K-Means) interactive protocol within the Worker node. This method manages the multi-party privacy-preserving lifecycle by evaluating the protocol's state through a step index. It ensures that encrypted computations are correctly delegated to either the initial distance calculation phase (Step 1) or the final convergence and centroid update phase (Step 2), maintaining the double-blind security guarantees throughout the distributed execution.

Note

Interactive Protocol Control: The execution flow and state transition are managed exclusively via the 'Step-Index' attribute passed in the HTTP Headers.

Attributes:

Name	Type	Description
`Step-Index`	`int`	The current round of the interactive protocol. Use "1" for the initial distance and shift matrix calculation, and "2" for convergence verification and label assignment. Defaults to "1".
`Experiment-Id`	`str`	A unique identifier used for performance auditing and execution tracing within the Rory platform.
`Plaintext-Matrix-Id`	`str`	The root identifier used to locate the encrypted dataset and its associated cryptographic metadata in the CSS.

Returns:

Type	Description
	An object forwarded from the corresponding sub-routine (dbskmeans_1 or dbskmeans_2),
	containing either intermediate ciphertexts or final clustering results.

Raises:

Type	Description
`Exception`	If the Step-Index is invalid or if the internal sub-routines encounter failures during CSS retrieval or cryptographic processing.

`dbskmeans_1(requestHeaders)` `async` ¶

First interactive phase of the Double-Blind Secure K-Means (DBS K-Means) protocol within the Worker node. This method orchestrates the retrieval and merging of encrypted data matrices and encrypted UDM matrices from the CSS. It performs the initial privacy-preserving distance calculations ('Run 1') using the double-blind scheme, generates the intermediate encrypted shift matrix, and persists the updated centroids and state back to storage. The execution pauses after this step, awaiting the Client to perform the necessary partial decryption of the shift matrix.

Note

Double-Blind Execution: This protocol requires both the data and the UDM to be in an encrypted state. All cryptographic metadata and identifiers must be provided via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier for deriving storage keys for centroids and UDM.
`Encrypted-Matrix-Id`	`str`	Storage key for the primary encrypted dataset.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the dataset.
`Encrypted-Matrix-Dtype`	`str`	Data type of the encrypted dataset elements.
`Encrypted-Udm-Shape`	`str`	Tuple string representing the dimensions of the encrypted UDM.
`Encrypted-Udm-Dtype`	`str`	Data type of the encrypted UDM elements.
`K`	`int`	The number of clusters to form. Defaults to "3".
`M`	`int`	Encryption scheme multiplier parameter. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments for matrix persistence.
`Clustering-Status`	`int`	Current state of the algorithm (Start=0, Progress=1).
`Iterations`	`int`	Current count of completed protocol cycles.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing.

Returns:

Name	Type	Description
`label_vector`	`list`	Intermediate cluster assignments.
`encrypted_shift_matrix_id`	`str`	Identifier for the generated matrix S1 stored in the CSS.
`n_iterations`	`int`	The current iteration count.
`service_time`	`float`	Total time elapsed during this worker phase.

Raises:

Type	Description
`Exception`	If mandatory headers (Shape/Dtype) are missing, CSS retrieval fails, or errors arise during the persistence of intermediate encrypted chunks.

`dbskmeans_2(requestHeaders)` `async` ¶

Second interactive phase of the Double-Blind Secure K-Means (DBS K-Means) protocol in the Worker node. This method processes the decrypted shift matrix provided by the Client to evaluate the algorithm's convergence based on a mean error threshold. If the error is within limits, the process terminates and returns cumulative performance metrics. Otherwise, it executes the 'Run 2' logic to update the encrypted UDM matrices, segments them into chunks, and persists them back to the CSS to enable the next iteration of the privacy-preserving mining cycle.

Note

Iterative Control: The protocol's state transition (Progress vs. Completion) and all cryptographic metadata are managed exclusively via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier for locating centroids and encrypted UDM fragments.
`Encrypted-Matrix-Id`	`str`	Storage key for the primary encrypted dataset.
`Shift-Matrix-Ope-Id`	`str`	Identifier for the decrypted shift matrix returned by the client.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the encrypted data.
`Encrypted-Udm-Shape`	`str`	Tuple string representing the dimensions of the encrypted UDM.
`K`	`int`	The number of clusters to form. Defaults to "3".
`M`	`int`	Encryption scheme multiplier parameter. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments for matrix persistence. Defaults to "4".
`Start-Time`	`str`	Global start timestamp used to calculate total response time upon completion.
`Iterations`	`int`	The current count of completed protocol cycles.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing.

Returns:

Name	Type	Description
`response_time`	`str`	Cumulative time since the global start (only on completion).
`service_time`	`float`	Execution time for this specific worker phase.
`encrypted_udm_shape`	`str`	The shape of the updated UDM matrix.
`encrypted_udm_dtype`	`str`	The data type of the updated UDM matrix.

Raises:

Type	Description
`Exception`	If mandatory identifiers are missing, CSS retrieval fails, or errors occur during the segmentation and persistence of updated encrypted UDM chunks.

`dbsnnc()` `async` ¶

Asynchronous endpoint for the Worker node to execute the Double-Blind Secure Nearest Neighbor Clustering (DBSNNC) algorithm. This method performs a privacy-preserving clustering operation by retrieving both the encrypted data matrix and the encrypted distance matrix from the CSS. It executes the DBSNNC logic directly on the ciphertext using a secure threshold comparison, effectively grouping data points based on their proximity without exposing the underlying plaintext or the actual distances to the cloud environment.

Note

Single-Round Execution: Unlike SK-Means, this protocol is non-interactive at the worker level. All cryptographic identifiers and threshold values must be provided via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier for deriving keys and session logging.
`Encrypted-Matrix-Id`	`str`	Storage key for the primary encrypted dataset.
`Encrypted-Dm-Id`	`str`	Storage key for the pre-calculated encrypted distance matrix.
`Encrypted-Threshold`	`float`	The secure distance limit used to determine neighborhood connectivity.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the data matrix.
`Encrypted-Dm-Shape`	`str`	Tuple string representing the dimensions of the distance matrix.
`M`	`int`	Encryption scheme multiplier parameter. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments for the input matrices.
`Experiment-Id`	`str`	Unique identifier for performance auditing and tracing.

Returns:

Name	Type	Description
`label_vector`	`list`	The final cluster assignment for each data point.
`service_time`	`float`	Total time elapsed during the worker's execution flow.

Raises:

Type	Description
`Exception`	If mandatory headers (Shape/Dtype) are missing, CSS retrieval fails, or errors arise during the secure clustering computation.

`kmeans()` `async` ¶

This method retrieves a plaintext matrix from the Cloud Storage System (CSS) using asynchronous clients, performs the clustering logic locally, and logs detailed performance metrics—including retrieval and execution times—to support experimental auditing and service time analysis within the distributed platform.

Note

Execution Parameters: All attributes listed below must be passed exclusively via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Unique identifier for the matrix stored in the CSS/Bucket.
`K`	`int`	The number of clusters to form. Defaults to "3".
`Experiment-Id`	`str`	A unique identifier for the execution trace and logging.

Returns:

Name	Type	Description
`label_vector`	`list`	The final cluster assignment for each data point.
`iterations`	`int`	Total number of iterations performed until convergence.
`service_time`	`float`	Total time elapsed during the worker's execution flow.

Raises:

Type	Description
`Exception`	Captures and logs failures during CSS matrix retrieval, MictlanX communication timeouts, or clustering computation errors.

`nnc()` `async` ¶

Asynchronous endpoint for the Worker node to execute the standard Nearest Neighbor Clustering (NNC) algorithm on plaintext data. This method retrieves the plaintext data matrix and its corresponding distance matrix from the CSS using asynchronous operations. It then executes the NNC logic to group data points based on a provided distance threshold, returning the resulting labels and logging performance metrics for auditing and benchmarking against secure variants.

Note

Plaintext Execution: All required parameters and matrix identifiers must be provided exclusively via HTTP Headers. The request body is not utilized.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier used to locate the data matrix and the pre-calculated distance matrix.
`Threshold`	`float`	The distance limit used to establish connectivity between neighboring data points.
`Plaintext-Matrix-Shape`	`str`	Tuple string representing the dimensions of the data matrix.
`Plaintext-Matrix-Dtype`	`str`	Data type of the data matrix elements.
`Dm-Shape`	`str`	Tuple string representing the dimensions of the distance matrix.
`Dm-Dtype`	`str`	Data type of the distance matrix elements.
`Num-Chunks`	`int`	Number of storage fragments for the input matrices.
`Experiment-Id`	`str`	Unique identifier for performance auditing and execution tracing.

Returns:

Name	Type	Description
`label_vector`	`list`	The final cluster assignment for each data point.
`service_time`	`float`	Total execution time for the worker's processing flow.

Raises:

Type	Description
`Exception`	If mandatory headers (Shape/Dtype) are missing, CSS retrieval fails, or errors occur during the clustering computation.

`pqc_dbskmeans()` `async` ¶

Main routing endpoint for the Post-Quantum Double-Blind Secure K-Means (PQC DBS K-Means) interactive protocol within the Worker node. This method orchestrates a multi-party privacy-preserving clustering flow that is resilient to quantum computing attacks by utilizing CKKS scheme. It manages the protocol state via a step index to coordinate the complex interaction between encrypted data matrices and encrypted UDM matrices, ensuring that the cloud environment operates in a "zero-knowledge" state while delegating specific cryptographic refreshes to the Client.

Note

Hybrid Secure Protocol: This execution combines post-quantum security with double-blind logic. All control parameters and cryptographic identifiers must be passed exclusively via HTTP Headers.

Attributes:

Name	Type	Description
`Step-Index`	`int`	The current round of the interactive PQC double-blind protocol. Use "1" for the initial distance and shift matrix calculation, and "2" for convergence verification and UDM updates. Defaults to "1".
`Experiment-Id`	`str`	A unique identifier used for performance auditing and execution tracing within the Rory platform.
`Plaintext-Matrix-Id`	`str`	The root identifier used to locate the CKKS-encrypted dataset and associated double-blind metadata in the CSS.

Returns:

Type	Description
	An object forwarded from the corresponding sub-routine (pqc_dbskmeans_1 or pqc_dbskmeans_2),
	containing either intermediate PQC-encrypted shift matrices or final clustering results.

Raises:

Type	Description
`Exception`	If the Step-Index is invalid or if the internal sub-routines encounter failures during ciphertext retrieval or processing.

`pqc_dbskmeans_1(requestHeaders)` `async` ¶

First interactive phase of the Post-Quantum Double-Blind Secure K-Means (PQC DBS K-Means) protocol within the Worker node. This method implements a hybrid privacy-preserving approach by combining CKKS scheme with double-blind logic. It retrieves PQC-encrypted data matrices and encrypted UDM fragments from the CSS, performing the initial distance calculations (Run 1) directly on the ciphertexts. The resulting encrypted shift matrices and intermediate centroids are persisted back to storage, pausing the execution to allow the Client to perform secure refreshes or partial decryptions of the ciphertexts before the next iteration.

Note

Hybrid Secure Execution: This protocol requires both CKKS parameters and double-blind metadata. All identifiers and cryptographic configurations must be provided exclusively via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier used to derive storage keys for CKKS-encrypted centroids and shift matrices.
`Encrypted-Matrix-Id`	`str`	Storage key for the primary CKKS-encrypted dataset in the CSS.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the encrypted matrix.
`Encrypted-Udm-Shape`	`str`	Tuple string representing the dimensions of the encrypted UDM.
`K`	`int`	The number of clusters to form. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments the ciphertexts are divided into.
`Clustering-Status`	`int`	Current state of the algorithm (Start=0, Progress=1).
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing.
`Iterations`	`int`	Current count of completed PQC double-blind protocol cycles.

Returns:

Name	Type	Description
`label_vector`	`list`	Intermediate cluster assignments derived from the PQC double-blind computation.
`service_time`	`float`	Total execution time for the Step 1 hybrid operations.
`n_iterations`	`int`	Incremented count of total protocol iterations.
`encrypted_shift_matrix_id`	`str`	Identifier for the generated CKKS shift matrix stored in the CSS.

Raises:

Type	Description
`Exception`	Occurs if CKKS initialization fails, mandatory headers are missing,

`pqc_dbskmeans_2(requestHeaders)` `async` ¶

Second interactive phase of the Post-Quantum Double-Blind Secure K-Means (PQC DBS K-Means) protocol. This method evaluates the convergence signal ('Is-Zero') provided by the Client after the partial decryption of the shift matrix. If convergence is reached, it marks the experiment as completed and logs final metrics. If not, it retrieves the refreshed shift matrix and the previous encrypted UDM from the CSS to execute 'Run 2' within the CKKS domain. The resulting updated UDM matrix is then segmented into chunks and persisted back to the storage system to enable the next iterative cycle of the hybrid secure mining process.

Note

Hybrid Secure Convergence: This step manages the transition between protocol states using cryptographic parameters. All control signals and identifiers must be provided via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier used to locate CKKS-encrypted UDM, centroids, and initial shift matrices.
`Encrypted-Matrix-Id`	`str`	Storage key for the primary CKKS-encrypted dataset in the CSS.
`Shift-Matrix-Ope-Id`	`str`	Identifier for the decrypted/refreshed shift matrix returned by the Client.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the encrypted dataset.
`Encrypted-Udm-Shape`	`str`	Tuple string representing the dimensions of the encrypted UDM.
`Is-Zero`	`int`	Convergence flag provided by the Client (1 if converged, 0 otherwise).
`K`	`int`	The number of clusters to form. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments for matrix persistence. Defaults to "-1".
`Iterations`	`int`	The current count of completed protocol cycles.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing.

Returns:

Type	Description
	Clustering-Status (int): Updated state (1 for In Progress, 2 for Completed).
	Service-Time (float): Execution time for this specific hybrid worker phase.
	Total-Service-Time (float): Cumulative time if the algorithm has reached completion.

Raises:

Type	Description
`Exception`	If mandatory identifiers are missing, CKKS key initialization fails,

`pqc_skmeans()` `async` ¶

Main routing endpoint for the Post-Quantum Secure K-Means (PQC SK-Means) interactive protocol within the Worker node. This method manages the lifecycle of clustering operations resilient to quantum computing threats by utilizing the CKKS homomorphic encryption scheme. It acts as an orchestrator that evaluates the protocol's state via a step index, delegating tasks to either the initial distance calculation phase (Step 1) or the final centroid update and convergence phase (Step 2), ensuring a secure multi-round communication flow with the Client.

Note

Post-Quantum Protocol Control: The execution flow and state transitions are managed exclusively via the 'Step-Index' attribute passed in the HTTP Headers. The request body is not utilized.

Attributes:

Name	Type	Description
`Step-Index`	`int`	The current round of the interactive PQC protocol. Use "1" for initial encrypted distance calculations and "2" for processing decrypted updates from the Client. Defaults to "1".
`Experiment-Id`	`str`	A unique identifier for performance auditing and execution tracing within the Rory platform.
`Plaintext-Matrix-Id`	`str`	The root identifier used to locate the encrypted dataset and associated CKKS cryptographic metadata in the CSS.

Returns:

Type	Description
	An object forwarded from the corresponding sub-routine (pqc_skmeans_1 or pqc_skmeans_2),
	containing intermediate PQC ciphertexts or final clustering results.

Raises:

Type	Description
`Exception`	If the Step-Index is invalid or if the internal sub-routines encounter failures during CSS retrieval or CKKS-based processing.

`pqc_skmeans_1(requestHeaders)` `async` ¶

First interactive phase of the Post-Quantum Secure K-Means (PQC SK-Means) protocol within the Worker node. This method implements the CKKS homomorphic encryption scheme to process encrypted datasets, retrieving ciphertexts and UDM matrices from the CSS. It performs the initial privacy-preserving distance calculations (Run 1) in a post-quantum secure domain, persisting intermediate shift matrices and centroids as encrypted fragments. The process halts after this phase, requiring the Client to perform secure refreshes or partial decryptions of the CKKS ciphertexts before the next iteration.

Note

Post-Quantum Execution: All execution parameters, including CKKS metadata and matrix identifiers, must be provided exclusively via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier used to derive storage keys for CKKS-encrypted centroids and shift matrices.
`Encrypted-Matrix-Id`	`str`	Storage key for the primary CKKS-encrypted dataset in the CSS.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the encrypted matrix.
`Encrypted-Matrix-Dtype`	`str`	Data type of the encrypted matrix elements.
`K`	`int`	The number of clusters to form. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments the ciphertexts are divided into.
`Clustering-Status`	`int`	Current state of the algorithm (Start=0, Progress=1).
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing.
`Iterations`	`int`	Current count of completed PQC protocol cycles.

Returns:

Name	Type	Description
`label_vector`	`list`	Intermediate cluster assignments derived from the PQC computation.
`service_time`	`float`	Total execution time for the Step 1 PQC operations.
`n_iterations`	`int`	Incremented count of total PQC protocol iterations.
`encrypted_shift_matrix_id`	`str`	Identifier for the generated CKKS shift matrix stored in the CSS.

Raises:

Type	Description
`Exception`	Occurs if CKKS key initialization fails, mandatory headers are missing,

`pqc_skmeans_2(requestHeaders)` `async` ¶

Second interactive phase of the Post-Quantum Secure K-Means (PQC SK-Means) protocol using the CKKS scheme. This method evaluates the convergence signal ('Is-Zero') provided by the Client. If the algorithm has converged, it finalizes the process and logs cumulative performance metrics. If convergence is not reached, it retrieves the refreshed/decrypted shift matrix from the Client and the initial parameters to execute 'Run 2', updating the encrypted UDM matrices and persisting them back to the CSS to enable the next iteration of the post-quantum mining lifecycle.

Note

Quantum-Resistant Iteration: The protocol state and convergence flow are managed exclusively via HTTP Headers, ensuring that the Worker operates in a zero-knowledge state regarding the underlying plaintext.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier used to derive storage keys for CKKS-encrypted UDM and centroids.
`Encrypted-Matrix-Id`	`str`	Storage key for the primary CKKS-encrypted dataset in the CSS.
`Shift-Matrix-Id`	`str`	Identifier for the decrypted or refreshed shift matrix provided by the Client.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the dataset.
`Is-Zero`	`int`	Convergence flag provided by the Client (1 if converged, 0 otherwise).
`K`	`int`	The number of clusters to form. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments for matrix persistence.
`Iterations`	`int`	The current count of completed PQC protocol cycles.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing within Rory.

Returns:

Type	Description
	Clustering-Status (int): The updated state (1 for In Progress, 2 for Completed).
	Service-Time (float): Execution time for this specific PQC worker phase.
	Total-Service-Time (float): Cumulative time if the algorithm has reached completion.

Raises:

Type	Description
`Exception`	If mandatory identifiers are missing, CKKS key initialization fails,

`skmeans()` `async` ¶

This method evaluates the protocol's state via a step index to coordinate the privacy-preserving mining process, ensuring that intermediate computations are handled by the appropriate sub-routine (Step 1 or Step 2) to maintain data confidentiality throughout the clustering lifecycle.

Attributes:

Name	Type	Description
`Step-Index`	`int`	The current round of the interactive protocol. Use "1" for distance calculation and "2" for centroid and label updates. Defaults to "1".
`Experiment-Id`	`str`	A unique identifier for the execution trace and performance auditing.
`Plaintext-Matrix-Id`	`str`	Identifier for the encrypted matrix stored in the CSS.

Returns:

Type	Description
	An object forwarded from the corresponding sub-step (skmeans_1 or skmeans_2),
	typically containing encrypted intermediate results or final labels.

Raises:

Type	Description
`Exception`	If the Step-Index is outside the valid range (1-2) or if the sub-routines encounter communication failures with the storage system.

`skmeans_1(requestHeaders)` `async` ¶

First interactive phase of the Secure K-Means protocol (Liu scheme) within the Worker node. This method orchestrates the retrieval of encrypted datasets and UDM matrices from the CSS, performs the initial privacy-preserving distance calculations (Run 1), and persists the resulting intermediate shift matrices and centroids back to storage. The process intentionally pauses at this stage, awaiting Client interaction to resolve secure updates before proceeding to subsequent rounds of the iterative clustering lifecycle.

Note

State Management: This step handles both the initial 'START' status and subsequent 'WORK_IN_PROGRESS' states, requiring specific cryptographic metadata via HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier used to derive storage keys for centroids and shift matrices.
`Encrypted-Matrix-Id`	`str`	Storage key for the primary encrypted dataset in the CSS.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the encrypted matrix.
`Encrypted-Matrix-Dtype`	`str`	Data type of the encrypted matrix elements.
`K`	`int`	The number of clusters to form. Defaults to "3".
`M`	`int`	Encryption scheme multiplier parameter. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments the matrices are divided into.
`Clustering-Status`	`int`	Current state of the algorithm (Start=0, Progress=1).
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing.
`Iterations`	`int`	Current count of completed protocol cycles.

Returns:

Name	Type	Description
`label_vector`	`list`	Intermediate cluster assignments for the dataset points.
`service_time`	`float`	Total execution time for the Step 1 operations.
`n_iterations`	`int`	Incremented count of total protocol iterations.
`encrypted_shift_matrix_id`	`str`	Identifier for the generated matrix S stored in the CSS.

Raises:

Type	Description
`Exception`	Occurs if mandatory headers (Shape/Dtype) are missing, CSS retrieval fails, or errors arise during the persistence of intermediate chunks.

`skmeans_2(requestHeaders)` `async` ¶

Second interactive phase of the Secure K-Means protocol (Liu scheme). This method processes the decrypted shift matrix returned by the Client to determine protocol convergence. If the error is within the permissible threshold, the clustering is marked as completed; otherwise, it triggers 'Run 2' to update the encrypted UDM matrices and persists them to the CSS, preparing the system for the next iterative cycle of the privacy-preserving mining process.

Note

Iterative Control: This endpoint manages the transition between 'WORK_IN_PROGRESS' and 'COMPLETED' states based on the convergence criteria evaluated from HTTP Headers.

Attributes:

Name	Type	Description
`Plaintext-Matrix-Id`	`str`	Root identifier for deriving storage keys (UDM, centroids).
`Encrypted-Matrix-Id`	`str`	Identifier for the encrypted dataset in the CSS.
`Shift-Matrix-Id`	`str`	Storage key for the decrypted shift matrix provided by the client.
`Encrypted-Matrix-Shape`	`str`	Tuple string representing the dimensions of the encrypted data.
`K`	`int`	The number of clusters to form. Defaults to "3".
`M`	`int`	Encryption scheme multiplier parameter. Defaults to "3".
`Num-Chunks`	`int`	Number of storage fragments for matrix persistence.
`Iterations`	`int`	The current count of protocol cycles completed.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing.

Returns:

Type	Description
	Clustering-Status (int): The updated state (1 for In Progress, 2 for Completed).
	Service-Time (float): Execution time for this specific step.
	Total-Service-Time (float): Cumulative time if the algorithm has reached completion.

Raises:

Type	Description
`Exception`	If mandatory identifiers are missing, storage retrieval fails, or errors occur during the persistence of updated UDM chunks.

`test()` ¶

Health check and component identification endpoint for the Worker node. This method serves as a heartbeat signal for the Rory Manager, allowing the orchestrator to confirm the node's availability and its specific role within the PPDMaaS ecosystem. It returns the component type both in the JSON payload and the HTTP response headers to facilitate automated discovery and load balancing.

Note

Infrastructure Check: This endpoint does not require cryptographic parameters or session identifiers, making it the primary tool for connectivity troubleshooting.

Returns:

Name	Type	Description
`component_type`	`str`	The identification string "worker".
`Headers`		Component-Type (str): Metadata indicating the node's functional role.

Classification (Worker-side)¶

Endpoints for processing secure classification queries, utilizing FDHOPE for privacy-preserving distance comparisons.

`knn_predict()` `async` ¶

Asynchronous endpoint for the Worker node to execute K-Nearest Neighbors (KNN) classification on plaintext data. This method retrieves a pre-trained model, its associated labels, and the target test records from the CSS. It performs the classification logic using the distance metric configured in the global system settings (e.g., Euclidean or Manhattan) and returns the resulting label vector. Detailed performance metrics for each retrieval and computation step are logged to support experimental analysis within the PPDMaaS platform.

Note

Standard Classification: All required identifiers for models and datasets must be passed exclusively via HTTP Headers. The request body is not utilized.

Attributes:

Name	Type	Description
`Model-Id`	`str`	Unique identifier for the trained KNN model stored in the CSS. Defaults to "model0".
`Model-Labels-Shape`	`str`	Tuple string representing the dimensions of the model labels (Mandatory).
`Records-Test-Id`	`str`	Storage key for the dataset records to be classified. Defaults to "matrix0".
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing.

Returns:

Name	Type	Description
`label_vector`	`list`	The predicted class assignments for the test records.
`service_time`	`float`	Total time elapsed during the worker's processing flow.

Raises:

Type	Description
`Exception`	If the 'Model-Labels-Shape' header is missing, CSS retrieval fails, or errors occur during the KNN prediction logic.

`sknn_pedict_1(requestHeaders)` `async` ¶

First interactive phase of the Secure K-Nearest Neighbors (SKNN) prediction protocol within the Worker node. This method orchestrates the retrieval of encrypted models and test records from the CSS. It performs the privacy-preserving distance calculation between the target records and the model's training set using the specified metric (e.g., Manhattan or Euclidean). The resulting secure distance matrix is segmented and persisted back to storage, awaiting the Client's interaction to resolve the k-nearest labels in the subsequent protocol round.

Note

Secure Inference Phase 1: This step operates exclusively on ciphertext to maintain data confidentiality. All identifiers, shapes, and cryptographic metadata must be provided via HTTP Headers.

Attributes:

Name	Type	Description
`Model-Id`	`str`	Root identifier used to locate the encrypted training model.
`Records-Test-Id`	`str`	Storage key for the encrypted records to be classified.
`Encrypted-Model-Shape`	`str`	Tuple string representing the dimensions of the encrypted model.
`Encrypted-Model-Dtype`	`str`	Data type of the encrypted model elements.
`Encrypted-Records-Shape`	`str`	Tuple string representing the dimensions of the encrypted test records.
`Encrypted-Records-Dtype`	`str`	Data type of the encrypted record elements.
`Num-Chunks`	`int`	Number of storage fragments for matrix retrieval and persistence.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing within Rory.

Returns:

Name	Type	Description
`distances_id`	`str`	Storage key for the calculated secure distance matrix.
`distances_shape`	`str`	Dimensions of the resulting distance matrix.
`distances_dtype`	`str`	Data type of the distance elements.
`service_time`	`float`	Total time elapsed during this worker phase.

Raises:

Type	Description
`Exception`	If mandatory headers are missing, CSS retrieval fails, or errors occur during the secure distance computation or chunk persistence.

`sknn_pqc_pedict_1(requestHeaders)` `async` ¶

First interactive phase of the Post-Quantum Secure K-Nearest Neighbors (PQC SKNN) prediction protocol within the Worker node. This method utilizes the CKKS homomorphic encryption scheme to process ciphertexts. It orchestrates the retrieval and merging of the encrypted model and test records from the CSS, performs the privacy-preserving distance calculation directly on the PQC ciphertexts, and persists the resulting secure distance matrix back to storage. The process pauses here, awaiting the Client's refresh or partial decryption of the CKKS distances to identify the k-nearest neighbors in the next round.

Note

Post-Quantum Inference Phase 1: This step operates exclusively on CKKS ciphertexts. All identifiers, parameters, and matrix shapes must be provided via HTTP Headers.

Attributes:

Name	Type	Description
`Model-Id`	`str`	Root identifier used to locate the CKKS-encrypted training model.
`Records-Test-Id`	`str`	Storage key for the CKKS-encrypted records to be classified.
`Encrypted-Model-Shape`	`str`	Tuple string representing the dimensions of the PQC-encrypted model.
`Encrypted-Model-Dtype`	`str`	Data type of the encrypted model elements.
`Encrypted-Records-Shape`	`str`	Tuple string representing the dimensions of the encrypted test records.
`Encrypted-Records-Dtype`	`str`	Data type of the encrypted record elements.
`Num-Chunks`	`int`	Number of storage fragments for matrix retrieval and persistence.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing within the Rory platform.

Returns:

Name	Type	Description
`distances_id`	`str`	Storage key for the calculated CKKS-encrypted distance matrix.
`distances_shape`	`str`	Dimensions of the resulting PQC distance matrix.
`distances_dtype`	`str`	Data type of the PQC distance elements.
`service_time`	`float`	Total time elapsed during this worker phase.

Raises:

Type	Description
`Exception`	If mandatory headers are missing, CKKS key initialization fails, or errors arise during the retrieval or persistence of lattice-based ciphertext chunks.

`sknn_pqc_predict()` `async` ¶

Main routing endpoint for the Post-Quantum Secure K-Nearest Neighbors (PQC SKNN) interactive prediction protocol within the Worker node. This method manages the secure inference lifecycle using CKKS scheme. It acts as an orchestrator that evaluates the protocol's state via a step index, delegating tasks to either the initial PQC-encrypted distance calculation (Step 1) or the final label resolution based on client-aided results (Step 2). This ensures that the classification of sensitive records remains confidential against both classical and quantum-era threats.

Note

Post-Quantum Protocol Control: The execution flow and state transitions are managed exclusively via the 'Step-Index' attribute passed in the HTTP Headers. The request body is not utilized.

Attributes:

Name	Type	Description
`Step-Index`	`int`	The current round of the interactive PQC SKNN protocol. Use "1" for the initial CKKS-encrypted distance calculations and "2" for final label assignment. Defaults to "1".
`Model-Id`	`str`	Identifier for the CKKS-encrypted model stored in the CSS.
`Experiment-Id`	`str`	A unique identifier for performance auditing and execution tracing within the Rory platform.

Returns:

Type	Description
	An object forwarded from the corresponding sub-routine (sknn_pqc_predict_1 or sknn_pqc_predict_2),
	containing either intermediate PQC secure scores or the final classification results.

Raises:

Type	Description
`Exception`	If the Step-Index is invalid or if the sub-routines encounter failures during CKKS key initialization or CSS retrieval.

`sknn_pqc_predict_2(requestHeaders)` `async` ¶

Final interactive phase of the Post-Quantum Secure K-Nearest Neighbors (PQC SKNN) prediction protocol within the Worker node. This method completes the secure classification lifecycle by retrieving the model labels and the resolved nearest-neighbor indices (previously refreshed or decrypted by the Client) from the CSS. It maps these indices to the corresponding class labels to produce the final classification vector.

Note

Post-Quantum Inference Phase 2: This step acts as the final label mapping. All required identifiers for models, labels, and indices must be provided via HTTP Headers.

Attributes:

Name	Type	Description
`Model-Id`	`str`	Root identifier used to locate the model labels and trained parameters.
`Records-Test-Id`	`str`	Storage key used to identify the resolved distance indices.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing within the Rory platform.

Returns:

Name	Type	Description
`label_vector`	`list`	The final predicted class assignments for the test dataset.
`service_time`	`float`	Total execution time for this specific worker phase.

Raises:

Type	Description
`Exception`	If CSS retrieval for labels or indices fails, or if errors arise during the final label vector construction.

`sknn_predict()` `async` ¶

Main routing endpoint for the Secure K-Nearest Neighbors (SKNN) interactive prediction protocol within the Worker node. This method manages the multi-round secure inference process by evaluating the protocol's state via a step index. It coordinates the transition between the encrypted distance calculation and the final label assignment, ensuring that the Worker performs heavy computations on ciphertext (using the FDHOPE scheme) while delegating specific decryption tasks to the Client to maintain end-to-end privacy.

Note

Interactive Inference Control: The execution flow and state transitions are managed exclusively via the 'Step-Index' attribute passed in the HTTP Headers. The request body is not utilized.

Attributes:

Name	Type	Description
`Step-Index`	`int`	The current round of the interactive SKNN protocol. Use "1" for the initial secure distance calculation and "2" for processing client-aided label resolution. Defaults to "1".
`Model-Id`	`str`	Identifier for the encrypted model stored in the CSS to be used for prediction.
`Experiment-Id`	`str`	A unique identifier for execution tracing and performance auditing within the Rory platform.

Returns:

Type	Description
	An object forwarded from the corresponding sub-routine (sknn_predict_1 or sknn_predict_2),
	containing either intermediate secure scores or the final classification results.

Raises:

Type	Description
`Exception`	If the Step-Index is invalid or if the sub-routines encounter failures during CSS retrieval or cryptographic processing.

`sknn_predict_2(requestHeaders)` `async` ¶

Final interactive phase of the Secure K-Nearest Neighbors (SKNN) prediction protocol within the Worker node. This method completes the secure classification process by retrieving the resolved nearest-neighbor indices from the CSS (previously computed and uploaded by the Client). It then maps these indices to their corresponding model labels to generate the final classification vector. The process concludes by logging cumulative performance metrics and the total service time for the interactive inference session.

Note

Secure Inference Phase 2: This step acts as the final label resolution. All identifiers and shape metadata for the labels and indices must be provided via HTTP Headers.

Attributes:

Name	Type	Description
`Model-Id`	`str`	Root identifier used to locate the associated model labels.
`Model-Labels-Shape`	`str`	Tuple string representing the dimensions of the model labels (Mandatory).
`Records-Test-Id`	`str`	Storage key used to derive the identifier for the resolved distance indices.
`Experiment-Id`	`str`	Unique identifier for execution tracing and auditing within the Rory platform.

Returns:

Name	Type	Description
`label_vector`	`list`	The final predicted class labels for the test records.
`service_time`	`float`	Total execution time for this specific worker phase.

Raises:

Type	Description
`Exception`	If the 'Model-Labels-Shape' header is missing, CSS retrieval of labels or indices fails, or errors occur during the label mapping logic.

`test()` ¶

Health check and role verification endpoint for the Worker's Classification module. This method acts as a diagnostic heartbeat, allowing the Rory Manager to verify that the Classification blueprint is correctly registered and the node is ready to process KNN or PQC-based inference tasks. It returns the component type in both the JSON payload and the HTTP response headers for automated service discovery and configuration auditing.

Note

Service Availability: This endpoint provides a zero-overhead way to test the connectivity between the Manager and the Worker node without requiring cryptographic keys or session identifiers.

Returns:

Name	Type	Description
`Response`		A Flask Response object with a 200 status containing a JSON payload with: component_type (str): The identification string "worker".
`Headers`		Component-Type (str): Functional metadata indicating the node's classification role.

API Reference¶

Rory Client¶

Route Summary¶

Clustering¶

Classification¶

Clustering (Client-side)¶

dbskmeans() async ¶

dbsnnc() async ¶

kmeans() async ¶

nnc() async ¶

pqc_dbskmeans() async ¶

pqc_skmeans() async ¶

skmeans() async ¶

test() ¶

Classification (Client-side)¶

knn_predict() async ¶

knn_train() async ¶

sknn_pqc_predict() async ¶

sknn_pqc_train() async ¶

sknn_predict() async ¶

sknn_train() async ¶

test() ¶

Rory Manager¶

Route Summary¶

Orchestration & Management¶

deploy_worker() ¶

getAll() ¶

started() ¶

Rory Worker¶

Route Summary¶

Clustering¶

Classification¶

Clustering (Worker-side)¶

dbskmeans() async ¶

dbskmeans_1(requestHeaders) async ¶

dbskmeans_2(requestHeaders) async ¶

dbsnnc() async ¶

kmeans() async ¶

nnc() async ¶

pqc_dbskmeans() async ¶

pqc_dbskmeans_1(requestHeaders) async ¶

pqc_dbskmeans_2(requestHeaders) async ¶

pqc_skmeans() async ¶

pqc_skmeans_1(requestHeaders) async ¶

pqc_skmeans_2(requestHeaders) async ¶

skmeans() async ¶

skmeans_1(requestHeaders) async ¶

skmeans_2(requestHeaders) async ¶

test() ¶

Classification (Worker-side)¶

knn_predict() async ¶

sknn_pedict_1(requestHeaders) async ¶

sknn_pqc_pedict_1(requestHeaders) async ¶

sknn_pqc_predict() async ¶

sknn_pqc_predict_2(requestHeaders) async ¶

sknn_predict() async ¶

sknn_predict_2(requestHeaders) async ¶

test() ¶

`dbskmeans()` `async` ¶

`dbsnnc()` `async` ¶

`kmeans()` `async` ¶

`nnc()` `async` ¶

`pqc_dbskmeans()` `async` ¶

`pqc_skmeans()` `async` ¶

`skmeans()` `async` ¶

`test()` ¶

`knn_predict()` `async` ¶

`knn_train()` `async` ¶

`sknn_pqc_predict()` `async` ¶

`sknn_pqc_train()` `async` ¶

`sknn_predict()` `async` ¶

`sknn_train()` `async` ¶

`test()` ¶

`deploy_worker()` ¶

`getAll()` ¶

`started()` ¶

`dbskmeans()` `async` ¶

`dbskmeans_1(requestHeaders)` `async` ¶

`dbskmeans_2(requestHeaders)` `async` ¶

`dbsnnc()` `async` ¶

`kmeans()` `async` ¶

`nnc()` `async` ¶

`pqc_dbskmeans()` `async` ¶

`pqc_dbskmeans_1(requestHeaders)` `async` ¶

`pqc_dbskmeans_2(requestHeaders)` `async` ¶

`pqc_skmeans()` `async` ¶

`pqc_skmeans_1(requestHeaders)` `async` ¶

`pqc_skmeans_2(requestHeaders)` `async` ¶

`skmeans()` `async` ¶

`skmeans_1(requestHeaders)` `async` ¶

`skmeans_2(requestHeaders)` `async` ¶

`test()` ¶

`knn_predict()` `async` ¶

`sknn_pedict_1(requestHeaders)` `async` ¶

`sknn_pqc_pedict_1(requestHeaders)` `async` ¶

`sknn_pqc_predict()` `async` ¶

`sknn_pqc_predict_2(requestHeaders)` `async` ¶

`sknn_predict()` `async` ¶

`sknn_predict_2(requestHeaders)` `async` ¶

`test()` ¶