---

name: synapse-plugin-execution description: Explains how to execute Synapse plugins programmatically. Use when the user mentions "run_plugin", "ExecutionMode", "LocalExecutor", "RayActorExecutor", "RayJobExecutor", "PluginDiscovery", "from_path", "from_module", or needs help with running plugins programmatically.

Plugin Execution

Synapse SDK provides multiple ways to execute plugin actions programmatically.

run_plugin() Function

The simplest way to run a plugin action:

Copyfrom synapse_sdk.plugins.runner import run_plugin, ExecutionMode

# Local execution (in-process, good for dev)
result = run_plugin(
    plugin_code='/path/to/plugin',
    action='train',
    params={'epochs': 100},
    mode=ExecutionMode.LOCAL,
)

# Ray Actor execution (fast startup)
result = run_plugin(
    plugin_code='/path/to/plugin',
    action='train',
    params={'epochs': 100},
    mode=ExecutionMode.TASK,
)

# Ray Job execution (heavy workloads)
job_id = run_plugin(
    plugin_code='/path/to/plugin',
    action='train',
    params={'epochs': 100},
    mode=ExecutionMode.JOB,
)

Execution Modes

Plugin Discovery

Discover and inspect plugins before execution:

Copyfrom synapse_sdk.plugins.discovery import PluginDiscovery

# From filesystem path
discovery = PluginDiscovery.from_path('/path/to/plugin')

# From Python module
import my_plugin
discovery = PluginDiscovery.from_module(my_plugin)

# List available actions
actions = discovery.list_actions()  # ['train', 'inference']

# Get action class
action_cls = discovery.get_action_class('train')

# Get action metadata
config = discovery.get_action_config('train')
params_model = discovery.get_action_params_model('train')

Direct Executor Usage

For more control, use executors directly:

Copyfrom synapse_sdk.plugins.executors.local import LocalExecutor
from synapse_sdk.plugins.discovery import PluginDiscovery

discovery = PluginDiscovery.from_path('/path/to/plugin')
action_cls = discovery.get_action_class('train')

executor = LocalExecutor()
result = executor.execute(action_cls, {'epochs': 100})

Detailed References

• references/run-plugin.md - run_plugin() function details
• references/executors.md - Executor classes
• references/discovery.md - PluginDiscovery class