qoa4ml

qoa4ml

Classes

ClientConfig

Top-level configuration that fully describes a QoA client and its connectors, collectors, and probes.

QoaClient

Functions

__init__(report_cls=_DEFAULT_REPORT_CLS, config_dict=None, config_path=None, registration_url=None, strict=False)

Initialize the QoA Client with configuration settings and a report class.

Parameters:

Name	Type	Description	Default
report_cls	type[T]	The class type for reports, default is MLReport.	_DEFAULT_REPORT_CLS
config_dict	dict	A dictionary to load the client's configuration from.	None
config_path	str	Path to a JSON configuration file.	None
registration_url	str	URL for registering the client and receiving configuration data.	None
strict	bool	When True, re-raise any exception encountered while wiring up connectors (honouring the project fail-fast rule). Default False preserves the legacy "construct successfully with no connector" behaviour.	False

Notes

• If both config_dict and config_path are provided, config_dict takes precedence.
• If neither is provided, the client falls back to a bare ClientConfig and relies on registration_url to fetch a connector configuration.
• Raises ValueError if none of config_dict, config_path, or a usable registration_url is provided.

__str__()

Returns a string representation of the client's configuration and connectors.

Returns:

Type	Description
str	JSON representation of the client configuration and a string representation of the connector list.

Notes

This method is particularly useful for debugging and logging purposes.

get_client_config()

Get the current client configuration.

Returns:

Type	Description
ClientInfo	The client's current configuration settings.

import_previous_report(reports)

Import and process previous reports.

Parameters:

Name	Type	Description	Default
reports	Union[dict, list[dict]]	A single report or a list of reports to be processed.	required

init_connector(configuration)

Initialize a connector based on the configuration provided.

Parameters:

Name	Type	Description	Default
configuration	ConnectorConfig	Configuration settings for initializing the connector.	required

Returns:

Type	Description
BaseConnector	An instance of the connector (e.g., AMQP, Debug).

Raises:

Type	Description
RuntimeError	If the connector configuration type is not supported.

init_probes(probe_config_list, client_info)

Initialize monitoring probes based on the provided probe configuration list.

Parameters:

Name	Type	Description	Default
probe_config_list	list[ProbeConfig]	A list of configuration settings for each probe.	required
client_info	ClientInfo	Information about the client to be passed to each probe.	required

Returns:

Type	Description
list[Probe]	A list of initialized probe instances.

Raises:

Type	Description
ValueError	If an unsupported probe configuration type is provided.

observe_inference(inference_value)

Observe and record inference data.

Parameters:

Name	Type	Description	Default
inference_value	Any	The value of the inference to be observed.	required

Notes

This method is used to record predictions or inference results for later analysis.

observe_inference_metric(metric_name, value)

Observe and report a specific inference metric.

Parameters:

Name	Type	Description	Default
metric_name	MetricNameEnum	The name of the inference metric being observed.	required
value	Any	The value of the observed metric.	required

Notes

This method can be used to log performance metrics, evaluation scores, etc. during inference.

observe_metric(metric_name, value, category=0, description='')

Observe and report a metric.

Parameters:

Name	Type	Description	Default
metric_name	MetricNameEnum	The name of the metric being observed.	required
value	Any	The value of the observed metric.	required
category	int	The category of the metric (0: service, 1: data, 2: security), default is 0.	0
description	str	An optional description of the observed metric, default is "".	''

Raises:

Type	Description
RuntimeError	If the category type is not supported.

registration(url)

Registers the client with the monitoring service and retrieves connector configurations.

Parameters:

Name	Type	Description	Default
url	str	The registration URL to fetch the connector configuration from.	required

Returns:

Type	Description
Response	The response from the registration service, containing connector configurations.

Raises:

Type	Description
ValueError	If url is not http/https, lacks a hostname, or targets a cloud-metadata endpoint (SSRF hardening, 0.3.19).

Notes

This method sends a POST request to the given URL with the client's configuration in JSON format.

report(report=None, connectors=None, submit=False, reset=True, corr_id=None)

Generate a report and optionally submit it through the default connector.

Parameters:

Name	Type	Description	Default
report	dict	The report data to be submitted. If None, a report will be generated.	None
connectors	list	A list of connectors through which to send the report, default is None.	None
submit	bool	Whether to submit the report, default is False.	False
reset	bool	Whether to reset the report state after submission, default is True.	True
corr_id	str	The correlation ID for the report, default is None.	None

Returns:

Type	Description
dict[str, Any]	The report as a dictionary.

Notes

The method will create a report based on the current state if none is provided. If submit is True, the report will be sent through the default or specified connectors.

set_config(key, value)

Update a single ClientInfo field in place.

Parameters:

Name	Type	Description	Default
key	str	Must be a declared ClientInfo field name; arbitrary attributes are rejected to prevent silent attribute injection.	required
value	Any	The new value to set.	required

Raises:

Type	Description
AttributeError	If key is not a known ClientInfo field.

start_all_probes()

Start all probes for monitoring, running them in the background.

Raises:

Type	Description
RuntimeError	If no probes have been initialized.

Notes

If the probe takes a long time to report and the main process exits, no report may be sent.

stop_all_probes()

Stop all running probes.

Raises:

Type	Description
RuntimeError	If no probes have been initialized.

Notes

This method stops the background monitoring activities of all active probes.

timer()

Start or stop a timer and record the response time.

Returns:

Type	Description
dict	A dictionary containing the start time and response time.

Notes

• When called for the first time, it starts the timer.
• When called again, it stops the timer and records the response time as a metric.