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.

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.
study_name	str | None	Optional; The name of the study.
storage	str | None	Optional; The storage URI to save the optimisation results to.

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.
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.

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.