feat(cli): add --process-type option to override process execution mode

[Copilot]

Summary

Adds --process-type CLI option to plugboard process run for switching between LocalProcess and RayProcess execution modes, overriding YAML configuration. Uses Literal type for type-safe validation.

Changes

• CLI Enhancement

  • Added --process-type {local|ray} option to run command with Literal["local", "ray"] type
  • Typer automatically validates input and shows helpful error messages for invalid values

• Schema Enhancement

  • Added RAY_CONNECTOR_CLS_PATH constant to connector schema for consistency
  • Implemented ProcessSpec.override_process_type() method with mapping-based logic
  • Method handles process type, connector builder, and state backend updates atomically
  • When switching to ray: LocalProcess → RayProcess, AsyncioConnector → RayConnector, DictStateBackend → RayStateBackend
  • When switching to local: reverses the above transformations
  • Preserves connector builder args during override
  • Only modifies incompatible components (e.g., won't change RayConnector when already on Ray)

• Tests

  • Unit tests for local override and ray override
  • Validation testing handled by typer's built-in Literal type support

Example usage:

# Override any YAML config to run locally
plugboard process run ray-config.yaml --process-type local

# Force Ray execution regardless of YAML
plugboard process run local-config.yaml --process-type ray

Implementation Note: The override logic is implemented in the schema layer (ProcessSpec.override_process_type()) using a mapping-based approach rather than hard-coded if/else branches in the CLI, keeping business logic close to the data model and improving maintainability. Type safety is enforced using Literal types, allowing typer to handle validation automatically.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>CLI option to switch between local and Ray process</issue_title>
<issue_description>See #49 (comment)

We would like to be able to switch between Local and Ray processes from the CLI.</issue_description>

<agent_instructions>We need an option on the CLI to switch between RayProcess and LocalProcess by overriding whatever is specified in the input YAML. Note that when changing from local to ray, it is not enough just to change the Process type: you will also need to make sure the connector_builder and State type are changed if they are specified in the YAML and not compatible with Ray.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes CLI option to switch between local and Ray process #60

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

Benchmark comparison for 6dcb8099 (base) vs 21226eb0 (PR)

------------------------------------------------------------------------------------------------------------------ benchmark: 2 tests -----------------------------------------------------------------------------------------------------------------
Name (time in ms)                                                                         Min                 Max                Mean            StdDev              Median               IQR            Outliers     OPS            Rounds  Iterations
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_process_run (main/.benchmarks/Linux-CPython-3.12-64bit/0001_base)     362.4378 (1.0)      366.1342 (1.0)      364.4173 (1.0)      1.5109 (1.0)      363.9402 (1.0)      2.3329 (1.0)           2;0  2.7441 (1.0)           5           1
test_benchmark_process_run (pr/.benchmarks/Linux-CPython-3.12-64bit/0001_pr)         363.0361 (1.00)     368.5160 (1.01)     365.8759 (1.00)     2.2386 (1.48)     365.6326 (1.00)     3.7068 (1.59)          2;0  2.7332 (1.00)          5           1
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean

[toby-coleman]

@copilot review the implementation in this PR with a view to simplification.
Can you reduce the amount of hard-coded if/else branches checking for the different process types, and instead do something more elegant? Can some of the logic be done in the relevant schemas?

[Copilot]

@copilot review the implementation in this PR with a view to simplification.
Can you reduce the amount of hard-coded if/else branches checking for the different process types, and instead do something...

I've refactored the implementation to simplify the logic as requested:

Changes in commit 88d9c91:

1. Added RAY_CONNECTOR_CLS_PATH constant in the connector schema for consistency with existing patterns

2. Created ProcessSpec.override_process_type() method that uses mapping-based logic instead of hard-coded if/else branches:

   • Uses dictionaries to map process types to their connector/state requirements
   • Eliminates duplication between "local" and "ray" branches
   • Leverages Pydantic's model_copy() for clean updates

3. Simplified CLI code from ~70 lines down to ~10 lines by delegating to the new schema method

The logic is now in the schema layer where it belongs, and the implementation is much more maintainable and extensible.

[github-actions]

Benchmark comparison for 6dcb8099 (base) vs 2703cd9e (PR)

------------------------------------------------------------------------------------------------------------------ benchmark: 2 tests -----------------------------------------------------------------------------------------------------------------
Name (time in ms)                                                                         Min                 Max                Mean            StdDev              Median               IQR            Outliers     OPS            Rounds  Iterations
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_process_run (main/.benchmarks/Linux-CPython-3.12-64bit/0001_base)     302.8409 (1.0)      316.0205 (1.0)      307.9700 (1.0)      5.3306 (1.10)     307.7501 (1.0)      7.8993 (1.29)          1;0  3.2471 (1.0)           5           1
test_benchmark_process_run (pr/.benchmarks/Linux-CPython-3.12-64bit/0001_pr)         309.5419 (1.02)     321.4549 (1.02)     313.4483 (1.02)     4.8387 (1.0)      311.9684 (1.01)     6.1004 (1.0)           1;0  3.1903 (0.98)          5           1
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Benchmark comparison for 809ad8d2 (base) vs 22e38d01 (PR)

------------------------------------------------------------------------------------------------------------------ benchmark: 2 tests -----------------------------------------------------------------------------------------------------------------
Name (time in ms)                                                                         Min                 Max                Mean            StdDev              Median               IQR            Outliers     OPS            Rounds  Iterations
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_process_run (main/.benchmarks/Linux-CPython-3.12-64bit/0001_base)     454.4774 (1.0)      462.5387 (1.0)      458.6065 (1.0)      3.4675 (1.0)      457.1392 (1.0)      5.6966 (1.01)          2;0  2.1805 (1.0)           5           1
test_benchmark_process_run (pr/.benchmarks/Linux-CPython-3.12-64bit/0001_pr)         455.0820 (1.00)     465.4028 (1.01)     461.8959 (1.01)     4.2070 (1.21)     463.2152 (1.01)     5.6455 (1.0)           1;0  2.1650 (0.99)          5           1
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean