Plugins

function CODE_FIELD

def CODE_FIELD(language: str, title: str | None = None, description: str | None = None, default: Any = ...) -> Any:

Create a Pydantic Field rendered as a code editor.

The value is a plain string; syntax highlighting is presentation only, so the plugin stays responsible for validating what the user typed.

Parameters:

• language str — Language id used for highlighting, as understood by the frontend’s editor — for example "sql", "python", "json", "yaml" or "xml". An unknown id degrades to plain text.
• title str | None — Optional UI title for the field.
• description str | None — Optional UI help text for the field.
• default Any — Default value, or ... to make the field required.

Source

def CODE_FIELD(
    *,
    language: str,
    title: str | None = None,
    description: str | None = None,
    default: Any = ...,
) -> Any:
    """Create a Pydantic `Field` rendered as a code editor.

    The value is a plain string; syntax highlighting is presentation only, so the
    plugin stays responsible for validating what the user typed.

    Args:
        language: Language id used for highlighting, as understood by the
            frontend's editor -- for example `"sql"`, `"python"`, `"json"`,
            `"yaml"` or `"xml"`. An unknown id degrades to plain text.
        title: Optional UI title for the field.
        description: Optional UI help text for the field.
        default: Default value, or `...` to make the field required.
    """
    return Field(
        default=default,
        title=title,
        description=description,
        json_schema_extra={"x-ui-meta": {"type": "code", "language": language}},
    )

function COMPUTED_SELECTION

def COMPUTED_SELECTION(title: str | None = None, description: str | None = None, provider: str, depends_on: list[str] | None = None, default: Any = ...):

Create a Pydantic Field for a UI selection computed by a provider.

Parameters:

• title str | None — Optional UI title for the field.
• description str | None — Optional UI help text for the field.
• provider str — The name (ID) of the provider function used by the frontend to compute the available options.
• depends_on list[str] | None — Optional list of field names this selection depends on.
• default Any — Default value, or ... to make the field required.

Source

def COMPUTED_SELECTION(
    *,
    title: str | None = None,
    description: str | None = None,
    provider: str,
    depends_on: list[str] | None = None,
    default: Any = ...,
):
    """Create a Pydantic `Field` for a UI selection computed by a provider.

    Args:
        title: Optional UI title for the field.
        description: Optional UI help text for the field.
        provider: The name (ID) of the provider function used by the frontend to compute the available options.
        depends_on: Optional list of field names this selection depends on.
        default: Default value, or `...` to make the field required.

    """
    meta = {
        "type": "computed_select",
        "provider": provider,
        "dependsOn": depends_on or [],
    }

    return Field(
        default=default,
        title=title,
        description=description,
        json_schema_extra={"x-ui-meta": meta},
    )

function OCEL_FIELD

def OCEL_FIELD(field_type: Literal['object_type', 'event_type', 'event_id', 'object_id', 'event_attribute', 'object_attribute', 'time_frame', 'e2o_qualifier', 'o2o_qualifier'], ocel_id: str, theme: Literal['standard', 'r4pm'] = 'standard', default_frequency: float | None = None, title: str | None = None, description: str | None = None) -> Any:

Create a Pydantic Field with Ocelescope UI metadata for OCEL-based inputs.

Parameters:

• field_type Literal['object_type', 'event_type', 'event_id', 'object_id', 'event_attribute', 'object_attribute', 'time_frame', 'e2o_qualifier', 'o2o_qualifier'] — What kind of OCEL field the user should select (e.g. "event_attribute" or "object_type").
• ocel_id str — Identifier/name of the OCEL input this field depends on.
• default — Default value, or ... to make the field required.
• title str | None — Optional UI title for the field.
• description str | None — Optional UI help text for the field.

Source

def OCEL_FIELD(
    *,
    field_type: Literal[
        "object_type",
        "event_type",
        "event_id",
        "object_id",
        "event_attribute",
        "object_attribute",
        "time_frame",
        "e2o_qualifier",
        "o2o_qualifier",
    ],
    ocel_id: str,
    theme: Literal["standard", "r4pm"] = "standard",
    default_frequency: float | None = None,
    title: str | None = None,
    description: str | None = None,
) -> Any:
    """Create a Pydantic `Field` with Ocelescope UI metadata for OCEL-based inputs.

    Args:
        field_type: What kind of OCEL field the user should select (e.g.
            `"event_attribute"` or `"object_type"`).
        ocel_id: Identifier/name of the OCEL input this field depends on.
        default: Default value, or `...` to make the field required.
        title: Optional UI title for the field.
        description: Optional UI help text for the field.
    """
    extra: dict[str, Any] = {
        "type": "ocel",
        "field_type": field_type,
        "ocel_id": ocel_id,
        "theme": theme,
        "default_frequency": default_frequency,
    }

    return Field(
        title=title,
        description=description,
        json_schema_extra={"x-ui-meta": extra},
    )

function SLIDER_FIELD

def SLIDER_FIELD(min: float, max: float, step: float | None = None, marks: list[float] | None = None, title: str | None = None, description: str | None = None, default: Any = ...) -> Any:

Create a Pydantic Field rendered as a slider.

min and max become real ge/le constraints, not just UI bounds, so a value outside the range is rejected on validation rather than only being unreachable by dragging.

Annotate the field as int to get whole-number steps, or float for fractional ones.

Parameters:

• min float — Lowest selectable value.
• max float — Highest selectable value.
• step float | None — Increment between selectable values. Defaults to 1 for int fields and to a hundredth of the range for float fields.
• marks list[float] | None — Optional values to label on the track.
• title str | None — Optional UI title for the field.
• description str | None — Optional UI help text for the field.
• default Any — Default value, or ... to make the field required.

Source

def SLIDER_FIELD(
    *,
    min: float,
    max: float,
    step: float | None = None,
    marks: list[float] | None = None,
    title: str | None = None,
    description: str | None = None,
    default: Any = ...,
) -> Any:
    """Create a Pydantic `Field` rendered as a slider.

    `min` and `max` become real `ge`/`le` constraints, not just UI bounds, so a
    value outside the range is rejected on validation rather than only being
    unreachable by dragging.

    Annotate the field as `int` to get whole-number steps, or `float` for
    fractional ones.

    Args:
        min: Lowest selectable value.
        max: Highest selectable value.
        step: Increment between selectable values. Defaults to 1 for `int`
            fields and to a hundredth of the range for `float` fields.
        marks: Optional values to label on the track.
        title: Optional UI title for the field.
        description: Optional UI help text for the field.
        default: Default value, or `...` to make the field required.
    """
    meta: dict[str, Any] = {"type": "slider", "min": min, "max": max}

    if step is not None:
        meta["step"] = step
    if marks:
        meta["marks"] = marks

    return Field(
        default=default,
        title=title,
        description=description,
        ge=min,
        le=max,
        json_schema_extra={"x-ui-meta": meta},
    )

function SQL_FIELD

def SQL_FIELD(title: str | None = None, description: str | None = None, default: Any = ...) -> Any:

Create a Pydantic Field rendered as a SQL editor.

Shorthand for CODE_FIELD(language="sql").

Parameters:

• title str | None — Optional UI title for the field.
• description str | None — Optional UI help text for the field.
• default Any — Default value, or ... to make the field required.

Source

def SQL_FIELD(
    *,
    title: str | None = None,
    description: str | None = None,
    default: Any = ...,
) -> Any:
    """Create a Pydantic `Field` rendered as a SQL editor.

    Shorthand for `CODE_FIELD(language="sql")`.

    Args:
        title: Optional UI title for the field.
        description: Optional UI help text for the field.
        default: Default value, or `...` to make the field required.
    """
    return CODE_FIELD(
        language="sql",
        title=title,
        description=description,
        default=default,
    )

class OCELAnnotation

class OCELAnnotation(Annotation):

UI annotation metadata for an OCEL-typed parameter or result.

In addition to the base Annotation fields, this annotation may specify an OCEL extension. To keep the annotation JSON-serializable and stable for frontend consumption, the constructor accepts an OCELExtension class and coerces it to its class name (a string).

Attributes:

• label str — Human-readable label to display in the UI.
• description str | None — Optional longer text shown in the UI to explain the OCEL.

Source

@dataclass
class OCELAnnotation(Annotation):
    """UI annotation metadata for an `OCEL`-typed parameter or result.

    In addition to the base `Annotation` fields, this annotation may specify an
    OCEL extension. To keep the annotation JSON-serializable and stable for
    frontend consumption, the constructor accepts an `OCELExtension` class and
    coerces it to its class name (a string).

    Attributes:
        label: Human-readable label to display in the UI.
        description: Optional longer text shown in the UI to explain the OCEL.
    """

class Plugin

class Plugin(ABC):

Source

class Plugin(ABC):
    version: ClassVar[str]
    label: ClassVar[str]
    description: ClassVar[str | None] = None

    @classmethod
    def get_name(cls):
        return cls.__name__

    @classmethod
    def method_map(cls) -> dict[str, PluginMethod]:
        method_map: dict[str, PluginMethod] = {}
        for _, method in inspect.getmembers(cls, predicate=inspect.isfunction):
            method_meta = getattr(method, "__meta__", None)

            if not isinstance(method_meta, PluginMethod):
                continue

            method_map[method_meta.name] = method_meta

        return method_map

    @classmethod
    def get_resources(cls) -> list[type[Resource]]:
        return list(
            dict.fromkeys(
                resource_type
                for method_meta in cls.method_map().values()
                for io_element in [*method_meta.inputs, *method_meta.outputs]
                for resource_type in io_element.resource_types
            )
        )

class PluginInput

class PluginInput(ABC, BaseModel):

Source

class PluginInput(ABC, BaseModel):
    pass

class PluginMethod

class PluginMethod:

Source

@dataclass
class PluginMethod:
    name: str
    label: str
    method: Callable[..., PluginReturnType]
    description: str | None
    inputs: list[PluginIO] = field(default_factory=list)
    outputs: list[PluginIO] = field(default_factory=list)
    configuration_input: type[PluginInput] | None = None

    def bind(self, plugin: "Plugin") -> Callable[..., PluginReturnType]:
        """Bind this method to a plugin instance.

        `method` is captured while the class body is still executing, so it is a
        plain function that still expects `self`. Binding it to `plugin` yields the
        callable a plugin run actually needs.
        """
        return MethodType(self.method, plugin)

function bind

def bind(plugin: Plugin) -> Callable[..., PluginReturnType]:

Bind this method to a plugin instance.

method is captured while the class body is still executing, so it is a plain function that still expects self. Binding it to plugin yields the callable a plugin run actually needs.

Source

    def bind(self, plugin: "Plugin") -> Callable[..., PluginReturnType]:
        """Bind this method to a plugin instance.

        `method` is captured while the class body is still executing, so it is a
        plain function that still expects `self`. Binding it to `plugin` yields the
        callable a plugin run actually needs.
        """
        return MethodType(self.method, plugin)

class ResourceAnnotation

class ResourceAnnotation(Annotation):

UI annotation metadata for a Resource-typed parameter or result.

This annotation is used to provide frontend-facing text (label/description) for resources.

Attributes:

• label str — Human-readable label to display in the UI.
• description str | None — Optional longer text shown in the UI to explain the resource.
• annotation_resources list[type[Resource]] | None — Further resource types this input accepts, registered alongside the declared one.

Source

@dataclass
class ResourceAnnotation(Annotation):
    """UI annotation metadata for a `Resource`-typed parameter or result.

    This annotation is used to provide frontend-facing text (label/description)
    for resources.

    Attributes:
        label: Human-readable label to display in the UI.
        description: Optional longer text shown in the UI to explain the resource.
        annotation_resources: Further resource types this input accepts, registered
            alongside the declared one.
    """

    annotation_resources: list[type[Resource]] | None = None

function plugin_method

def plugin_method(label: str | None = None, description: str | None = None):

Decorator that marks a plugin class method as an Ocelescope runnable function.

Parameters:

• label str | None — Human-readable label shown in the UI for the method. If not provided, the UI may fall back to the Python method name.
• description str | None — Human-readable description shown in the UI for the method.

Source

def plugin_method(
    label: str | None = None,
    description: str | None = None,
):
    """Decorator that marks a plugin class method as an Ocelescope runnable function.

    Args:
        label: Human-readable label shown in the UI for the method. If not provided,
            the UI may fall back to the Python method name.
        description: Human-readable description shown in the UI for the method.

    """

    def decorator(func: Callable[..., PluginReturnType]):
        plugin_method_meta = PluginMethod(
            name=func.__name__,  # ty: ignore[unresolved-attribute]
            label=label or func.__name__,  # ty: ignore[unresolved-attribute]
            description=description,
            method=func,
        )

        for key, value in get_type_hints(func, include_extras=True).items():
            if key == "return":
                return_origin = get_origin(value)

                types_to_parse = []

                if return_origin is tuple:
                    types_to_parse = get_args(value)
                else:
                    types_to_parse = [value]

                plugin_method_meta.outputs = [
                    PluginIO("", return_item) for return_item in types_to_parse
                ]

            elif isinstance(base_type := extract_info(value)[0], type) and issubclass(
                base_type, PluginInput
            ):
                plugin_method_meta.configuration_input = value
            else:
                plugin_method_meta.inputs += [PluginIO(name=key, io_type=value)]

        setattr(func, "__meta__", plugin_method_meta)  # noqa: B010

        return func

    return decorator