Skip to content

schemas

Provides schemas used in Plugboard.

This includes:

  • Pydantic models for specifying Plugboard objects;
  • TypeDict definitions for constructor **kwargs.

Direction module-attribute 

Direction = Literal['min', 'max']

A type for the direction of optimisation.

ParameterSpec module-attribute 

ParameterSpec = Union[
    FloatParameterSpec,
    IntParameterSpec,
    CategoricalParameterSpec,
]

A union type for all parameter specifications.

CategoricalParameterSpec

Bases: BaseFieldSpec

Specification for a categorical parameter.

See: https://docs.ray.io/en/latest/tune/api/search_space.html.

Attributes:

Name Type Description
type Literal['ray.tune.choice']

The type of the parameter.
categories list[Any]

The categories of the parameter.

ComponentArgsDict

Bases: TypedDict

TypedDict of the Component constructor arguments.

ComponentArgsSpec

Bases: PlugboardBaseModel

Specification of the Component constructor arguments.

Attributes:

Name Type Description
name str

The name of the Component.
initial_values dict[str, Any]

Initial values for the Component.
parameters dict[str, Any]

Parameters for the Component.
constraints dict[str, Any]

Constraints for the Component.
resources Resource | None

Resource requirements for the Component.

ComponentSpec

Bases: PlugboardBaseModel

Specification of a Component.

Attributes:

Name Type Description
type str

The type of the Component.
args ComponentArgsSpec

The arguments for the Component.

ConfigSpec

Bases: PlugboardBaseModel

Configuration for a Plugboard simulation.

Attributes:

Name Type Description
plugboard ProcessConfigSpec

A ProcessConfig that specifies the Plugboard Process.

ConnectorBuilderArgsDict

Bases: TypedDict

TypedDict of the Connector constructor arguments.

ConnectorBuilderArgsSpec

Bases: PlugboardBaseModel

Specification of the Connector constructor arguments.

Attributes:

Name Type Description
parameters dict[str, Any]

Parameters for the Connector.

ConnectorBuilderSpec

Bases: PlugboardBaseModel

Specification of a ConnectorBuilder.

Attributes:

Name Type Description
type str

The type of the ConnectorBuilder.
args ConnectorBuilderArgsSpec

Optional; The arguments for the ConnectorBuilder.

ConnectorMode

Bases: StrEnum

Defines the mode of a connector.

Attributes:

Name Type Description
PIPELINE

one-in-one-out task queue.
PUBSUB

one-to-many event distribution.

ConnectorSocket

Bases: PlugboardBaseModel

ConnectorSocket defines a source or target connection point on a Connector.

There are two typical types of connections in use: those between attributes of components; and those connecting components with events which they either emit or consume. When connecting two component attributes together, the entity is the name of the component, and the descriptor is the name of the attribute. When connecting components with events, the entity is the name of the event, and the descriptor is either "publishers" or "subscribers" as appropriate.

Attributes:

Name Type Description
entity str

The name of the entity.
descriptor str

The name of the descriptor on the entity.

id property 

id: str

Unique ID for ConnectorSocket.

connects_to 

connects_to(entities: Container[str]) -> bool

Returns True if the ConnectorSocket connects to any of the named entities.

from_ref classmethod 

from_ref(ref: str) -> _t.Self

Creates a ConnectorSocket from a reference string.

ConnectorSpec

Bases: PlugboardBaseModel

ConnectorSpec defines a connection between two entities.

Attributes:

Name Type Description
source ConnectorSocket

The source endpoint.
target ConnectorSocket

The target endpoint.
mode ConnectorMode

The mode of the connector.

id property 

id: str

Unique ID for ConnectorSpec.

Entity

Bases: StrEnum

Entity names.

id_prefix property 

id_prefix: str

Returns prefix for generating unique entity ids.

id_regex property 

id_regex: str

Returns regex for validating entity ids.

FloatParameterSpec

Bases: BaseFieldSpec

Specification for a uniform float parameter.

See: https://docs.ray.io/en/latest/tune/api/search_space.html.

Attributes:

Name Type Description
type Literal['ray.tune.uniform']

The type of the parameter.
lower float

The lower bound of the parameter.
upper float

The upper bound of the parameter.

IODirection

Bases: StrEnum

IODirection defines the type of IO operation.

Attributes:

Name Type Description
INPUT

Specifies an input to a Component.
OUTPUT

Specifies an output to a Component.

IntParameterSpec

Bases: BaseFieldSpec

Specification for a uniform integer parameter.

See: https://docs.ray.io/en/latest/tune/api/search_space.html.

Attributes:

Name Type Description
type Literal['ray.tune.randint']

The type of the parameter.
lower int

The lower bound of the parameter.
upper int

The upper bound of the parameter.

ObjectiveSpec

Bases: BaseFieldSpec

Specification for an objective field.

OptunaSpec

Bases: PlugboardBaseModel

Specification for the Optuna configuration.

See: https://docs.ray.io/en/latest/tune/api/doc/ray.tune.search.optuna.OptunaSearch.html and https://optuna.readthedocs.io/en/stable/reference/index.html for more information on the Optuna configuration.

Attributes:

Name Type Description
type Literal['ray.tune.search.optuna.OptunaSearch']

The algorithm type to load.
space str | None

Optional; A function defining the search space. Use this to define more complex search spaces that cannot be represented using the built-in parameter types. The function must accept a trial argument. If it also accepts a spec argument, the ProcessSpec will be passed to it.
study_name str | None

Optional; The name of the study.
storage str | None

Optional; The storage URI to save the optimisation results to.
points_to_evaluate list[dict[str, Any]] | None

Optional; A list of initial parameter configurations to evaluate first. Each entry is a dict mapping parameter full names to values. Useful for providing a warm start when exploring large or heavily constrained search spaces.

PlugboardBaseModel

Bases: BaseModel, ABC

Custom base model for Plugboard schemas.

ProcessArgsDict

Bases: TypedDict

TypedDict of the Process constructor arguments.

ProcessArgsSpec

Bases: PlugboardBaseModel

Specification of the Process constructor arguments.

Attributes:

Name Type Description
components Annotated[list[ComponentSpec], Len(min_length=1)]

Specifies each Component in the Process.
connectors list[ConnectorSpec]

Specifies the connections between each Component.
name Optional[str]

Unique identifier for Process.
parameters dict[str, Any]

Parameters for the Process. These will be shared across all Component objects within the Process.
state StateBackendSpec

Optional; Specifies the StateBackend used for the Process.

ProcessConfigSpec

Bases: PlugboardBaseModel

A ProcessSpec within a Plugboard configuration.

Attributes:

Name Type Description
process ProcessSpec

A ProcessSpec that specifies the process, or a path to a YAML file containing the process specification.
tune TuneSpec | None

Optional; A TuneSpec that specifies an optimisation configuration.

ProcessSpec

Bases: PlugboardBaseModel

Specification of a Plugboard Process.

Attributes:

Name Type Description
args ProcessArgsSpec

The arguments for the Process.
type Literal['plugboard.process.LocalProcess', 'plugboard.process.RayProcess']

The type of Process to build.
connector_builder ConnectorBuilderSpec

The ConnectorBuilder to use for the Process.

override_process_type 

override_process_type(
    process_type: Literal["local", "ray"],
) -> Self

Override the process type and update connector/state to be compatible.

Parameters:

Name Type Description Default
process_type Literal['local', 'ray']

The process type to use ("local" or "ray")

 required

Returns:

Type Description
Self

A new ProcessSpec with the overridden process type and compatible settings

Resource

Bases: PlugboardBaseModel

Resource requirements for a component.

Supports specification of CPU, GPU, memory, and custom resources. Values can be specified as numbers or strings with units (e.g., "250m" for 0.25, "10Mi" for 10 * 1024 * 1024).

Attributes:

Name Type Description
cpu float

CPU requirement (default: 0.001).
gpu float

GPU requirement (default: 0).
memory int

Memory requirement in bytes as an integer (default: 0).
resources dict[str, float]

Custom resource requirements as a dictionary.

to_ray_options 

to_ray_options(
    style: Literal["actor", "placement_group"] = "actor",
) -> dict[str, _t.Any]

Convert resource requirements to Ray actor options.

Returns:

Type Description
dict[str, Any]

Dictionary of Ray actor options.

StateBackendArgsDict

Bases: TypedDict

TypedDict of the StateBackend constructor arguments.

StateBackendArgsSpec

Bases: PlugboardBaseModel

Specification of the StateBackend constructor arguments.

Attributes:

Name Type Description
job_id Optional[str]

The unique id for the job.
metadata dict[str, Any]

Metadata for a run.

StateBackendSpec

Bases: PlugboardBaseModel

Specification of a Plugboard StateBackend.

Attributes:

Name Type Description
type str

The type of the StateBackend.
args StateBackendArgsSpec

The arguments for the StateBackend.

Status

Bases: StrEnum

Status describes the status of either a Component or a Process.

Attributes:

Name Type Description
CREATED

The Component or Process has been created but not yet started.
INIT

The Component or Process has been initialised but has not started running.
RUNNING

The Component or Process is currently running.
WAITING

The Component or Process is waiting for input.
COMPLETED

The Component or Process has completed successfully.
FAILED

The Component or Process has failed.
STOPPED

The Component or Process has been cancelled or stopped.

is_terminal property 

is_terminal: bool

Returns whether the status is terminal.

TuneArgsDict

Bases: TypedDict

TypedDict of the Tuner constructor arguments.

TuneArgsSpec

Bases: PlugboardBaseModel

Specification of the arguments for the Tune class.

Attributes:

Name Type Description
objective ObjectiveSpec | list[ObjectiveSpec]

The location of the objective(s) to optimise for in the Process.
parameters list[ParameterSpec]

The parameters to optimise over.
num_samples PositiveInt

The number of samples to draw during the optimisation.
mode Direction | list[Direction]

The mode of optimisation. For multi-objective optimisation, this should be a list containing a direction for each objective.
max_concurrent PositiveInt | None

The maximum number of concurrent trials.
algorithm Union[OptunaSpec]

The algorithm to use for the optimisation.

TuneSpec

Bases: PlugboardBaseModel

Configuration for an optimisation job.

Attributes:

Name Type Description
args TuneArgsSpec

The arguments for the Tune job.

simple_cycles 

simple_cycles(
    graph: dict[str, set[str]],
) -> Generator[list[str], None, None]

Find all simple cycles in a directed graph using Johnson's algorithm.

Parameters:

Name Type Description Default
graph dict[str, set[str]]

A dictionary mapping each vertex to a set of its neighbours.

 required

Yields:

Type Description
list[str]

Each elementary cycle as a list of vertices.

validate_all_inputs_connected 

validate_all_inputs_connected(
    process_dict: dict[str, Any],
) -> list[str]

Check that all component inputs are connected.

Parameters:

Name Type Description Default
process_dict dict[str, Any]

The output of process.dict(). Uses the "components" and "connectors" keys.

 required

Returns:

Type Description
list[str]

List of error messages for unconnected inputs.

validate_input_events 

validate_input_events(
    process_dict: dict[str, Any],
) -> list[str]

Check that all components with input events have a matching output event producer.

Parameters:

Name Type Description Default
process_dict dict[str, Any]

The output of process.dict(). Uses the "components" key.

 required

Returns:

Type Description
list[str]

List of error messages for unmatched input events.

validate_no_unresolved_cycles 

validate_no_unresolved_cycles(
    process_dict: dict[str, Any],
) -> list[str]

Check for circular connections that are not resolved by initial values.

Circular loops are only valid if there are initial_values set on an appropriate component input within the loop.

Parameters:

Name Type Description Default
process_dict dict[str, Any]

The output of process.dict(). Uses the "components" and "connectors" keys.

 required

Returns:

Type Description
list[str]

List of error messages for unresolved circular connections.

validate_process 

validate_process(process_dict: dict[str, Any]) -> list[str]

Run all registered validators against the given process.

New validators are picked up automatically via the @validator decorator; this function never needs to be modified directly.

validator 

validator(func: _Fn) -> _Fn

Decorator: register func as a process validator.

Validators are called in registration order when validate_process is invoked. Raise an exception inside the validator to signal an invalid process.

Example::

@validator
def check_no_cycles(connectors: ConnectorMap) -> None:
    if cycles := _find_cycles(connectors):
        raise ValueError(f"Cycle detected involving: {cycles}")