feat(cli): add --remote flag for automated remote Ray dispatch of ado CLI commands

[michael-johnston]

What's Added

A new global --remote <file> option for the ado CLI. When provided, any ado command is automatically dispatched to a remote Ray cluster instead of running locally. The entire workflow — copying files, building plugin wheels, generating a Ray runtime environment, setting up a port-forward, submitting the job, and tearing down — is handled by ado with no manual steps required.

Example

Running an optimisation operation (using examples/optimization_test_functions/) with the port-forward execution context.

: # From examples/optimization_test_functions/
ado --remote execution_context.yaml \
    create operation -f operation_nevergrad.yaml \
    --with space=space.yaml

Where execution_context.yaml contains:

executionType:
  type: cluster
  clusterUrl: "http://localhost:8265"
  portForward:
    namespace: discovery-dev
    serviceName: ray-disorch-head-svc
    localPort: 8265
packages:
  fromPyPI:
    - ray==2.52.1 # Required to match cluster ray
  fromSource:
    - . ./../          # ado-core 
    - custom_experiments  # in-tree custom experiments
wait: true
envVars:
  PYTHONUNBUFFERED: "x"
  OMP_NUM_THREADS: "1"
  OPENBLAS_NUM_THREADS: "1"
  RAY_AIR_NEW_PERSISTENCE_MODE: "0"
additionalFiles: [ ] #Optional list of additional files/dirs to send

[michael-johnston]

@AlessandroPomponio Docs not complete but take a look and test when you have a moment.

[AlessandroPomponio]

I have left a couple of comments and opened #608 for converting docstrings to all use the Google format

[michael-johnston]

@christian-pinto @VassilisVassiliadis some modifications to the actuator docs so please check

[christian-pinto]

@christian-pinto @VassilisVassiliadis some modifications to the actuator docs so please check

The docs look fine to me

[VassilisVassiliadis]

There're a couple of broken %include directives, a broken URL, and some potentially misaligned lines in sft-trainer.md.

We'll have to run mkserve docs locally to fix those problems.

Review comments answered