deisa.ray.utils module

deisa.ray.utils.get_head_actor_options() → dict[source]

Return the options that should be used to start the head actor.

Returns:

Dictionary of Ray actor options including: - name: “simulation_head” - namespace: “deisa_ray” - scheduling_strategy: NodeAffinitySchedulingStrategy for the head node - max_concurrency: Very high value to prevent blocking - lifetime: “detached” to persist beyond function scope - enable_task_events: False for performance

Return type:

dict

Notes

The head actor is scheduled on the head node with a detached lifetime to ensure it persists. High concurrency is set to prevent the actor from being blocked when gathering many references.

deisa.ray.utils.get_head_node_id() → str[source]

Get the node ID of the Ray cluster head node.

Returns:

The node ID of the head node.

Return type:

str

Raises:

AssertionError – If there is not exactly one head node in the cluster.

Notes

This function queries Ray’s state API to find the head node. It assumes there is exactly one head node in the cluster.

deisa.ray.utils.get_node_actor_options(name: str, namespace: str) → Dict[str, Any][source]

Return Ray options used to create (or get) a node scheduling actor.

Parameters:

  • name (str) – Actor name to use for the node actor.

  • namespace (str) – Ray namespace where the actor will live.

Returns:

Dictionary of options to be passed to SchedulingActor.options.

Return type:

dict

Notes

The options use get_if_exists=True to avoid race conditions when several bridges on the same node attempt to create the same actor. The actor is configured with:

  • lifetime='detached' so it survives the creating task

  • num_cpus=0 so it does not reserve CPU resources

  • a very large max_concurrency because the actor is async-only and used mainly as a coordination point.

async deisa.ray.utils.get_ready_actor_with_retry(name, namespace, deadline_s=180)[source]

Get a Ray actor by name with retry logic and readiness check.

This function attempts to retrieve a Ray actor by name and namespace, checking that it is ready before returning. It implements exponential backoff retry logic with a deadline.

Parameters:

  • name (str) – The name of the actor to retrieve.

  • namespace (str) – The namespace of the actor.

  • deadline_s (float, optional) – Maximum time in seconds to wait for the actor to become available. Default is 180.

Returns:

The handle to the ready actor.

Return type:

RayActorHandle

Raises:

TimeoutError – If the actor is not found or not ready within the deadline.

Notes

The function uses exponential backoff with jitter for retries. The delay starts at 0.2 seconds and increases by a factor of 1.5 up to a maximum of 5.0 seconds. A small random jitter (0-0.1 seconds) is added to avoid thundering herd problems.

deisa.ray.utils.get_system_metadata() → Dict[source]

Return system-level metadata placeholder.

Notes

Currently returns an empty dictionary; the hook exists to keep backward compatibility with callers expecting environment metadata.

deisa.ray.utils.log(message: str, debug_logs_path: str | None) → None[source]

Append a timestamped debug message to debug_logs_path if provided.

Parameters:

  • message (str) – Text to append.

  • debug_logs_path (str or None) – Destination file path. If None logging is skipped.