Plugin

Operator

Base operator class for LightlyStudio plugins.

BaseOperator

Bases: ABC

Base class for all operators.

description abstractmethod property

description: str

Return the description of the operator.

error_message class-attribute instance-attribute

error_message: str = ''

Human-readable error description set when status is ERROR.

name abstractmethod property

name: str

Return the operator name.

parameters abstractmethod property

parameters: list[BaseParameter]

Return the list of parameters this operator expects.

status class-attribute instance-attribute

status: OperatorStatus = PENDING

Current lifecycle status of the operator.

supported_scopes abstractmethod property

supported_scopes: list[OperatorScope]

Return the list of scopes this operator can be triggered from.

Determines where in the UI the operator is surfaced. OperatorScope.ROOT targets dataset/root collections.

execute abstractmethod

execute(
    *, session: Session, context: ExecutionContext, parameters: dict[str, Any]
) -> OperatorResult

Execute the operator with the given parameters.

Parameters:

Name	Type	Description	Default
session	Session	Database session.	required
context	ExecutionContext	Execution context containing collection_id and optional filter.	required
parameters	dict[str, Any]	Parameters passed to the operator.	required

Returns:

Type	Description
OperatorResult	An OperatorResult with success flag and message.

shutdown

shutdown() -> None

Stop the operator and release resources.

Called during application shutdown. Override this in operators that spawned subprocesses or allocated resources in startup().

startup

startup() -> None

Start the operator.

Called by LightlyStudio after registration. Override this in operators that need setup work (venv creation, model download, server subprocess, etc.).

Simple operators that run purely in-process do not need to override this — the default sets status to READY without any additional setup.

Scope definitions for operator execution.

AnyFilter module-attribute

AnyFilter = Union[
    ImageFilter, VideoFrameFilter, VideoFilter, AnnotationsFilter, GroupFilter, SampleFilter, None
]

Scope definitions for operator execution.

ExecutionContext dataclass

ExecutionContext(collection_id: UUID, context_filter: AnyFilter = None)

Contextual data passed to BaseOperator.execute().

filter=None means the whole collection, while a non-null filter restricts the target samples.

Scope definitions for operator execution.

OperatorScope

Bases: str, Enum

Scope in which an operator can be triggered.

Operators declare which scopes they support via BaseOperator.supported_scopes. The UI uses this to surface operators contextually by media type.

ANNOTATION class-attribute instance-attribute

ANNOTATION = 'annotation'

Operate on annotations.

CAPTION class-attribute instance-attribute

CAPTION = 'caption'

Operate on captions.

GROUP class-attribute instance-attribute

GROUP = 'group'

Operate on groups.

IMAGE class-attribute instance-attribute

IMAGE = 'image'

Operate on images.

ROOT class-attribute instance-attribute

ROOT = 'root'

Operate on the root collection (dataset-level).

VIDEO class-attribute instance-attribute

VIDEO = 'video'

Operate on videos.

VIDEO_FRAME class-attribute instance-attribute

VIDEO_FRAME = 'video_frame'

Operate on video frames.

Parameter

Parameter for operators for LightlyStudio plugins.

BaseParameter dataclass

BaseParameter(
    name: str,
    description: str = "",
    default: Any = None,
    required: bool = True,
    param_type: str | None = None,
)

Bases: ABC

Base parameter definition shared across operator parameters.

__post_init__

__post_init__() -> None

Run value validation once the dataclass is initialized.

BoolParameter dataclass

BoolParameter(
    name: str,
    description: str = "",
    default: Any = None,
    required: bool = True,
    param_type: str | None = None,
)

Bases: BuiltinParameter[bool]

Represents a boolean operator parameter.

__post_init__

__post_init__() -> None

Set up type information and validate default value.

BuiltinParameter dataclass

BuiltinParameter(
    name: str,
    description: str = "",
    default: Any = None,
    required: bool = True,
    param_type: str | None = None,
)

Bases: BaseParameter, Generic[T]

Represents a built-in operator parameter.

__post_init__

__post_init__() -> None

Set up type information and validate default value.

FloatParameter dataclass

FloatParameter(
    name: str,
    description: str = "",
    default: Any = None,
    required: bool = True,
    param_type: str | None = None,
)

Bases: BuiltinParameter[float]

Represents a float operator parameter.

__post_init__

__post_init__() -> None

Set up type information and validate default value.

IntParameter dataclass

IntParameter(
    name: str,
    description: str = "",
    default: Any = None,
    required: bool = True,
    param_type: str | None = None,
)

Bases: BuiltinParameter[int]

Represents an integer operator parameter.

__post_init__

__post_init__() -> None

Set up type information and validate default value.

StringParameter dataclass

StringParameter(
    name: str,
    description: str = "",
    default: Any = None,
    required: bool = True,
    param_type: str | None = None,
)

Bases: BuiltinParameter[str]

Represents a string operator parameter.

__post_init__

__post_init__() -> None

Set up type information and validate default value.