Minimum version 3.1.0

Messages

The messages are used to communicate to active runs. You can send messages to a run and retrieve them from the run. It is mainly use to change parameters, or take actions on the run (saving models, evaluation, etc.).

Publish a message

You can publish a message to the server using the SDK or the web application. Usually, the messages are published using the CLI or the web application. Contrary to most methods, the run parameter isn't optional. If you use the CLI, you must provide the run ID or the rank of the run with the project.

CLI

hectiq-lab Message.publish --run "9sk7x6" --key "learning-rate" --value 0.001 
# or
hectiq-lab Message.publish --run 438 --project hectiq-ai/demo --key "learning-rate" --value 0.001

Functional

import pyhectiqlab.functional as hl
hl.publish_message(run="9sk7x6", key="learning-rate", value=0.001)
# or
hl.publish_message(run=438, key="learning-rate", value=0.001, project="hectiq-ai/demo")

Object-Oriented

from pyhectiqlab import Message
message = Message.publish(run="9sk7x6", key="learning-rate", value=0.001)
# or
message = Message.publish(run=438, project="hectiq-ai/demo", key="learning-rate", value=0.001)

Name	Type	Default	Description
run	str		The run ID or rank. If the rank is used, then the project must be specified.
key	str		The key of the message.
value	Any		The value of the message.
project	Optional[str]		The project ID. Must be specified if run is the rank.

Retrieve messages

You can retrieve pending messages from the server using get_message. You must provide the key of the message you want to retrieve. If the message is not available, the method will return None.

Functional

import pyhectiqlab.functional as hl
message: Message.view = hl.get_message(key="learning-rate")
if message:
    message.ack() # Prevents the message from being retrieved again.
    print(message.value)

Object-Oriented

from pyhectiqlab import Message
message: Message.view = Message.get(key="learning-rate")
if message:
    message.ack() # Prevents the message from being retrieved again.
    print(message.value)

Name	Type	Default	Description
key	str		The key of the message.
run_id	Optional[str]		The run ID. If not specified, the run ID is taken from the environment.

The method returns a Message.view object. This object contains the following attributes:

Name	Type	Description
key	str	The key of the message.
value	str	The value of the message.
ack()	method	Acknowledge the message.

We recommend acknowledging the message before processing it to prevent it from being retrieved again or by another client.

WARNING

The message must be acknowledged. Otherwise, it will be retrieved again.

If you wish to retrieve all messages, you can use the get_all_messages method. This method returns a list of Message.view objects.

Functional

import pyhectiqlab.functional as hl
messages: List[Message.view] = hl.get_all_messages()
for message in messages:
    message.ack()
    print(message.key, message.value)

Object-Oriented

from pyhectiqlab import Message
messages: List[Message.view] = Message.get_all()
for message in messages:
    message.ack()
    print(message.key, message.value)

CLI

hectiq-lab Message.get_all --run "9sk7x6"

Optimization

Messages are not fetched every time the hl.get_message (or Message.get) method is called. It is fetched at most every few seconds.

If you call this method at high frequency (multiple times per second), the message will be fetched every 5 seconds. The message is fetched in a separate thread, but the method get_message returns immediately. Hence, the messages are fetched in the background, and the method will return your message when it is available. This is to prevent the client from waiting for the message to be available.