plugin-development.mdc

---
description: Guidelines for developing ado plugins (actuators, operators, custom_experiments)
globs: "{plugins,examples}/**/*"
alwaysApply: false
---

# Plugin Development Guidelines

These guidelines apply when developing plugins for ado.
Plugins are developed under `plugins/` or `examples/` directories.
All general development guidelines from `AGENTS.md` also apply.

---

## Plugin Structure

### Package Organization

- **Actuators**: Each actuator is its own package under `plugins/actuators/`
- **Operators**: Each operator is its own package under `plugins/operators/`
- **Custom Experiments**: Can have multiple custom experiments in a single package under `plugins/custom_experiments/`

### Directory Layout

Each plugin package should contain:

- `pyproject.toml` - Package configuration
- `tests/` - Unit and integration tests (keep within the plugin package)
- YAML examples - Example discoveryspace and operation files for the plugin
- Plugin implementation code

---

## Package Setup

### Using setuptools_scm for Versioning

Configure `pyproject.toml` to use `setuptools_scm` for automatic versioning:

```toml
[build-system]
requires = ["setuptools", "setuptools_scm"]
build-backend = "setuptools.build_meta"

[tool.setuptools_scm]
root = "../../../"  # Points to repo root

[project]
name = "your-plugin-name"
dynamic = ["version"]  # Version set automatically by setuptools_scm
```

### Dependencies

**Always include ado-core** in the dependencies:

```toml
[project]
dependencies = [
    "ado-core",
    # ... other dependencies
]
```

### Installation

Install the plugin into the top-level venv from the repo root:

```bash
uv pip install -e plugins/your_plugin_type/your_plugin
```

### Workspace Membership

By default, plugins added in-tree are not workspace members and should
not be added to `[tool.uv.workspace]` members in the root `pyproject.toml`.

This means the plugins pyproject.toml should not include a `[tool.uv.sources]`
section resolving `ado-core` via `{ workspace = true }`.

Only add a plugin to the workspace when explicitly
asked, for example when the plugin must be included in `uv sync` for CI or
cross-plugin dependency resolution.

If you mistakenly add `ado-core = { workspace = true }` to a plugin's
`[tool.uv.sources]` without adding it to the workspace, `uv pip install`
will fail with:

```
Failed to parse entry: `ado-core`
`ado-core` references a workspace ... but is not a workspace member
```

### Adding Dependencies with uv

Use `uv` to add new dependencies to your plugin:

```bash
cd plugins/actuators/your_plugin/
uv add package-name
```

---

## Plugin Registration

### Actuators: Namespaced Packages

Actuators use namespaced packages and require:

1. Package structure under a namespace
2. `actuator_definitions.yaml` file
3. Optional `experiments.yaml` file

```toml
[tool.setuptools.package-data]
your_actuator = [
    "actuator_definitions.yaml",  # Required
    "experiments.yaml"             # Optional
]
```

### Operators and Custom Experiments: Entry Points

Operators and custom experiments use entry points in `pyproject.toml`:

**Operator Example:**

```toml
[project.entry-points."ado.operators"]
ado-ray-tune = "ado_ray_tune.operator_function"
```

**Custom Experiment Example:**

```toml
[project.entry-points."ado.custom_experiments"]
min_gpu_experiment = "autoconf.min_gpu_recommender"
```

---

## Custom Experiments

### Decorator Requirements

Custom experiments **must** use the `@custom_experiment` decorator correctly:

```python
from typing import Any
from orchestrator.modules.actuators.custom_experiments import custom_experiment
from orchestrator.schema.property import ConstitutiveProperty

# Define your properties explicitly (or let ado infer from type annotations)
MyProperty = ConstitutiveProperty(...)

@custom_experiment(
    required_properties=[MyProperty, ...],
    optional_properties=[...],
    output_property_identifiers=["output1", "output2"],
    metadata={
        "description": "Clear description of what this experiment does"
    },
    parameterization={},
)
def my_custom_experiment(my_property: float, ...) -> dict[str, Any]:
    # Function parameters must match required/optional property identifiers
    return {"output1": ..., "output2": ...}
```

**Key Points:**

- Function **parameter names must match the property identifiers** — ado maps
  values to the function by name, not by position
- Positional parameters become required properties; keyword parameters become
  optional properties
- Type annotations on positional parameters allow ado to infer domains:
  `float` → continuous, `int` → discrete, `Literal` → categorical
- Return a `dict` whose keys include the `output_property_identifiers`
- Define `output_property_identifiers` for measurement results
- Include descriptive metadata

For the full decorator API and worked examples, see
[creating-custom-experiments.md](../../../website/docs/actuators/creating-custom-experiments.md).

---

## Testing Requirements

### Unit & Integration Test Location

Keep unit and integration tests **within the plugin package**,
not in the top-level `tests/` directory.

### Testing Checklist

Before considering a plugin complete, verify:

- **Plugin Installation**: Install the plugin into the top-level uv venv
from the repo root:

  ```bash
  uv pip install -e plugins/your_plugin_type/your_plugin
  ```

- **Confirm actuator or operator registration**:

Run

```
uv run ado get actuators --details
```

or

```
uv run ado get operators
```

and confirm the plugin is installed

- **Experiment execution**: Use the `run_experiment` tool to verify custom_experiment or actuator experiments can execute successfully

For example:

```
uv run run_experiment point.yaml
```

- **Valid DiscoverySpace YAML**: Create and validate a discoveryspace YAML that uses the experiment/actuator

  ```bash
  ado create discoveryspace -f space.yaml --dry-run
  ```

- **Valid Operation YAML**: Create and validate an operation YAML that uses the operator

  ```bash
  ado create operation -f operation.yaml --dry-run
  ```

- **Unit tests pass**: Run pytest on the plugin package

  ```bash
  uv run pytest plugins/your_plugin_type/your_plugin/tests/
  ```

### Example YAML Files

Include example YAML files in your plugin package that demonstrate:

- How to configure a discoveryspace with your actuator/experiment
- How to configure an operation with your operator
- Different use cases or configurations

---

## Linting

After making changes to plugin code, run linting at the plugin directory level:

```bash
cd plugins/actuators/your_plugin/
uv run black .
uv run ruff check --fix .
uv run tombi fmt .
```

Fix any issues that ruff cannot automatically resolve.

---

## Complete pyproject.toml Examples

### Actuator Example

```toml
[build-system]
requires = ["setuptools", "setuptools_scm"]
build-backend = "setuptools.build_meta"

[tool.setuptools_scm]
root = "../../../"

[tool.setuptools.packages.find]
where = ["."]
exclude = ["build", "build.*", "examples"]

[tool.setuptools.package-data]
my_actuator = ["actuator_definitions.yaml", "experiments.yaml"]

[project]
name = "my-actuator"
description = "Description of your actuator"
dynamic = ["version"]
dependencies = [
  "ado-core",
]
```

### Operator Example

```toml
[build-system]
requires = ["setuptools", "setuptools_scm"]
build-backend = "setuptools.build_meta"

[tool.setuptools_scm]
root = "../../../"

[project]
name = "my-operator"
dynamic = ["version"]
dependencies = [
  "ado-core",
]

[project.entry-points."ado.operators"]
my-operator = "my_operator.operator_function"
```

### Custom Experiment Example

```toml
[project]
name = "my-custom-experiment"
description = "Description of your custom experiment"
dynamic = ["version"]
dependencies = [
  "ado-core",
]

[project.entry-points."ado.custom_experiments"]
my_experiment = "my_package.my_experiment"

[build-system]
requires = ["setuptools", "setuptools_scm"]
build-backend = "setuptools.build_meta"

[tool.setuptools_scm]
root = "../../../"
```